Form API Request Response Format

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

• This can be useful when calling out to external APIs to get additional live information.
• For example, your customer can interact with the bot to get information about their shipment or other personalized information:

Response types

Several different response types are possible:

• Simple text response written back to the bot
• Markdown formatted response
• Messages with buttons
• Adaptive cards - allowing for a highly configurable card layout

Top level response format

Message Type

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.

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

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

Example API response: simple message

{
"status": "success",
"statusCode": 1,
"messageType": "Text",
"message": "The weather today is nice and sunny"
}

Example API response: markdown format

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

Attachment format

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.

All button attachments include the following field: attachmentType: 0

Types of button

Response button

• displayText - Text shown on the button, eg "Click here"
• replyText - Text that will come back to the bot when the user clicks the button. Optional. Useful when you want short, simple button text, but more detailed response, ie to trigger a specific answer via a long question

Custom action button

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.

• displayText - Text shown on the button
• action - Custom action to perform, see Custom action format info below

Open url button

• displayText - Text shown on the button
• url - Url to open when the button is clicked

Example - API response with button attachments

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

Custom action format

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.  

See custom actions documentation for more details on available actions.

Custom action formats

Custom actions: value field format by type

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

Example: API response with custom actions

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

Example API host (in NodeJS) to test message responses

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

• Use this to quickly test how the bot displays various response types. 
• Use with a port-forwarder, i.e. NGROK to expose the API to the bot.

const http = require("http");
const url = require("url");

const requestListener = function (req, res) {
  const parsed = url.parse(req.url, true); // Parse URL with query string

  const examples = {
    1: {
      status: "success",
      statusCode: 1,
      messageType: "Text",
      message: "The weather today is nice and sunny",
    },
    2: {
      status: "success",
      statusCode: 1,
      messageType: "Text",
      message: "The weather today is **nice** and sunny click [here](https://weather.com/city/auckland) for more information",
    },
    3: {
      status: "success",
      statusCode: 1,
      messageType: "Text",
      message: "The weather today is **nice** and sunny click [here](https://weather.com/city/auckland) for more information",
      attachments: [
        {
          type: 0,
          displayText: "Weather radar",
          replyText: "Show me the weather radar",
        },
        {
          type: 0,
          displayText: "Weather warnings",
        },
        {
          type: 0,
          displayText: "Open home page",
          url: "https://weather.com",
        },
      ],
    },
    4: {
      status: "success",
      statusCode: 1,
      messageType: "Text",
      message: `✅ We have found your order number: **${parsed.query.orderId}**`,
      attachments: [
        {
          type: 0, // Button
          displayText: "📝 - View order",
          url: `https://store.com?order=${parsed.query.orderId}&email=${parsed.query.email}`,
        },
        {
          type: 0, // Button
          displayText: "Contact us",
          action: {
            type: 3, // Activate form
            value: "calculator=c11fe92a-4444-555e-11aa-06f13fa3f123,
            context: {
                 "userName": "Clementine Citrus",
                  "contactMethod": "apiResponse"
             },
          },
        },
      ],
    },
  };

  if (parsed.query.ex && examples[parsed.query.ex]) {
    res.setHeader("Content-Type", "application/json");
    res.writeHead(200);
    res.end(JSON.stringify(examples[parsed.query.ex]));
  } else {
    res.writeHead(200);
    res.end("<html><body<div>test</div></body></html>");
  }
};

const host = "localhost";
const port = 9001;

const server = http.createServer(requestListener);
server.listen(port, host, () => {
  console.log(`Server is running on http://${host}:${port}`);
});