# Webhooks
Webhooks allow you to connect your chatbot to your web services. Pass information from interactions and retrieve the result. Your bot is able to send and receive information from your external internet-connected systems with REST APIs.
Webhooks empower your chatbot to integrate with numerous external internet-connected systems (emails, business software, ERP and CRM platforms, and helpdesk software.)
## Webhooks Page
Webhooks Dashboard
Your bot uses these webhooks in its stories to:
* Send information (generated leads, signups, queries, and emails)
* Receive information (status updates, alerts, weather information, and bus timings.)
### Creating a New Webhook
To create a new webhook, click on **New Webhook.**
Add New Webhook
Just like any other API definition, a webhook has a request and a response.
* The request should be configured on the BotDistrikt platform
* The response should be configured on your API server
### **Webhook Request**
The webhook's request is configured on the BotDistrikt platform. These are the following fields you have to configure for every webhook.
| Field | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | A unique name to describe what the webhook does |
| **Method** | GET or POST |
| **URL** | The URL of your API to be called |
| **Query Params** | The data parameters to send to your URL. In a GET request, these are sent as *query parameters* directly on the URL, while a POST request, these are sent as *body parameters* in JSON |
Here is an example of a webhook configuration that gets a random number
random number webhook
The example above shows a simple webhook that calls the URL with the query params **min=10\&max=20.**
### **Webhook Response**
The webhook's response has to be generated by your API server. Every webhook response should be in JSON format, and should contain **at least one** of the following keys:
```json
{
"responses": [],
"memory": {},
"user_attributes": {},
"quickreplies": [],
}
```
#### responses
`responses` can be an array of strings. These strings add to your bot's response to your user. Take a look at how it is done in this example
{% tabs %}
{% tab title="Story" %}
Let's create a story with a webhook that returns `responses`
{% endtab %}
{% tab title="API" %}
{% endtab %}
{% tab title="Webhook Response" %}
```json
{
"responses": [
"Here's your random number: 20"
]
}
```
{% endtab %}
{% tab title="Execution" %}
Let's see how the response is displayed to the user
{% endtab %}
{% endtabs %}
**memory**
`memory` should be an object of key-value pairs that are assigned to the user session's memory. Use these keys to remember the user's current session (product or topic they were talking about) or use the memory merge tags in responses.
For example:
{% tabs %}
{% tab title="Story" %}
Let's create a story with a webhook that returns `memory`. Notice the merge tag {{memory.favourite-thing}}.
{% endtab %}
{% tab title="API" %}
{% endtab %}
{% tab title="Webhook Response" %}
```json
{
"memory": {
"favourite-thing": "cars"
}
}
```
{% endtab %}
{% tab title="Execution" %}
Let's see how the response is displayed to the user. Notice the merge tag {{memory.favourite-thing}} is replaced with **cars.**
{% endtab %}
{% endtabs %}
**user\_attributes**
`user_attributes` should be an object of key-value pairs that are assigned to the user's profile. These keys can then be used to segment users in the **Users** dashboard and to create targeted groups for personalized stories and broadcasts. Take a look at this example:
{% tabs %}
{% tab title="Story" %}
Let's create a story with a webhook that returns `memory`. Notice the merge tag {{user.age}}.
{% endtab %}
{% tab title="API" %}
{% endtab %}
{% tab title="Webhook Response" %}
```json
{
"user_attributes": {
"age": "28"
}
}
```
{% endtab %}
{% tab title="Execution" %}
Let's see how the response is displayed to the user. Notice the merge tag {{user.age}} is replaced with **28.**
{% endtab %}
{% endtabs %}
#### quickreplies
`quickreplies` can be an array of strings. These quick replies display as options to your user. Take a look at how it is done in this example
{% tabs %}
{% tab title="Story" %}
Let's create a story with a webhook that returns `quickreplies`. These display as quick replies to the user
{% endtab %}
{% tab title="API" %}
{% endtab %}
{% tab title="Webhook Response" %}
```json
{
"quickreplies": [
"Chicken",
"Fish",
"Vegetarian",
"Vegan"
]
}
```
{% endtab %}
{% tab title="Execution" %}
Let's see how the response is displayed to the user.
{% endtab %}
{% endtabs %}
### Rich Responses
You may return rich responses from your webhooks for better user engagement. These responses can include rich components such as buttons, images, cards, documents, audios, and videos. For this, `responses` must be an array of JSON objects instead of an array of strings. The following data structures can be used for rich responses.
#### Image response
For an image response, use the following data structure
```json
{
"type": "image",
"url": ""
}
```
{% tabs %}
{% tab title="Story" %}
{% endtab %}
{% tab title="API" %}
{% endtab %}
{% tab title="Webhook Response" %}
```json
{
"responses": [
{
"type": "image",
"url": "https://www.worldatlas.com/upload/6b/40/33/community-development-councils-map-of-singapore.png"
}
]
}
```
{% endtab %}
{% tab title="Execution" %}
{% endtab %}
{% endtabs %}
#### Text with Buttons response
To include buttons within your text response, use the following data structure
```json
{
"type": "text",
"text": "",
"buttons": [
{
"type": "",
"title": "",
"payload": "", // required if type is "postback"
"url": "" // required if type is "web_url"
}
]
}
```
{% hint style="info" %}
To support most messaging apps, use a maximum of **3 buttons** per text response
{% endhint %}
{% tabs %}
{% tab title="Story" %}
{% endtab %}
{% tab title="API" %}
{% endtab %}
{% tab title="Webhook Response" %}
```json
{
"responses": [
{
"type": "text",
"text": "How would you rate your experience with us?",
"buttons": [
{
"type": "postback",
"title": "👍 Like",
"payload": "rating_like_user_227323"
},
{
"type": "postback",
"title": "👍 Dislike",
"payload": "rating_dislike_user_227323"
},
{
"type": "web_url",
"title": "🌐 Learn More",
"url": "https://mywebsite.com/about-our-rating-system"
}
]
}
]
}
```
{% endtab %}
{% tab title="Execution" %}
{% endtab %}
{% endtabs %}
#### Cards response
To display a carousel of cards, use the following data structure
```json
{
"type": "cards",
"elements": [
{
"image_url": "",
"title": "",
"subtitle": "<SUBTITLE>",
"buttons": [
{
"type": "<postback|web_url>",
"title": "<BUTTON_TITLE>",
"payload": "<POSTBACK_PAYLOAD>", // required if type is "postback"
"url": "<WEBSITE_URL>" // required if type is "web_url"
}
]
}
],
"image_aspect_ratio": "<original|horizontal|square>", // If a messaging app supports it, display cards in a different aspect ratio
"page_limit": 8 // defaults to 8
}
```
Cards are paginated by default at 8 cards. If you would like to increase or reduce the number of cards to show per page, change the value of `page_limit` in the webhook response
{% hint style="info" %}
To support most messaging apps, use a maximum of **3 buttons** per card
{% endhint %}
{% tabs %}
{% tab title="Story" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2FHu9lkWz94MlpXSCbWewa%2FScreenshot%202024-05-20%20at%2011.10.49%20AM.png?alt=media&token=142afb42-6520-45c7-950c-2ba5b68c91a1" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% tab title="API" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2FGhgCGCaZG4wpVgarORY2%2FScreenshot%202024-05-20%20at%2011.10.33%20AM.png?alt=media&token=85c23a58-5de9-4e0b-9ddb-0a06c4e6bace" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% tab title="Webhook Response" %}
```json
{
"responses": [
{
"type": "cards",
"elements": [
{
"image_url": "https://www.foodandwine.com/thmb/R29hsuwfvCakNb9E7htyI8fgfrc=/750x0/filters:no_upscale():max_bytes(150000):strip_icc():format(webp)/florentine-butter-chicken-ft-recipe0919-3fef0bddd6614a70b2fe450c11298acb.jpg",
"title": "Florentine Butter Chicken",
"subtitle": "Butter Chicken from Florence with a twist 🐓",
"buttons": [
{
"type": "postback",
"title": "Order",
"payload": "addcart_florentinebutterchicken"
},
{
"type": "web_url",
"title": "Learn More",
"url": "https://www.foodandwine.com/travel/europe/italy/italian-main-dishes/florentine-butter-chicken"
}
]
},
{
"image_url": "https://www.foodandwine.com/thmb/g-2_63IdHag2p5Ayhcw2KI04svI=/750x0/filters:no_upscale():max_bytes(150000):strip_icc():format(webp)/farro-mafaldine-with-black-truffle-butter-and-mushrooms-FT-RECIPE1220-71c4d864d58f42b1a1addd91572c9e47.jpg",
"title": "Truffle Faro Pasta",
"subtitle": "Pair creamy butter, nutty farro pasta, and a fortifying mix of wild mushrooms 🍄",
"buttons": [
{
"type": "postback",
"title": "Order",
"payload": "addcart_trufflefaropasta"
},
{
"type": "web_url",
"title": "Learn More",
"url": "https://www.foodandwine.com/travel/europe/italy/italian-main-dishes/truffle-faro-pasta"
}
]
}
]
}
]
}
```
{% endtab %}
{% tab title="Execution" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2F894Uv5wz2Tdnt7X8ndvp%2Fcards_webhook.gif?alt=media&token=6ee64090-08e7-45d5-851c-5148de59a62e" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}
#### Document Response
To display a document response that a user can download, use the following data structure
```json
{
"type": "document",
"url": "<DOCUMENT_URL>",
"name": "<DOCUMENT_NAME>.<FILE_EXTENSION>"
}
```
Remember to include the file extension within the document's name to allow the user to open it using the intended file format, e.g. pdf, docx, pptx, txt
{% tabs %}
{% tab title="Story" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2FTQwQPXimFWbN9x3i8Fyp%2FScreenshot%202024-05-20%20at%2011.36.44%20AM.png?alt=media&token=2124f964-c2e4-439d-8dd1-57d5c21ac16a" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% tab title="API" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2FfRc71am2wr6swQoQk9ZG%2FScreenshot%202024-05-20%20at%2011.39.26%20AM.png?alt=media&token=4612256d-6f88-4f65-9346-5597bb196fce" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% tab title="Webhook Response" %}
```json
{
"responses": [
{
"type": "document",
"url": "https://worldofwarships.eu/dcont/fb/document/e7d8b942-142f-11ef-9f3c-b49691e6ead0.pdf",
"name": "Contest Conditions.pdf"
}
]
}
```
{% endtab %}
{% tab title="Execution" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2FJxCTRYF5ioAIMaY0ljCB%2FScreenshot%202024-05-20%20at%2011.38.47%20AM.png?alt=media&token=a3837a95-fd14-4381-8518-a05487ecd5ad" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}
#### Audio response
To show a playable audio file to the user, use the following data structure
```json
{
"type": "audio",
"url": "<AUDIO_URL>",
"name": "<AUDIO_NAME>.<FILE_EXTENSION>"
}
```
Remember to include the file extension within the audio's name to allow the user to open it using the intended file format, e.g. wav, mp3
{% tabs %}
{% tab title="Story" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2F90uE6jDyzEZmTdjYauAe%2FScreenshot%202024-05-20%20at%2011.51.17%20AM.png?alt=media&token=db1493e5-56e6-4e21-959a-3b87472c6dac" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% tab title="API" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2FjcWmG4HLmcP1ory8UpVs%2FScreenshot%202024-05-20%20at%2011.51.29%20AM.png?alt=media&token=7ebb020a-3a1e-434d-9de3-9eab1dbacb40" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% tab title="Webhook Response" %}
```json
{
"responses": [
{
"type": "audio",
"url": "https://science.nasa.gov/wp-content/uploads/2024/03/48520_E1-PIA26041-The_Sound_of_MOXIE_at_Work_on_Mars.wav",
"name": "Secret Code.wav"
}
]
}
```
{% endtab %}
{% tab title="Execution" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2FsV7Plx67LDkdi68RTmRP%2FScreenshot%202024-05-20%20at%2011.51.01%20AM.png?alt=media&token=6a57f557-aa64-40c0-8cbd-f64759a4e7e1" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}
#### Video response
To display a playable video file to the user, use the following data structure
```json
{
"type": "video",
"url": "<VIDEO_URL>",
"name": "<VIDEO_NAME>.<FILE_EXTENSION>"
}
```
Remember to include the file extension within the video's name to allow the user to open it using the intended file format, e.g. mp4, mpg
{% tabs %}
{% tab title="Story" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2FBSwAjRn8PpIwJSLqzqDC%2FScreenshot%202024-05-20%20at%2012.01.01%20PM.png?alt=media&token=a3e55f71-17b4-4fa3-a734-854c399f3154" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% tab title="API" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2FBqDyNS2Nm8MSgKaib1mR%2FScreenshot%202024-05-20%20at%2012.00.54%20PM.png?alt=media&token=a06f7bd8-0c81-426b-b57c-0e60bec2f606" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% tab title="Webhook Response" %}
```json
{
"responses": [
{
"type": "video",
"url": "https://i.imgur.com/UDWU7r7.mp4",
"name": "Unboxing Camera.mp4"
}
]
}
```
{% endtab %}
{% tab title="Execution" %}
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2F13iNaGRuI4dVnsq5Fm1R%2Fvideo_webhook.gif?alt=media&token=126b52dc-5bcb-42b9-8bf1-2c1f8fc4f799" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}
## Testing Webhooks
You may test your webhooks using the Test Webhook button within the webhook editor
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2FP8xcrDRNmpgUYRAHfYXK%2FScreenshot%202024-05-20%20at%2012.16.21%20PM.png?alt=media&token=acdf864c-877f-4e8a-8a96-c8895578887a" alt=""><figcaption><p>Test Webhook button</p></figcaption></figure>
When you click the button, a window will pop up with two panes. The left pane allows you to edit the inputs of the webhook directly, and the right pane shows you the output - the preview of what the webhook's response will look like within the chatbot's response. You can click the **Retest** button below the right pane to refresh the output from the webhook
<figure><img src="https://2535542804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LirAdLo22OkAW9w3tvY%2Fuploads%2F00LrCmNUzn82U5eB73kL%2FScreenshot%202024-05-20%20at%2012.15.06%20PM.png?alt=media&token=9c38db03-d476-4f77-ab28-cea8f1752183" alt=""><figcaption></figcaption></figure>
Remember to substitute variables within your URL, Headers, Query Params, and JSON Body Params with string values while testing. E.g. if you are sending a variable `{{user.first_name}}` in any of the webhook fields, remember to change it to the user's actual first name, e.g. `John`. The Webhook Tester assumes the strings sent in the request are the final values.
.png?alt=media&token=db99e83c-86b0-4a15-8e36-40e55f54525d)
.png?alt=media&token=8c2e8c82-8e1d-44a3-a4e4-aea497e84d65)
.png?alt=media&token=9d9820f8-692f-4fa3-b56c-0f6de55d2527)
.png?alt=media&token=0f1d0651-470c-4d08-a7b2-0d10bccfd0ce)
.png?alt=media&token=0f0c0910-e519-4c16-ad95-5d28939b7e24)
.png?alt=media&token=170b0c48-38f8-4bb8-a7ff-f50d6c70d10a)
.png?alt=media&token=3261249a-fc3e-4eb0-a10c-1aa124d05e14)
.png?alt=media&token=91bea328-7c53-4ff1-bd1e-72eab8faa6a8)
.png?alt=media&token=f995107a-12e1-41d5-b164-6359067d8a28)
