> For the complete documentation index, see [llms.txt](https://dev.joonbot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.joonbot.com/master.md).

# Webhooks

## 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.

![](/files/-MHHL5jiJ76fLbSTy3HR)

### 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.

![](/files/-MHHOSXGVkVK-Fxa2XTL)

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

![](/files/-MHHP7g2BGlieceYltpg)

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.

![](/files/-MHHYaceaXZ58twFZuZx)

### 4. Send data to your system - Asynchronous webhook

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

![](/files/-MHHW1f16PpO0ubrV4v1)

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": "nicolas@joonbot.com",
    "phone_number": "0612345678",
    "conversation": "Bot: What brings you here today?\nUser: Just browsing\nBot: What's your email address?\nUser: nicolas@joonbot.com\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:

![](/files/-MHHe8j7Y5JfK4Gl2qWf)

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

![](/files/-MHQ0KU3VI8NJTPgez7h)

Now let's have a conversation with the bot

![](/files/-MHQ0T8rTdHHXNSXQYRb)

If you have any question, please contact us at <nicolas@joonbot.com>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.joonbot.com/master.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.