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"
        }
      ]
    }
  ]
}

Buttons in Cards and Quick Replies

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"
    }
  ]
}

Button types

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.

Start a free ChatBot trial
and build your first chatbot today!

Free 14-day trial No credit card required

Discover our text| products