Botnation API : Import and Export data through Webhook

JSON API mode: Automatically import and export chatbot data via webhook

The Webhook element allows you to import or export data to any external system: your own Webhook, Zapier, IFTTT or any other system that responds to HTTP protocol.

➜ Discover Botnation and launch your chatbot easily!

1. Recommendations

Avoid overloading your chatbot with Webhook calls, this can strongly slow down the performance of your chatbot as Botnation will be waiting for a service outside its infrastructure. Your webhooks are then placed in a queue dedicated to your chatbot.
We therefore recommend that you only connect external services with instantaneous response times via Webhook.


To do this, enter the url of the service you want to call. The url must be in HTTPS (secure http).

You can add parameters either by adding them directly in the URL or by using the + Add parameter option.

The url will be called by Botnation AI in POST or GET. The header can be customized.

TIPS
If you want to be sure that the variable contains information before it is sent you can, for testing, temporarily display a message just before the Webhook that displays the variable.

Your Webhook must always be located after the data collection, not before, otherwise it has nothing to send!

2. Test the url of your Webhook

The button “Test the Webhook” allows you to make a call to the url you have entered to check that it works properly.

If your url contains Botnation variables then you will have to simulate them by filling in values in the associated fields:

If the url is correct, a message will confirm it, otherwise an error will appear:

3. “Synchronous process” option

Synchronous processing allows you to put the Chatbot on hold while your Webhook delivers a response. This is useful if one or more functions depend on a call to your Webhook.

For example, we have two Webhook functions one after the other:

  • The Webhook A function executes a query that will add a user in a database
  • The Webhook B function executes a query that will retrieve the total number of users from the database and insert it into a Botnation variable.

For the Chatbot to work properly, it is imperative that function A is fully executed before launching function B, otherwise we would get an incorrect number of users.

By using the “synchronous processing” option on function A, we ask the Chatbot to pause its execution for the time of the request. As soon as the Webhook delivers a response, the Chatbot moves on to the next function, namely B.

This allows the order of the functions to be respected during the execution of the Chatbot.

If the “synchronous processing” option is not checked, the Chatbot will not stop its execution, it will perform the request in parallel.

In case of a Webhook error

When processing is synchronous, it is possible to select a redirection sequence in case of an error in your Webhook :

If your Webhook does not respond or returns an error, the user will be redirected to the redirection sequence you have chosen.

4. Option “Process JSON answer”.

Only enable this option for very advanced use of the Webhook. This can cause your chatbot to change its behavior if your webhook does not respect the expected response format.

If you are only collecting data, you should not activate this option.

For advanced use, the Webhook element can also read and process the response returned by the HTTP call.

This allows you, for example, to generate personalized responses from data on your own servers. These responses can contain text messages, images, videos, audios, variables, buttons, etc…

Here are some examples of usage:

  • Retrieve your latest news automatically without having to integrate them daily “by hand” into your chatbot’s tree structure.
  • Send the city or the collected GPS coordinates of a user to your webhook which sends back a message containing the 7-day weather forecast + a weather image generated by your system.
  • Send to your webhook a user’s order number collected by the chatbot which returns in response the status of the delivery and changes the user’s variables.
  • Send the title of a movie requested by the user in your chatbot to your webhook which connects to your database of millions of videos to send it a trailer without having to pre-program everything and upload it to your chatbot tree!

Your webhook must then answer within a few seconds (10), after which the connection to the webhook will be interrupted and the possible answer cancelled.

When you choose to process the response, the “Synchronous Processing” option will be automatically activated. Your chatbot will be on hold until your webhook has delivered a response, so bet on a server with a good connection and a fast base.

If you are going to retrieve a non-personalized content (a news item) or one that can be reused by several users (the weather forecast for the same city), you can cache your response to increase processing speed and limit calls to your webhook. The duration can be from a few minutes to several days.

You can use services like Zapier or IFFT that have pre-made webhooks connected to many external APIs like Salesforce, Mailchimp, Google etc…

The service must send a response in JSON format and encoded in UTF-8 . Recommended header content-type: “application/json”.

All responses must be formatted as follows:

{
    "botnation": "v1", // obligatoire pour que la réponse soit prise en compte
    "reply": [
         // contenu de la réponse (voir les nombreux exemples ci-dessous)
{
                        "type": "text",
                        "value": "Hello"
                }
    ]
}

We strongly recommend that you use the https://jsonlint.com/ service to check the syntax and format of your JSON responses. It is not uncommon to forget a comma or a brace, and the answer would then be cancelled.

Warning: the response must only contain the JSON file, nothing before, nothing after.

