Webhooks
ChatBot webhooks allows you to easily return any Bot Response(s) or Attribute(s) directly from your external service to the ongoing chat. Thanks to Webhooks, you can connect the conversation context with any data stored on your backend side and return a bot message or attribute based on that.
When should I use Webhooks?
Webhooks allow you to make your bot story dynamic and different for every end-user. There are many use-cases in which Webhooks come in handy, but here are the few most popular ones:
- Checking if the visitor is our existing customer
- Providing VIP customers with special bot responses (for example: transfer to the agent for VIPs only)
- Returning account data to the end-user inside the chat (for example: account balance, contact details, subscription status)
- Activating customer account via ChatBot conversation
As you can notice, there is an unlimited number of ideas to cover with Webhooks, and this section will help you understand how you can implement Webhooks for your ChatBot story.
Setting up your first Webhook
Please go to our Help Center to see how to set up a Webhook step by step:
How ChatBot Webhooks works?
The idea of Webhooks is really simple:
- [1] Our ChatBot webhook service sends a POST request to your backend service with all of the data connected with the current chat. Example body of POST request sent by ChatBot:
{
"chatId": "602313f00000000000000000",
"messageId": "5a7fb3e1-8452-4aee-a7a9-2f0edaeb8e42",
"userId": "602313f00000000000000000",
"externalId": "26565d77-dd8f-4f34-bb46-4daaa8a22895",
"node": {
"id": "4b0d6bea-1a9b-4d29-bf23-85e8aa9619ae",
"name": "foo bar",
"type": "WEBHOOK",
"webhookId": "602313f00000000000000000",
"webhookName": "foo bar baz"
},
"userAttributes": {
"default_name": "User",
"default_email": "me@example.com"
},
"attributes": {
"foo": "bar",
"baz": ""
}
}
Properties
Property |
Description |
chatId |
ID of the current chat. |
messageId |
ID of the event. |
userId |
ID of the User chatting with the bot. |
externalId |
External ID of the User coming from our Channel Integrations (LiveChat, Facebook, Slack) |
node.id |
ID of the webhook block. |
node.name |
Name of the triggered webhook block. |
node.webhookId |
ID of the webhook configured in the webhook block. |
node.webhookName |
Name of the triggered webhook. |
userAttributes |
User attributes. |
attributes |
Attributes collected in the ongoing chat. |
- [2] After that, you can return in response to a Webhook with a Bot Response(s) or Attribute(s) that you can use later in your ChatBot story. For example:
{
"responses": [
{
"type": "text",
"delay": 1000,
"message": "Have a great day!"
}
],
"attributes": {
"foo": "bar",
"baz": ""
}
}
- [3] (optional) - You can also create a response in which you will return Attributes only, without any Bot Response. To do so, simply remove the “responses” part from your webhook’s code. You can use these Attributes with Filters attached right to the Webhook’s “Success” branch, and your bot will instantly redirect the end-user to the specific branch, depending on the filtered attribute value. For example:
{
"attributes": {
"foo": "bar",
"baz": ""
}
}
Properties
Property |
Description |
responses |
Array of the responses which you want to send from your backend service. |
attributes |
Object with the attributes passed from your backend service. |
Available Bot Responses
List of available bot responses:
Text message
parameter |
type |
required |
default |
type |
String valid(text ) |
required |
|
delay |
Number size(100, 10000) |
optional |
1000 |
message |
String size(1, 1024) |
required |
|
{
"type": "text",
"message": "foo bar baz"
}
Random Text message
parameter |
type |
required |
default |
type |
String valid(randomText ) |
required |
|
delay |
Number size(100, 10000) |
optional |
1000 |
messages |
Array size(1, 20) of String size(1, 1024) |
required |
|
{
"type": "randomText",
"messages": [
"foo",
"bar",
"baz"
]
}
Image
parameter |
type |
required |
default |
type |
String valid(image ) |
required |
|
delay |
Number size(100, 10000) |
optional |
1000 |
imageUrl |
String size(1, 2048) |
required |
|
{
"type": "image",
"imageUrl": "https://www.chatbot.com/logo.png"
}
Quick Replies
parameter |
type |
required |
default |
type |
String valid(quickReplies ) |
required |
|
delay |
Number size(100, 10000) |
optional |
1000 |
title |
String size(1, 640) |
required |
|
buttons |
Array size(1, 13) of Postback, Goto |
required |
|
{
"type": "quickReplies",
"title": "foo bar baz",
"buttons": [
{
"type": "postback",
"title": "foo",
"value": "bar"
},
{
"type": "postback",
"title": "baz",
"value": "qux"
}
]
}
Cards
parameter |
type |
required |
default |
type |
String valid(cards ) |
required |
|
delay |
Number size(100, 10000) |
optional |
1000 |
elements.title |
String size(1, 80) |
required |
|
elements.subtitle |
String size(1, 80) |
required |
|
elements.imageUrl |
String size(1, 2048) |
required |
|
elements.buttons |
Array size(1, 5) of Postback, Goto, URL, Webview, Phone |
required |
|
{
"type": "cards",
"elements": [
{
"title": "foo bar baz",
"subtitle": "foo bar baz",
"imageUrl": "https://www.chatbot.com/logo.png",
"buttons": [
{
"type": "postback",
"title": "foo",
"value": "bar"
},
{
"type": "postback",
"title": "baz",
"value": "qux"
}
]
}
]
}
parameter |
type |
required |
default |
type |
String valid(buttons ) |
required |
|
delay |
Number size(100, 10000) |
optional |
1000 |
title |
String size(1, 640) |
required |
|
buttons |
Array size(1, 5) of Postback, Goto, URL, Webview, Phone |
required |
|
{
"type": "cards",
"title": "foo bar baz",
"buttons": [
{
"type": "postback",
"title": "foo",
"value": "bar"
},
{
"type": "postback",
"title": "baz",
"value": "qux"
}
]
}
Postback
parameter |
type |
required |
default |
type |
String valid(postback ) |
required |
|
title |
String size(1, 20) |
required |
|
value |
String size(1, 2000) |
required |
|
{
"type": "postback",
"title": "foo",
"value": "bar"
}
Go to
parameter |
type |
required |
default |
type |
String valid(goto ) |
required |
|
title |
String size(1, 20) |
required |
|
value |
String size(36) UUIDv4 |
required |
|
{
"type": "goto",
"title": "foo",
"value": "0e1a2425-76e3-49fd-bfc0-547603ab1fe3"
}
URL
parameter |
type |
required |
default |
type |
String valid(url ) |
required |
|
title |
String size(0, 20) |
required |
|
value |
String size(0, 2048) |
required |
|
{
"type": "url",
"title": "foo",
"value": "https://chatbot.com"
}
Webview
parameter |
type |
required |
default |
type |
String valid(webview ) |
required |
|
title |
String size(1, 20) |
required |
|
value |
String size(1, 2048) |
required |
|
height |
String valid(full , tall , compact ) |
required |
compact |
{
"type": "webview",
"title": "foo",
"value": "https://chatbot.com",
"height": "full"
}
Phone
parameter |
type |
required |
default |
type |
String valid(phone ) |
required |
|
title |
String size(1, 20) |
required |
|
value |
String size(3, 16) \+[\d]{2,} |
required |
|
{
"type": "phone",
"title": "foo",
"value": "+1234567890"
}
Webhooks API
List all connections
Lists all webhooks connected to the account.
GET
https://api.chatbot.com/v2/integrations/webhook
Request URL
curl --request GET \
--url https://api.chatbot.com/v2/integrations/webhook \
--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'
Response Example
[
{
"id": "611f9ad1fe24s3d0007d14ad4",
"story": {
"id": "634fef70sd214d000073f5730",
"name": "Foo"
},
"name": "Package Tracking Bot",
"url": "https://webhooks.my-example-site.com/tracking",
"error": "Request failed with status code 404",
"createdAt": "2021-06-09T07:35:00.788Z",
"updatedAt": "2021-06-09T07:35:00.788Z"
},
{
"id": "5f5220d2er93050007ba7402",
"story": {
"id": "634fef70sd214d000073f5730",
"name": "Foo"
},
"name": "foo bar",
"url": "https://my-another-website.com",
"error": false,
"createdAt": "2021-06-09T07:35:00.788Z",
"updatedAt": "2021-06-09T07:35:00.788Z"
}
]
Create connection
Creates new webhook connection.
POST
https://api.chatbot.com/v2/integrations/webhook
Request URL
curl --request POST \
--url https://api.chatbot.com/v2/integrations/webhook \
--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'
Properties
Field |
Type |
Size |
Required |
storyId |
String |
size(24) |
Yes |
name |
String |
size(1,128) |
Yes |
url |
String |
size(1,1024) |
Yes |
token |
String |
size(1,1024) |
No |
headers |
Object<String, String> |
size(1,10) |
No |
auth |
Object |
|
No |
auth.username |
String |
size(1,1024) |
Yes |
auth.password |
String |
size(1,1024) |
Yes |
Response Example
{
"id": "5ea8872dt3sd210a1586dab5",
"timestamp": "2020-04-1T00:00:300.000Z",
"status": {
"code": 201,
"type": "created"
}
}
List single connection
Lists single connection details.
GET
https://api.chatbot.com/v2/integrations/webhook/:id
Request URL
curl --request POST \
--url https://api.chatbot.com/v2/integrations/webhook/:id \
--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'
URL Params
Parameter |
Type |
Required |
Size |
id |
String |
Yes |
size(24) |
Response Example
{
"id": "5f5220d1ce93050007ba7402",
"story": {
"id": "634fef70c56fd000073f5730",
"name": "Foo"
},
"name": "foo bar",
"url": "https://<your-webhook-url>.com",
"token": "secret-token",
"headers": {
"x-custom-header": "value"
},
"auth": {
"username": "foo",
"password": "bar"
},
"error": null, // string or null
"createdAt": "2021-06-09T07:35:00.788Z",
"updatedAt": "2021-06-09T07:35:00.788Z"
}
Update connection
Updates existing webhook connection.
PUT
https://api.chatbot.com/v2/integrations/webhook/:id
Request URL
curl --request PUT \
--url https://api.chatbot.com/v2/integrations/webhook/:id \
--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'
URL Params
Parameter |
Type |
Required |
Size |
id |
String |
Yes |
size(24) |
Properties
Field |
Type |
Size |
Required |
name |
String |
size(1,128) |
Yes |
url |
String |
size(1,1024) |
Yes |
token |
String |
size(1,1024) |
No |
headers |
Object<String, String> |
size(1,10) |
No |
auth |
Object |
|
No |
auth.username |
String |
size(1,1024) |
Yes |
auth.password |
String |
size(1,1024) |
Yes |
Response Example
{
"timestamp": "2020-04-1T00:00:300.000Z",
"status": {
"code": 200,
"type": "success"
}
}
Delete connection
Deletes existing webhook connection.
DEL
https://api.chatbot.com/v2/integrations/webhook/:id
Request URL
curl --request DELETE \
--url https://api.chatbot.com/v2/integrations/webhook/:id \
--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'
URL Params
Parameter |
Type |
Required |
Size |
id |
String |
Yes |
size(24) |
Response Example
{
"timestamp": "2020-04-1T00:00:300.000Z",
"status": {
"code": 200,
"type": "success"
}
}
Code Examples
JavaScript
Webhook example with Body Parser and ExpressJS - basic example webhook code that returns text message and sets sample attribute when called.
Setting attributes with webhooks in Visual Builder - example webhook code in which a contextual response is sent to the end-user and the attribute is set.
Setting attributes only (without returning any bot response) - example webhook code that sets specific attribute value, without any message being sent to the end-user.
Working Hours Detector - advanced webhook example that collects current time and returns different attributes depending on the time of the day. This allows you to filter by these values in your bot story and return different responses to the customers, depending on the time of the day.
PHP
Returning text response and setting attributes with PHP - basic example webhook code that returns text message and sets sample attribute when called.