How to use external request / dynamic content?

External Request allows you to integrate your bot with any system that has an API. You can use external requests to get data from any other system and display the data to the user within your chatbot.

How to use an external request?

 

In the flow builder, Add  Actions  >  External API Request.

How to save data in a custom field?

 

You can use  a response mapping  to save data from an API to a  custom field if the API returns data in JSON format. Many times you may want to get data from an API and show the data to the user.

For example, we’ll use the currency conversion API to show how you can save the data returned from the API into a custom field. Below is the API response.

{
    "success": true,
    "timestamp": 1519296206,
    "base": "EUR",
    "date": "2021-03-17",
    "rates": {
        "AUD": 1.566015,
        "CAD": 1.560132,
        "CHF": 1.154727,
        "CNY": 7.827874,
        "GBP": 0.882047,
        "JPY": 132.360679,
        "USD": 1.23396
    }
}

to rescue

If we want to display the dollar value, you will need to use  rates.USD  , we recommend you check your request, copy the response and use  this service  to get the correct JSONPath. Also, you can use this service to check if your JSONPath is correct. Your JSONPath does not need to be initialized by  x.

There are two ways to present the data returned from an API to the user within your bot. You can save the data in a custom field using response mapping and use the custom field in your flow to display the data to the user. Also, your API can return messages ready to be displayed to the end user within your bot (  dynamic content  ). Dynamic content is explained below in this article.

How to get the HTTP status code or the entire response body?

 

In the response mapping, use  http_status_code  to get the response code and use  http_response_body  to get the entire response body. Once you save the HTTP status code in a custom field, you can use the conditions to perform any logic you want.

Dynamic content

 

Dynamic content allows you to generate content from your server and display it to the user within your chatbot. Dynamic content is supported on all channels. You use a single format that works on all channels. Our platform automatically converts your message in real time and delivers it to the user.

You cannot use the dynamic content feature if you do not own the API you are receiving data from. In this case, you can save data from the API to a custom field using  response mapping  and display the data using the custom field in the flow builder.

The response format is below.

{
    "messages": [],
    "actions": []
}

 

Messages  : Contains messages sent to the user within your bot. You can send any type of content supported by Messenger Bots. We show some sample formats in this article, but you can read  Facebook’s documentation  if you need more capabilities.

allchat sends an ‘  X-USER-ID  ‘ header in every request.

quick_plies  is always optional.

Send a text message.

{
    "messages": [
        {           
            "message": {
                "text": "Hello world",
                "quick_replies":[]
            }
            
        }
    ]
}

 

Sending more than one message

{
    "messages": [
        {
            "message": {
                "text": "Hello world"
            }
        },
        {
            "message": {
                "text": "This is the second Message",
                "quick_replies":[]
            }
        }
    ]
}

 

Sending a text message with buttons.
The text message can contain up to 3 buttons. The title of each button can contain up to 20 characters. To send a stream when a user clicks a button, simply use a stream identifier as the button’s payload. Every resource in allchat has a charge. You can use any payload, and the user will be redirected to the contents of the payload. For example, if you want to display a product instead of a flow, just use a product loader.

{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "buttons": [
                            {
                                "title": "Open Website",
                                "type": "web_url",
                                "url": "your_URL"
                            },
                            {
                                "title": "Send FLow",
                                "payload": "<payload>",
                                "type": "postback"
                            },
                            {
                                "title": "Call Number",
                                "type": "phone_number",
                                "payload": "<your_phone_number_with_county_code>"
                            }
                        ],
                        "template_type": "button",
                        "text": "Hello world"
                    },
                    "type": "template"
                },
                "quick_replies":[]
            }            
        }
    ]
}

 

Payload  : You can use any  flow/phase ID  as a payload. For example, if you want to redirect to a flow after the user clicks the button, you can use the flow ID as the payload. In this article, we show how to use  actions  as payloads as well.

Sends a message with quick replies

You can add quick replies to any type of message (text, file, gallery, file,…). Facebook allows you to attach a maximum of 11 quick replies to a message. The charge for quick replies is the same as the charge for buttons.

{
   "messages": [
       {           
           "message": {
               "text": "Hello world",
               "quick_replies":[
                  {
                     "content_type": "text",
                     "title": "Quick Reply 1",
                     "payload": "<payload>"
                  },
                  {
                     "content_type": "text",
                     "title": "Any Text Here",
                     "payload": "<payload>"
                  }
               ]
           }
           
       }
   ]
}

 

Charges on quick replies and buttons have the same structure.