The JSON “reply [ ]” array can contain elements of different types (texts, images, buttons…) in a single reply.

Text

Allows you to display a simple text.

Example:

{
        "botnation": "v1",
        "reply": [{
                        "type": "text",
                        "value": "Hello World!"
                }
        ]
}
Result

In the value of a text you can inject variables in the same way as for the Text elements of the interface. To do this, enclose your variable like this: {{variable}}. To learn more about variables, read this article: All about variables {{…}}

Example:

{
        "botnation": "v1",
        "reply": [{
                        "type": "text",
                        "value": "Hello {{FIRSTNAME}} !"
                }
        ]
}


A delay between 2 elements

“value”: duration in seconds.

Example:

{
        "botnation": "v1",
        "reply": [{
                        "type": "text",
                        "value": "Hello World!"
                },
                {
                        "type": "delay",
                        "value": 5            
                },
                {
                        "type": "text",
                        "value": "how are you?"
                }
        ]
}

Image, Video or Audio

Allows you to display a media, JPEG format recommended for images, MP4 for videos, MP3 for audio).

“type : “image”, “video” or “audio
“value” : “media url”

Example:

{
        "botnation": "v1",
        "reply": [{
                        "type": "text",
                        "value": "Hello World!"
                },
                {
                        "type": "image",
                        "value": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/db/Nasa_blue_marble.jpg/250px-Nasa_blue_marble.jpg"
                }
        ]
}
Result

Set of Variables

Allows you to assign a value to a user variable.

“name” : “variable_name” (without space or special character)
“value” : “string or value

In the bot call this variable by {{nom_de_la_variable}} .

You can create a new variable via this call, however the interface will eventually ask you to validate this variable so that it appears later in the interface menus.

To learn more about variables, read this article: All about variables {{…}}

Example:


{
        "botnation": "v1",
        "reply": [
                {
                        "type": "set",
                        "name": "who",
                        "value": "World"
                },
                {
                        "type": "text",
                        "value": "Hello {{who}}"
                }
        ]
}
Result

for global variables {{varglob}} the syntax is : “type”: “set_gobal”

Example:

{
        "botnation": "v1",
        "reply": [
                {
                        "type": "set_gobal",
                        "name": "phone",
                        "value": "+33175757575"
                },
                {
                        "type": "text",
                        "value": "Hello {{%%phone%%}}"
                }
        ]
}

Buttons and Quick Replies

Allows you to display a list of buttons.

To display the buttons of a Story Button (3 buttons maximum):

{
    "type": "button",
    "value": "le texte à envoyer"
    "buttons": [button1, button2, button3]
}

To display the buttons of a Story Rep. (maximum 11 buttons with icon):

{  
    "type": "quickreply",    
    "value": "le texte à envoyer"    
    "buttons": [button1, button2, button3]
}

Each of these buttons contains a next field that will redirect the user to a desired sequence. In this field, you must enter a redirection keyword that you have defined in the AI module.

Buttons: Text with Redirection

Example:

{
        "botnation": "v1",
        "reply": [{
                        "type": "text",
                        "value": "Hello!"
                },
                {
                        "type": "button",
                        "value": "Where is Brian?",
                        "buttons": [{
                                        "label": "In the kitchen",
                                        "type": "payload",
                                        "next": "kitchen"
                                },
                                {
                                        "label": "In the bathroom",
                                        "type": "payload",
                                        "next": "bathroom"
                                }
                        ]
                }
        ]
}
Result

Buttons: Variable Set and Redirection

Example:

{
        "botnation": "v1",
        "reply": [{
                        "type": "text",
                        "value": "Hello!"
                },
                {
                        "type": "button",
                        "value": "What do you want to eat?",
                        "buttons": [
                                {
                                        "label": "A sandwich!",
                                        "type": "input",
                                        "name": "eat",
                                        "value": "sandwich",
                                        "next": "confirmation"
                                },
                                {
                                        "label": "A Cheeseburger ;)",
                                        "type": "input",
                                        "name": "eat",
                                        "value": "burger",
                                        "next": "confirmation"
                                }
                        ]
                }
        ]
}


Buttons: Open Web Site and Launch Phone Call

The ratio of the open webview can be :

  • “compact”: opening of the site in a small popup system
  • “tall” : opening of the site in a large popup system
  • “full” : opening the site in a new tab
  • “current” : opening the site in the current tab
    The telephone number must begin with the country code. ( +1 (USA), +33 (France), +48 (Poland) etc.)

    Example:
{
        "botnation": "v1",
        "reply": [
                {
                        "type": "button",
                        "value": "Google or Phone Call?",
                        "buttons": [{
                                        "label": "Google",
                                        "type": "web_url",
                                         "ratio": "full",
                                        "url": "https://google.com"
                                },
                                {
                                        "label": "Call Me",
                                        "type": "phone_call",
                                        "value": "+33101010101"
                                }
                        ]
                }
        ]
}


