Webhooks

Joonbot provide a webhook system that let you integrate deeply with your systems. Let's have a look at how it work and what we can build.

Configure webhooks

A webhook is basically an API endpoint we will call during a conversation with your bot. We'll call your endpoint with a payload that contains data about the current conversation.

1. Add a webhook block to your flow

Let's create a lead generation bot that collect informations about your visitor and that will send the collected data to your api. To do that, drag and drop some question blocks and terminate it with a webhook block. Link blocks together so your flow look like you want.

2. Configure your endpoint

After selecting the webhook block, a link to the endpoint setup will appear. Please visit https://app.joonbot.com/webhooks to see the list of the webhooks you can use inside any of your bot flows.

Let's go and setup our first webhook!

Let's give it a name and the url of your endpoint. You can also configure the headers that will be used for every requests.

Great! Now let's go back to your bot builder and edit you webhook block to use the webhook you just created.

Notice the Asynchronous option here. If you select Asynchronous, your api will be called in a background task. It's useful to send data to your system. Otherwise, your api will be called during the conversation and can compute a response for your user in real time.

3. Configure field names

In your webhook, you certainly want to retrieve specific fields. In the bot builder, edit the email block so the field "Save answer to" match "email". You can do the same for the phone number block, and save answer to phone_number.

4. Send data to your system - Asynchronous webhook

Let's have a conversation with the bot we designed in the previous sections.

When the "Webhook block" is reached at the end of the conversation, a POST is done on the api url we configured previously (https://yourapi.com/hooks) and the payload is formatted with all the answers collected during the conversation. In this example, the payload sent was:

{
    "email": "[email protected]",
    "phone_number": "0612345678",
    "conversation": "Bot: What brings you here today?\nUser: Just browsing\nBot: What's your email address?\nUser: [email protected]\nBot: What's your phone number?\nUser: 0612345678\n"
}

A conversation field is sent by default with all the conversation detail. From there, you can use this payload and save it to your database for example.

5. Non Async webhook

Now, imagine you not only want to save the conversation in your database but also want to compute a reply in real time to your visitor. Let's say you want to reply the user with his order delivery status.

First, you will need to edit your webhook block and set async to "No". This way the webhook will be called during the conversation.

The payload you'll receive will be the same as in the previous section.

Now, your url endpoint need to return a 2xx with a body that contains the instructions you want to be executed.

5.1 Reply a text

If you want to return instructions that will be executed in the bot, you need to return a "responses" key with an array of instruction.

To reply with a list of texts, in your endpoint return a JSON payload that matches

{
   "responses": [
       {
           "elements": [
               {
                   "label": "Good morning John",
                   "order": 1,
                   "placeholder": null
               }
           ],
           "delay": 2000,
           "type": "text"
       },
       {
           "elements": [
               {
                   "label": "Your order is on the way to your delivery pickup point",
                   "order": 1,
                   "placeholder": null
               }
           ],
           "delay": 2000,
           "type": "text"
       }
   ]
}

If your api returns this payload, the conversation will look like this:

5.2 Set context variables

Another option you have is to return a set of variable you want to set into your conversation context.

If your api endpoint return a JSON payload that does not contains the key "responses", all the keys of your payload will be set in the conversation context and will be reusable.

Let's take an example, set your api to return

{
    "delivery_status": "delivered",
    "delivery_method": "eco"
}

Edit your bot flow, add a text block after the webhook call to display the delivery status

Now let's have a conversation with the bot

If you have any question, please contact us at [email protected]