Knowledge Base
External Requests allow you to integrate your bot with any system that have an API. You can use External Requests to get data in other systems and display to the user in Messenger, you can add/remove tags, set/unset custom fields and even get data from any API and save to custom fields.
The response format is below
{
"messages": [],
"actions": []
}Messages: contains messages that are sent to the user in Messenger. You can send any type of content supported by Messenger Bots. We show some format examples in this article but you can read Facebook documentation if you need more capabilities.
Botosynthesis send a header ‘ X-USER-ID‘ on every request.
quick_replies is always optional.
Send a text message.
{
"messages": [
{
"message": {
"text": "Hello world",
"quick_replies":[]
}
}
]
}Sending more than a single message
{
"messages": [
{
"message": {
"text": "Hello world"
}
},
{
"message": {
"text": "This is the second Message",
"quick_replies":[]
}
}
]
}Sending a text message with buttons.
The text can contain up to 3 buttons. The title of each button can contain up to 20 characters. To send a flow when a user clicks on a button just get the payload of the flow. Every resource on Botosynthesis has a payload. You can use any payload and the user will be redirected to the content of the payload. For example, if you want to show a product instead of a flow, just use the payload of a product.
{
"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 REF parameter or flow/step ID as a payload. For example, if you want to redirect to a flow once the user clicks on the button, you can use the flow ID as a payload. In this article, we show how to use actions as payload also.
Sending a message with quick replies
Quick replies can be added to any type of message (text, file, gallery, file, …). Facebook allows you to attach a maximum of 11 quick replies to a message. The payload for quick replies is the same as the payload 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>"
}
]
}
}
]
}Send an image, video, audio, file
You can use the same structure below to send an 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 subtitle of the card can 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 a Gallery
Basically a gallery is a set of cards. A gallery can contain up to 10 cards. The code below show 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/unset custom fields, send a flow…
Add Tag
{
"messages": [],
"actions": [
{
"action": "add_tag",
"tag_name": "..."
}
]
}Remove Tag
{
"messages": [],
"actions": [
{
"action": "remove_tag",
"tag_name": "..."
}
]
}Set Custom Field
{
"messages": [],
"actions": [
{
"action": "set_field_value",
"field_name": "...",
"value": ""
}
]
}Unset Custom Field
{
"messages": [],
"actions": [
{
"action": "unset_field_value",
"field_name": "..."
}
]
}Send Flow
To get the flow ID, you will need to go the list of flow, click the 3 dots, click Get Link. The flow-id is the number after the “t-“. Flow ID is always numeric.
{
"messages": [],
"actions": [
{
"action": "send_flow",
"flow_id": "..."
}
]
}Use actions as payload of buttons and quick_replies
Below is the format to use an action as a payload on buttons. But as a payload is a string you need to transfer your actions object to a JSON string. If you are using PHP use json_encode to get a string representation of your object.
{
"actions": [
{
"action": "send_flow",
"flow_id": "..."
}
]
}Below the action above is used as a payload of the button.
{
"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":[]
}
}
]
}If you are getting data for an API that you can’t control the format of the server response, you can use JSONPath (Response Mapping tab) to extract data in the response and save the data to custom fields.