Quick Replies with Geolocation.
Only on Facebook Messenger
Example:

{
        "botnation": "v1",
        "reply": [{
                        "type": "text",
                        "value": "Hello!"
                },
                {
                        "type": "quickreply",
                        "value": "Where are you?",
                        "buttons": [{
                                        "label": "Geolocation!",
                                        "type": "location",
                                        "next": "confirmation"
                                }]
                }
        ]
}
Result

Quick Replies with Variable Set and Redirection and Icon (“url”)

Example:

{
        "botnation": "v1",
        "reply": [{
                        "type": "text",
                        "value": "Hello!"
                },
                {
                        "type": "quickreply",
                        "value": "What do you want to eat?",
                        "buttons": [{
                                        "label": "A Pizza",
                                        "url": "https://png.icons8.com/dusk/540/shopping-cart.png",
                                        "type": "payload",
                                        "next": "pizza"
                                },
                                {
                                        "label": "A Cheeseburger",
                                        "url": "https://png.icons8.com/dusk/540/shopping-cart.png",
                                        "type": "payload",
                                        "next": "burger"
                                },
                                {
                                        "label": "A Salad",
                                        "url": "https://png.icons8.com/dusk/540/shopping-cart.png",
                                        "type": "input",
                                        "name": "eat",
                                        "value": "salad",
                                        "next": "confirmation"
                                }
                        ]
                }
        ]
}
Result

For web chatbots it is also possible to indicate outgoing links.

Example:

                                {
                                        "label": "My Website",
                                        "url": "https://png.icons8.com/dusk/540/shopping-cart.png",
                                        "type": "web_url",
                                        "web_url": "https://botnation.ai",
                                        "ratio": "full"                                        
                                }

Generate a carousel

Carousels can contain several pages and several buttons, each page can have an image or not. The syntax of the buttons is similar to the classic buttons (see above).

The ratio of the images must be declared in the header. “horizontal or square

Example of a carousel of 3 pages, the 3rd of which does not contain an image with several variations of buttons.

Example:

{
	"botnation": "v1",
	"reply": [{
		"type": "carousel",
		"ratio": "horizontal",
		"pages": [{
			"title": "Where is Brian?",
			"subtitle": "in the kitchen",
			"image": "https://i.pinimg.com/474x/c7/9b/2b/c79b2b537242b865188f172b346af5fc.jpg",
			"link": "https://www.botnation.ai",
			"buttons": [{
				"label": "In the kitchen",
				"type": "redirect",
				"next": "kitchen"
			}, {
				"label": "Call Brian",
				"type": "phone_call",
				"next": "+33140506010"
			}]
		}, {
			"title": "Hello {{FIRSTNAME}}",
			"subtitle": "Powered by Botnation",
			"image": "https://cdn.searchenginejournal.com/wp-content/uploads/2017/05/bing-site-search-760x400.png",
			"link": "https://www.botnation.ao",
			"buttons": [{
				"label": "Tell me more...",
				"type": "redirect",
				"next": "more"
			}, {
				"label": "Start {{LASTNAME}}",
				"type": "web_url",
				"url": "https://maboite.com"
			}]
		}, {
			"title": "One more time",
			"subtitle": "no picture?",
			"buttons": [{
				"label": "Test Input",
				"type": "input",
				"name": "MyVar",
				"value": "1234",
				"next": "next_one"
			}]
		}]
	}]
}

Simple redirection


Finally, if your Webhook collects data and simply needs to send the user on a confirmation message redirection you can simulate entering a keyword or indicate a blockId.

// by a keyword

            {
                        "type": "redirect",
                        "next": "etape_suivante"
             }


// by a blockid

       {
                        "type": "redirect",
                        "next": "590898d2abec169ef65fcc47"
          }

We strongly recommend that you use the https://jsonlint.com/ service to check the syntax and format of your JSON responses. It is not uncommon to forget a comma or a brace, the answer would then not be taken into account.


Debug variables are available to assist you in managing webhooks.

  • The Http status returned by your Webhook (remote server contacted). Only in “interpret response” mode is available in the variable: {{BN_WEBHOOK_STATUS}}
  • The error message returned by your webhook or if the json transmitted in return is incorrect is available in the variable : {{BN_WEBHOOK_REASON}}

Feel free to post them in messages (text).

➜ Discover Botnation and launch your chatbot easily!