{"versionId":"058978a8-0213-44eb-0294-08dccaef2767","articleId":"e73fd26a-64e4-4251-bd28-08dbbfa3c1d9","title":"Form API Request Response Format","tags":["API","forms","technical","integrations","All articles"],"content":"

With Helpfruit Forms, an API request can send data back to the bot and display this information in chat.

\n\n

\n
\n

In this article

\n\n
\n

Response types

\n

Several different response types are possible:

\n\n

Top level response format

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequired?OptionsExample
statusstringyessuccess|failuresuccess
statusCodestringyes-1 (Failure) |1 (Success)1
messageTypestringyes\n

\"AdaptiveCard\" | \"Text\"

\n		\n

Text

\n
messagestringyes \n

This is my message

\n

This __is__ my message

\n

This has a (link)[https://faqbot.ai]

\n
attachmentsarray(Attachments)nosee belowsee below
\n

 

\n

Message Type

\n

Adaptive card allows for parsing the message string as an adaptive card serialized to string format vs a bot framework format. Please contact us for details on what is supported.

\n

The serialized adaptive card is placed in the \"message\" field.

\n

Text is used for all other message types, i.e. simple text, markdown, message with buttons

\n

 

\n

Example API response: simple message

\n

\n
\nView code for this example\n
{\n\"status\": \"success\",\n\"statusCode\": 1,\n\"messageType\": \"Text\",\n\"message\": \"The weather today is nice and sunny\"\n}
\n
\n

 

\n

Example API response: markdown format

\n

\n
\nView code for this example\n
{\n\"status\": \"success\",\n\"statusCode\": 1,\n\"messageType\": \"Text\",\n\"message\": \"The weather today is **nice** and sunny click [here](https://weather.com/city/auckland) for more information\"\n}
\n
\n

 

\n

Attachment format

\n

Helpfruit supports different types of button attachments in API responses. This allows users to quickly and easily take a follow-up action - eg get more information or go to a specific web page.

\n

All button attachments include the following field: attachmentType: 0

\n

Types of button

\n

Response button

\n\n

Custom action button

\n

These buttons can also set context via the action field. This can be used by the API to set IDs, authentication information, or other information that is needed in subsequent forms.

\n\n

Open url button

\n\n

 

\n

Example - API response with button attachments

\n

\n
\nView code for this example\n
{\n\"status\": \"success\",\n\"statusCode\": 1,\n\"messageType\": \"Text\",\n\"message\": \"The weather today is **nice** and sunny click [here](https://weather.com/city/auckland) for more information\",\n\"attachments\": [\n  {\n    \"type\": 0,\n    \"displayText\": \"Weather radar\",\n    \"replyText\": \"Show me the weather radar\"\n  },\n  {\n    \"type\": 0,\n    \"displayText\": \"Weather warnings\",\n  },\n  {\n    \"type\": 0,\n    \"displayText\": \"Open home page\",\n    \"url\": \"https://weather.com\"\n  }\n]\n}
\n
\n

 

\n

Custom action format

\n

Within the button attachment, custom actions can be specified, to allow selected actions to be triggered in the bot via the button shown to the user.  

\n

See custom actions documentation for more details on available actions.

\n

Custom action formats

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequired?OptionsExampleNotes
typeNumberY\n

3 (Trigger Form)

\n

5 (Trigger Engagement By Event Name)

\n		\n

3

\n

5

\n		See value field format table
valueStringYSee value field format table\n

calculator=c53fe92a-8362-463e-94eb-06f13fa3fc13

\n

newsletter-signup

\n		See value field format table
contextObjectN \n

{

\n

\"contextKey\": \"contextValue\",

\n

\"name\": \"Clementine\"

\n

}

\n		\n

These fields need to first be added as bot context keys.

\n

Setting context allows for storing information that can be used by subsequent forms without having to ask the user, eg store a Sales Order number.

\n

Context is also displayed in live chat and conversation history - so you can attach identifiers to buttons and have that context visible in the portal (eg a marketing campaign ID).

\n

The context is only set when the button is clicked.

Learn more about setting up context

\n
\n

 

\n

Custom actions: value field format by type

\n

The format of the value field that must be used for each custom action type is shown below.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TypeActionValue field formatExample of value field
3Trigger a formcalculator=FORM_ID_GUIDcalculator=c53fe92a-8362-463e-94eb-06f13fa3fc13
5Trigger an engagement by event nameEVENT_NAMEnewsletter-signup
\n

 

\n

Example: API response with custom actions

\n

\n
\nView code for this example\n
{\n\"status\": \"success\",\n\"statusCode\": 1,\n\"messageType\": \"Text\",\n\"message\": \"The weather today is **nice** and sunny click [here](https://weather.com/city/auckland) for more information\",\n\"attachments\": [\n      {\n        \"type\": 0, // Button\n        \"displayText\": \"Signup to newsletter\", \n        \"action\":\n        {\n          \"type\": 5, // Trigger page event\n          \"value\": \"newsletter-signup\"\n        }\n      },\n      {\n        \"type\": 0, // Button\n        \"displayText\": \"Contact us\", \n        \"action\":\n        {\n          \"type\": 3, // Activate form\n          \"value\": \"calculator=c53fe92a-8362-463e-94eb-06f13fa3fc13\"\n        }\n      }\n    ]\n}
\n
\n

 

\n

Example API host (in NodeJS) to test message responses

\n

A simple node js web server to handle API requests and respond back with some examples.

\n\n
const http = require(\"http\");\nconst url = require(\"url\");\n\nconst requestListener = function (req, res) {\n  const parsed = url.parse(req.url, true); // Parse URL with query string\n\n  const examples = {\n    1: {\n      status: \"success\",\n      statusCode: 1,\n      messageType: \"Text\",\n      message: \"The weather today is nice and sunny\",\n    },\n    2: {\n      status: \"success\",\n      statusCode: 1,\n      messageType: \"Text\",\n      message: \"The weather today is **nice** and sunny click [here](https://weather.com/city/auckland) for more information\",\n    },\n    3: {\n      status: \"success\",\n      statusCode: 1,\n      messageType: \"Text\",\n      message: \"The weather today is **nice** and sunny click [here](https://weather.com/city/auckland) for more information\",\n      attachments: [\n        {\n          type: 0,\n          displayText: \"Weather radar\",\n          replyText: \"Show me the weather radar\",\n        },\n        {\n          type: 0,\n          displayText: \"Weather warnings\",\n        },\n        {\n          type: 0,\n          displayText: \"Open home page\",\n          url: \"https://weather.com\",\n        },\n      ],\n    },\n    4: {\n      status: \"success\",\n      statusCode: 1,\n      messageType: \"Text\",\n      message: `✅ We have found your order number: **${parsed.query.orderId}**`,\n      attachments: [\n        {\n          type: 0, // Button\n          displayText: \"\uD83D\uDCDD - View order\",\n          url: `https://store.com?order=${parsed.query.orderId}&email=${parsed.query.email}`,\n        },\n        {\n          type: 0, // Button\n          displayText: \"Contact us\",\n          action: {\n            type: 3, // Activate form\n            value: \"calculator=c11fe92a-4444-555e-11aa-06f13fa3f123,\n            context: {\n                 \"userName\": \"Clementine Citrus\",\n                  \"contactMethod\": \"apiResponse\"\n             },\n          },\n        },\n      ],\n    },\n  };\n\n  if (parsed.query.ex && examples[parsed.query.ex]) {\n    res.setHeader(\"Content-Type\", \"application/json\");\n    res.writeHead(200);\n    res.end(JSON.stringify(examples[parsed.query.ex]));\n  } else {\n    res.writeHead(200);\n    res.end(\"<html><body<div>test</div></body></html>\");\n  }\n};\n\nconst host = \"localhost\";\nconst port = 9001;\n\nconst server = http.createServer(requestListener);\nserver.listen(port, host, () => {\n  console.log(`Server is running on http://${host}:${port}`);\n});\n
","description":"","isMarkdown":false,"publishedOnUtc":"2024-09-04T21:59:17.0801798","modifiedOnUtc":"2023-10-03T00:40:21.296286"}