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:

• Setting up your Webhook
• What is verification request
• Troubleshooting Webhooks

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

• [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

Available Bot Responses

List of available bot responses:

• Text message
• Random Text message
• Image
• Quick Replies
• Cards
• Buttons

Text message

{
  "type": "text",
  "message": "foo bar baz"
}

Random Text message

{
  "type": "randomText",
  "messages": [
    "foo",
    "bar",
    "baz"
  ]
}

Image

{
  "type": "image",
  "imageUrl": "https://www.chatbot.com/logo.png"
}

Quick Replies

{
  "type": "quickReplies",
  "title": "foo bar baz",
  "buttons": [
    {
      "type": "postback",
      "title": "foo",
      "value": "bar"
    },
    {
      "type": "postback",
      "title": "baz",
      "value": "qux"
    }
  ]
}

Cards

{
  "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

{
  "type": "cards",
  "title": "foo bar baz",
  "buttons": [
    {
      "type": "postback",
      "title": "foo",
      "value": "bar"
    },
    {
      "type": "postback",
      "title": "baz",
      "value": "qux"
    }
  ]
}

Button types

• Postback
• Go to
• URL
• Webview
• Phone

Postback

{
  "type": "postback",
  "title": "foo",
  "value": "bar"
}

Go to

{
  "type": "goto",
  "title": "foo",
  "value": "0e1a2425-76e3-49fd-bfc0-547603ab1fe3"
}

URL

{
  "type": "url",
  "title": "foo",
  "value": "https://chatbot.com"
}

Webview

{
  "type": "webview",
  "title": "foo",
  "value": "https://chatbot.com",
  "height": "full"
}

Phone

{
  "type": "phone",
  "title": "foo",
  "value": "+1234567890"
}

Webhooks API

List all connections

Lists all webhooks connected to the account.

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.

Request URL

curl --request POST \
	--url https://api.chatbot.com/v2/integrations/webhook \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'

Properties

Response Example

  {
    "id": "5ea8872dt3sd210a1586dab5",
    "timestamp": "2020-04-1T00:00:300.000Z",
    "status": {
      "code": 201,
      "type": "created"
    }
  }

List single connection

Lists single connection details.

Request URL

curl --request POST \
	--url https://api.chatbot.com/v2/integrations/webhook/:id \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'

URL Params

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.

Request URL

curl --request PUT \
	--url https://api.chatbot.com/v2/integrations/webhook/:id \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'

URL Params

Properties

Response Example

  {
    "timestamp": "2020-04-1T00:00:300.000Z",
    "status": {
      "code": 200,
      "type": "success"
    }
  }

Delete connection

Deletes existing webhook connection.

Request URL

curl --request DELETE \
	--url https://api.chatbot.com/v2/integrations/webhook/:id \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'

URL Params

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.