JSON API Node and usage

1. Introduction

Like any other system or application, Chatbots can benefit significantly from integrations. The various channels that a chatbot may need to be deployed on, represent an integration in the basic sense. Importantly though, the capabilities of any chatbot can be significantly enhanced by having it integrate with other systems and applications. The typical use cases include – 

  1. Access to Data: Integrations enable a chatbot to get data from various systems and use it for more informed responses. Examples could include a user getting information about the latest Sales KPIs or a user inquiring about the status of their applied leave 
  2. Transaction completion: Integrations allow a chatbot to complete a transaction that the engaging user may be interested in. Examples include allowing a user to apply for a leave on the internal HR system or submitting a support ticket for getting help 

MyBOT provides you with a strong framework for API Integrations. This section will help you understand how to enable a new integration. 

1.1 Access to JSON API Integration 

You can build integrations right within the Conversation Flow Builder. This is accessible from Paths under the Build Menu in your Navigation. 

Once there you have to use the Node for JSON API to enable & Setup your integration. 

2. Know your Integration

The first and foremost thing, to begin with, is to know the integration you want in your bot. Do you want a calendar integration that helps users book a slot or appointment? Or, do you want to have an integration with your CRM and use that to store the collected user information? Or, you could be looking for a Google Sheets integration to add data to one of your sheets. MyBOT provides standard integration capabilities for some of these systems like Salesforce, Google Sheets and Google Calendar. 

Beyond these too though, MyBOT provides a strong capability to integrate with any system using REST APIs with JSON as the data exchange format. JSON (JavaScript Object Notation) is the most widely used data format for data interchange on the web. 

3. JSON API Plugin Usage

The JSON API node lets you enable & setup integration using JSON Rest APIs with your backend apps or other cloud apps. 

MyBOT supports making the REST APIs call using either one of the below methods: 

  1. GET (this method is used to read data)
  2. POST (this method is used to update data)
  3. PUT (this method is used to write or update data)

Depending on your requirements you can make an API request with the most suitable method. Once you select the method that you want to use and insert the required URL for making the request, you can click on the Send button to know the response you are getting from the API call right within the MyBOT Interface. 


To complete your integration, MyBOT’s JSON API node provides you various settings that you can update easily without writing a single line of code. See below for details on the available Settings

3.1 Settings: Params 

The Params tab helps you edit the data required for URL parameters. When you add key-value pairs, the JSON API Plugin automatically combines it with the URL while making the API call.

The value of the parameter can be user-enteredor predefined by the bot admin.