Send image, video, audio, file.
You can use the same structure below to send image, video, audio and file. Just change the media_type to video, audio or file. “URL” will be the link to your image, audio, video or file.

{
    "messages": [
        {
            "message": {
                "attachment": {
                    "type": "image",
                    "payload": {
                        "url": "<ASSET_URL>"
                    }
                },
                "quick_replies":[]
            }
        }
    ]
}

 

Send a single card
The title and caption of the card can be up to 80 characters.

{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "elements": [
                            {
                                "title": "Card Title",
                                "subtitle": "Card Subtitle",
                                "image_url": "image_url"
                            }
                        ],
                        "template_type": "generic"
                    },
                    "type": "template"
                },
                "quick_replies":[]
            }
        }
    ]
}

 

Send a single card with buttons
A card can contain up to 3 buttons.

{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "elements": [
                            {
                                "title": "Card Title",
                                "subtitle": "Card Subtitle",
                                "image_url": "image_url",
                                "buttons": [
                                    {
                                        "title": "Button Label",
                                        "type": "web_url",
                                        "url": "your_URL"
                                    },
                                    {
                                        "title": "Button Label",
                                        "payload": "<payload>",
                                        "type": "postback"
                                    },
                                    {
                                        "title": "Button Label",
                                        "type": "phone_number",
                                        "payload": "+your_phone_number"
                                    }
                                ]
                            }
                        ],
                        "template_type": "generic"
                    },
                    "type": "template"
                },
                "quick_replies":[]
            }
        }
    ]
}

 

Send Gallery
Basically, a gallery is a set of cards. A gallery can contain up to 10 cards. The code below displays a gallery with 2 cards. You can also add a button to each card.

{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "elements": [
                            {
                                "title": "Card Title 1",
                                "subtitle": "Card Subtitle 1",
                                "image_url": "image_url 1",
                                "buttons": []
                            },
                            {
                                "title": "Card Title 2",
                                "subtitle": "Card Subtitle 2",
                                "image_url": "image_url 2",
                                "buttons": []
                            }
                        ],
                        "template_type": "generic"
                    },
                    "type": "template"
                },
                "quick_replies":[]
            }
        }
    ]
}

 

Actions  : It is optional to include this field. You can use actions to add/remove tags, set/disable custom fields, send flow…

Add a tag

{
    "messages": [],
    "actions": [
        {
            "action": "add_tag",
            "tag_name": "..."
        }
    ]
}

 

Remove tag

{
    "messages": [],
    "actions": [
        {
            "action": "remove_tag",
            "tag_name": "..."
        }
    ]
}

 

Define a custom field

In addition to accepting any custom field name, this action also allows you to change system fields such as  phone  ,  email, full_name, first_name, last_name

{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "...",
            "value": ""
        }
    ]
}

 

Unset a custom field

{
    "messages": [],
    "actions": [
        {
            "action": "unset_field_value",
            "field_name": "..."
        }
    ]
}

 

Send a flow
To get the flow ID, you must go to the list of flows, click on the 3 dots and click on  get link  . The flow ID is the number included in your link. A flow ID is always numeric. An unlimited number of actions can be combined.

{
    "messages": [],
    "actions": [
        {
            "action": "send_flow",
            "flow_id": "..."
        }
    ]
}

 

Combine several operations

You can combine multiple actions in one request to allow you to run multiple actions at the same time. For example, you might want to define a custom field and send a flow in a single request.

{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "...",
            "value": ""
        },
        {
            "action": "send_flow",
            "flow_id": "..."
        }
    ]
}

 

Use actions as a button loader and quick replies

Below is the format for using the action as a loader on buttons. But since payload is a string, you need to convert your actions object to a JSON string. If you’re using PHP, use json_encode to get a string representation of your object.

{   
    "actions": [
        {
            "action": "send_flow",
            "flow_id": "..."
        }
    ]
}

 

Below, the above action is used as the button’s payload.

{
    "messages": [
        {
            "message": {
                "attachment": {
                    "payload": {
                        "buttons": [
                            {
                                "title": "Click Here",
                                "payload": "{\"actions\":[{\"action\":\"send_flow\",\"flow_id\":\"...\" } ]}",
                                "type": "postback"
                            }
                        ],
                        "template_type": "button",
                        "text": "Hello world"
                    },
                    "type": "template"
                },
                "quick_replies":[]
            }            
        }
    ]
}

More articles

Scroll to Top

A small step to change the business

After registration you will start immediately

Contact Information