This interaction is designed to provide you with the possibility to post content directly from your resources via API and/or sending data back to your server.
JSON posts can contain all elements of the interaction, such as cards, buttons, quick replies, etc.
To create this interaction, click 'Add new interaction/plugin' link from the top left of the screen, and then select ‘JSON API’ interaction type. After that, specify the interaction name, e.g. ‘API’. Click the 'Add' button to add the item to the bot’s structure:
To start working with the interaction, initially you need to specify the URL of your API as well as the text of the error response:
Correct URL of your API should return status 200 without errors. You can check this via a GUI platform – Postman.
Here is an example of an error response:
This is an example of the successful status:
Created interaction sends a request to your API using POST method following such a structure:
Type | Description |
|---|---|
bot_id | bot id (the one this interaction is connected to) |
user_id | user id (the one that is participating in a conversation with a bot) |
module_id | interaction id (the one sending the request) |
channel | channel type |
incoming_message | previous message sent by a user that triggered API interaction start |
Mandatory fields in requests
- bot_id
- user_id
- module_id
Are taken from the request
After the request has been sent to the API, JSON response will be received on what to show to the user. It must have the following structure:
Type | Description |
|---|---|
message | cannot be empty, contains message shown to the user. Value can be the same as supported by all other interaction types (initial response or error specified in the Error Response field) |
suggested_replies | quick reply buttons like in other interactions |
blocked_input | locks user’s input in the chat. The user can only use cards and quick reply buttons to interact with the bot. Can be true (user input locked) or false (not locked) |
cards | each card has type and value attributes |
You can find an example of the JSON response below:
{
"user_id": "2",
"bot_id": "1",
"module_id": "3",
"message": "Test Message",
"cards": [
{
"type": "text",
"value": "Test Text Card",
"buttons": [
{
"type": "url",
"value": "https://google.com",
"name": "google"
},
{
"type": "module",
"value": "4600",
"name": "Change Module"
}
]
},
{
"type": "image",
"value": "http://link_on_image .png"
},
{
"type": "gallery",
"value": "gallery",
"gallery": [
{
"image": "http://link_on_image .png",
"heading": "Test Gallery Heading",
"subtitle": "Test Gallery Subtitle",
"url": "http://some_test_url.com",
"buttons": [
{
"type": "url",
"value": "https://google.com",
"name": "google"
},
{
"type": "module",
"value": "4600",
"name": "Change Module"
}
]
}
]
}
]
}
The response can contain Rich cards values. Currently, there are three types of cards supported by SnatchBot platform: text card, image card, and gallery card.
- Text Card – is a card that can contain any combination of text, buttons, and input fields;
- Image Card – is a card that can contain just an image, without buttons and input fields;
- Gallery Card – is a card that can contain any combination of text, speech, images, buttons, and input fields.
Values should be as follows:
Value type | Description |
|---|---|
text card | the text displayed on the card (limited to 640 characters) |
image card | the URL of the image |
gallery card | value has to be gallery. Each gallery is a value has to be a gallery. Each gallery is a massive of sub cards, each of them containing its set of parameters: image (the URL of the image), heading (text in gallery header, limited to 80 characters), subtitle (text under the gallery, limited to 80 characters), URL (the URL the gallery forwards to) |
Each card type (except image card) has buttons (one card type can contain up to three buttons). Each button is a massive of buttons with the following attributes:
- Type – button type;
- Value – content;
- Name – button’s title (limited to 20 characters).
There are four button types:
Button type | Description |
|---|---|
module | triggers an interaction, its id should be specified in the button type |
URL | switches to the specified link in the button type |
phone | triggers a phone call to the specified phone number |
share | works only on Facebook, opening its sharing dialog. There are no specific attributes |
Here is an example of the API implementation:
public function snatchbotAPITest()
{
$bot_id = $this->input->post('bot_id');
$user_id = $this->input->post('user_id');
$module_id = $this->input->post('module_id');
$channel = $this->input->post('channel');
$message = $this->input->post('incoming_message');
$cards = [
[
'type' => 'text',
'value' => 'Test Text Card',
'buttons' => [
[
'type' => 'url',
'value' => 'https://google.com',
'name' => 'google'
],
[
'type' => 'module',
'value' => '4600',
'name' => 'Change Module'
]
]
],
[
'type' => 'image',
'value' => 'http://link_on_image .png'
],
[
'type' => 'gallery',
'value' => 'gallery',
'gallery' => [
[
'image' => 'http://link_on_image.png',
'heading' => 'Test Gallery Heading',
'subtitle' => 'Test Gallery Subtitle',
'url' => 'http://some_test_url.com',
'buttons' => [
[
'type' => 'url',
'value' => 'https://google.com',
'name' => 'google'
],
[
'type' => 'module',
'value' => '4600',
'name' => 'Change Module'
]
]
]
]
]
];
$suggestedReplies = ['Option1', 'Option2'];
header('Content-Type: application/json');
$response = [
'user_id' => $user_id,
'bot_id' => $bot_id,
'module_id' => $module_id,
'message' => 'Test Message',
'cards' => $cards,
'suggested_replies' => $suggestedReplies,
'blocked_input' => true
];
echo json_encode($response);
}
The JSON API interaction supports the following options:
Delayed card sending;
Switching the view mode in Gallery Cards (Grouped/In a Line);
Adjusting settings of the TTS feature (on/off, volume, voice, etc) for auto mode only;
“Display quick replies in one scrollable line” for quick replies in the WebChat;
“Disable input” feature;
Text wrapping.
Some restrictions
It is not possible to set the TTS feature in a JSON interaction, but TTS can be part of the JSON message as well as cards, modules etc.
Users can not subscribe/unsubscribe to RSS feed via JSON.
Attribute extraction
JSON functionality allows to extract user’s attributes and store them on your own server. To do so you have to add required attributes and wait until a user reaches JSON interaction. Then the data will be immediately sent to your server.
JSON API interaction can be connected to other types of interactions. For example to the Bot Statement:
Watch this video tutorial ''How to use JSON API''
Updated about a month ago
Next Steps
To illustrate how you can generate and post custom content via API, here is a demonstration of how you can create a Weather Forecast Chatbot that provides a weather forecast for a selected location and period using the API of the weather forecast web service provided by SnatchBot.
| Using the JSON API |