SnatchBot Support

Welcome to 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!

Please note that the community forum is not a helpdesk.
ProPlan users, remember you can raise a ticket from your dashboard.

Get Started    SNATCHBOT API

JSON API

Integrate your bot with API and post custom content in a chat.

This interaction provides 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.

How to add interaction

  1. Click Add new interaction/plugin
  2. Select JSON API
  3. Specify the interaction name, e.g. ‘API’
  4. (Optional) Tick Highlight Extracted data in chat for a better user experience
  5. Click the Add button to add the interaction to the bot’s structure:

How to set up the interaction

To start working with the interaction, you need to specify the URL of your API, the text of the error response and click Verify:

Valid API address should return status 200:

📘

You can check your API address via a GUI platform – Postman.

Below is an example of the valid JSON structure:

{
    "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"
                        }
                    ]
        }
        ]
    }
    ]
}

JSON API interaction sends a request to your API using the POST method following such a structure:

Type

Description

bot_id

bot id (the one this interaction is connected to)

user_id

user id (account ID. It can be found in Activity Log)

module_id

interaction id (the one sending the request)

channel

channel type
(test 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

Once the interaction is triggered, JSON response will display your content. 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

Cards in JSON API

The response can contain Cards. There are four types of cards supported by the 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.
  • RSS Card - is a card that displays the content from the RSS feeds.

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 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)

RSS card

"type": "rss",
"value": "rss",
"rssCard":
{
"imageURL": "https://rssfeed.rss",
"subscribtionTitle": "Test Rss",
"countStories": 2,
"isReadContentInBot": true,
"OneLine": false,
"url": "https://snatchbot.me/rss_feed"
}

Text and Gallery cards could have buttons (each card can contain up to three buttons). Each button is a massive of JSON data 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

email

opens an email client on the device

🚧

There are restrictions for structure of the buttons in the JSON request:

  1. The maximum number of buttons in a card (Text/Gallery) is 3. Other buttons will be hidden.
  2. The buttons of the Interactions type will be hidden if they lead to the interaction of another bot.
  3. The maximum length of the name of the button is 20 characters. The rest will be hidden.

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


Integrate your bot with API 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.