If you want to pass parameters from the user’s side you will have to save the user input as an attribute in the bot and later access it in the JSON API node by typing “{“ in the Params value field.

3.2 Settings: Headers

You can add headers to your API request which can again be user-entered data or predefined by the bot admin. You can pass authentication tokens, app secret, passwords and other credentials as per the requirements of the end-point.

Once you have all your required fields ready, you can click on the Send button to get the response from the API call.

3.3 Settings: Authentication

Authenticate allows you to define identification parameters along with the endpoint. When you send a request, you often have to include parameters to ensure the request has permission to access and return the data you want. 

MyBOT JSON Plugin provides authentication types that make it easy for you to handle authentication protocols through the node.

The authenticate tab provides you with ways to add different types of API authentication to your API request. The supported types are :

  1. Key Based API Authentication
  2. Basic Authentication
  3. Token-Based Authentication (Two-Step Authentication)

You can select “None” as authentication if no authentication is required.

Key Based Auth

For requests that require Key Based API Authentication, you can simply include the authentication keys or an already saved token variable in params/headers.

Basic Auth

For Basic Authentication, you can enter your username and password. It automatically adds the required “Authorization” header to your API request.

To use Basic Auth:

  1. In the Authentication tab, select “Basic” from the Authentication Type drop down menu.
  2. To set the authentication parameters for a request, enter your username and password or user the details from the list of variables saved.
  3. Click the Send button to test your API with basic authentication.

In the case of an Auth failure (i.e. response code 401), it executes the path that you specify under Input Path which can be structured in a way to simply update the username/password variables.

Token-Based Authentication (Two-Step Authentication)

To use Token Auth:

  1. In the authentication tab, select “Token” from the Authentication Type options
  2. To set the authentication parameters for a request, enter the value of the token in the params, header, body or URL.
  3. Create a path that would update the tokens specified as the authentication attributes.
  4. Select the path name in the Input Path field.

The selected path in the Input Path field is executed for updating the keys specified in case of authentication failure.

3.4 Response & Attributes

The Response Section shows you the API response when hit Send after having provided the required Request URL, Params & other settings to make a valid REST API Call. 

From the API response, if you wish to show certain messages to the users you can click on the object you want to show and an attribute will be created. For example, in the above image, I wish to show the USD value to the user. I just click on USD and an attribute is created with the name “rates.USD”. You can change this attribute according to your convenience and use it in the subsequent flow.

[Note: Creating an attribute from a response is available in paid plans only]

3.5 POST And PUT Methods

For the POST and PUT method too you can use the JSON API node to make an API request to update or write data, this data can be user-entered or predefined by the bot admin. You just have to add a JSON data in the Body field. 

And if you wish to send the user entered data, you need to save the user input as an attribute in the bot and later access it in the JSON API node by typing “{“ in the Body field.

4. JSON Response Structure

The JSON API plugin also lets you get interactive responses from your own backend server, provided the JSON response is in a specific format.

We currently support “Send Message”, “Send Message with options” and “Send Carousel” via the JSON API plugin. So if you want to display certain information from your back end as a Message, options and carousel you can use the below JSON reference code to write an API with specific responses

The JSON response format for each case is explained below:

4.1 Send Message:

  • “data” :
  • – “type” : “text”
  • – “text”: “your message”

 JSON Response Structure

{
“data” :{
“type” : “text”,

“text”: “your message”}}

4.2 Send Message with options:

Using the JSON response, you can customize various functionalities of the bot. You can use the Path Redirect functionality to direct the flow into a different Path, you can use Set Attribute to assign values to a predefined variable, or both. To read more about the functionality of the Send Message with Options node, refer the Send message with options doc.

4.2.1. Path Redirect:

  • “data” :
  • “type” : “msg_options”
  • “text”: “your message”
  • “options” :
  • “text” : “name of option”
  • “postback” : “flow_<flow-key>”

Note: To get the flow key of a particular flow, go to Build -> Path on your MyBOT portal and select the path. Flow key will be listed in the URL

  • If the flow key is not provided, then matching FAQ will be triggered based on the text in the option.
  • You can also Get this flow key when you Edit your Pathname.

JSON Response Structure

{
  “data”: {
    “type”: “msg_options”,
    “text”: “Choose an option”,
    “options”: [
      {
        “text”: “Option A”,
        “postback”: “flow_788224AF8006422BA5E587720DE3B252”
      },
      {
        “text”: “Option B”,
        “postback”: “flow_BBC5CE0C3CD94C2DA43FD6F1AE13737A”
      }
    ]
  }
}

4.2.2. Set Attributes:

  • “data” :
  • “type” : “msg_options”
  • “text” : “your message”
  • “options” :
  • “text” : “name of option”
  • “postback” : “data_<attribute name>=<attribute value>”

JSON Response Structure

{
  “data”: {
    “type”: “msg_options”,
    “text”: “Choose option”,
    “options”: [
      {
        “text”: “Option A”,
        “postback”: “data_age=18”
      },
      {
        “text”: “Option B”,
        “postback”: “data_age=30”
      }
    ]
  }
}

Note: The attribute has to be predefined in the bot (you can do so by making a Request User Data node, and not connecting it to your flow).

4.2.3. Path Redirect And Set Multiple Attributes:

  • “data” :
  • – “type” : “msg_options”
  • – “text” : “your message”
  • – “options” :
  • – “text” : “name of option”
  • -“postback” : “flow_<flow-key>||<first attribute name>=<first attribute value>&<second attribute name>=<second attribute value>”

JSON Response Structure

{
  “data”: {
    “type”: “msg_options”,
    “text”: “Choose an option”,
    “options”: [
      {
        “text”: “Option A”,
        “postback”: “flow_BBC5CE0C3CD94C2DA43FD6F1AE13737A||data_variable1=AAA”
      },
      {
        “text”: “Option B”,
        “postback”: “flow_BBC5CE0C3CD94C2DA43FD6F1AE13737A||data_variable1=BBB&variable2=CCC”
      }
    ]
  }
}

The JSON API functionality for Carousels makes it possible for you to create dynamic Carousels. This allows the Carousels to be tailored and more relevant to customers.

The carousel supports image in the form of URL, and up to 3 buttons which can either of the following three functionalities:

  • Trigger Path (“type”: “post_back”)
  • Web URL to redirect to a new page (“type”: “web_url”)
  • Phone number to directly call a phone number (“type”: “phone_number”)

There can be up to 10 different cards (referred to as templates in JSON) for a Carousel. The Default Action makes the carousel clickable and will direct the user to an external link.

  • “data” :
    • “type”: “carousel”
    • “templates” :
    • “title”: “title of the carousel”
    • “subtitle”: “subtitle of the carousel”
    • “image_url”: “URL of the image to be shown in the carousel”
  • “buttons” :
    •  “type”: “<button type>”
    • “payload”: “<payload for the button*>”
    • “title” : “<button name>
    • “type” : “<type of button>”
  • “default_action” :
    • “url” : “<valid HTTP or HTTPS url>”
    • “type” : “web_url”

*Payload would be a website URL for web_url, flow key for post_back, and phone number for phone_number.

Note: Either “image_url” or “buttons” is required with the “title” object. Both can be used together as well

JSON Response Structure

{
  “data”: {
    “type”: “carousel”,
    “templates”: [
      {
        “title”: “Carousel 1”,
        “subtitle”: “Subtitle 1”,
        “Image_url”: “https://searchengineland.com/figz/800×450.jpg”,
        “buttons”: [
          {
            “payload”: “https://www.mybot.com.my/”,
            “title”: “Visit page”,
            “type”: “web_url”
          },
          {
            “payload”: “+11234567890”,
            “title”: “Call a number”,
            “type”: “phone_number”
          }
        ],
        “default_action”: {
          “url”: “https://www.mybot.com.my/”,
          “type”: “website url”
        }
      },
      {
        “title”: “Carousel 2”,
        “subtitle”: “Subtitle 2”,
        “image_url”: “url of image”,
        “buttons”: [
          {
            “payload”: “flow_788224AF8006422BA5E587720DE3B252”,
            “title”: “See another path”,
            “type”: “postback”
          }
        ],
        “default_action”: {
          “url”: “https://searchengineland.com/figz/800×450.jpg”,
          “type”: “web_url”
        }
      }
    ]
  }
}

4.4. Saving User Attributes:

This is used to assign/change the value for a predefined attribute. It can be used along with “Send Message”, “Send Message with options” and “Send Carousels”.

  • “attributes” :  
    • “data” : “<attribute name>”
    • “value” : “<attribute value>”

Sample Snippet

“attributes”: [
    {
      “name”: “popular_search_engine”,
      “value”: “Google”
    }
  ]

4.5. Triggering Path:

This JSON plugin is used to trigger a path, move the flow to the new path.

You can find the flow key in the URL of the path.

  • “data” :
    • “path_to_follow”  : “<flow key>”

JSON Response Structure

{
  “data”: {
    “path_to_follow”: “8FC459EBFD7141B4BF116531D8539845”
  }
}

Was this article helpful?

Related Articles

Leave A Comment?