SnatchBot Support

Welcome to the SnatchBot Support. You'll find comprehensive guides and documentation to help you start working with SnatchBot as quickly as possible, as well as support if you get stuck. Let's jump right in!

The community forum is not a helpdesk
Let’s put this in the front - the vast majority of people here do not work for SnatchBot.

Get Started    SNATCHBOT API

JSON API

Integrates your bot with API. Gives an opportunity to generate and post custom content in a chat.

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)
This parameter can vary depending on the channel: it can contain letters, numbers, and symbols.

module_id

interaction id (the one sending the request)

channel

channel type
(text chat, web chat, facebook, slack, skype, API, email, SMS)

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

JSON API


Integrates your bot with API. Gives an opportunity to generate and post custom content in a chat.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.