Chatbot Overview
Conversational Bots
Intents & Entities
Intelligent Bots's Approach Conversational Platform
Bot Concepts and Terminology
Natural Language Processing (NLP)
Bot Types
Bot Tasks
Starting with Platform
How to Access Bot Builder
Working with Bot Builder
Building your first Bot
Getting Started with Building Bots
Using the Dialog Builder Tool
Creating a Simple Bot
Release Notes
Latest Updates
Older Releases
Bot Builder
Creating a Bot
Dialog Task
User Intent Node
Dialog Node
Entity Node
Supported Entity Types
Composite Entities
Supported Time Zones
Supported Colors
Supported Company Names
Form Node
Logic Node
Message Nodes
Confirmation Nodes
Service Node
Custom Authentication
2-way SSL for Service nodes
Script Node
Agent Transfer Node
WebHook Node
Grouping Nodes
Connections & Transitions
Managing Dialogs
User Prompts
Alert Tasks
Alert Tasks
Ignore Words and Field Memory
Digital Forms
Digital Views
Knowledge Graph
Importing and Exporting
Knowledge Extraction
Small Talk
Action & Information Task
Action Tasks
Information Tasks
Establishing Flows
Natural Language
Machine Learning
Model Validation
Fundamental Meaning
NLP Settings and Guidelines
Knowledge Graph Training
Ranking and Resolver
NLP Detection
Advanced NLP Configurations
Bot Intelligence
Context Management
Session and Context Variables
Context Object
Dialog Management
Amend Entity
Multi-Intent Detection
Sentiment Management
Tone Analysis
Sentiment Management
Default Conversations
Default Standard Responses
Channel Enablement
Test & Debug
Talk to Bot
Utterance Testing
Batch Testing
Record Conversations
Publishing your Bot
Analyzing your Bot
Custom Dashboard
Conversation Flows
Bot Metrics
Advanced Topics
Bot Authorization
Language Management
Collaborative Development
IVR Integration
Data Table
Universal Bots
Enabling Languages
Smart Bots
Sample Bots
Travel Planning
Flight Search
Event Based Bot Actions
koreUtil Libraries
Bot Settings
Bot Functions
General Settings
PII Settings
Customizing Error Messages
Manage Sessions
Bot Management
Bot Versioning
Using Bot Variables
API Guide
API Overview
API List
API Collection
SDK Overview
SDK Security
SDK App Registration
Web SDK Tutorial
Message Formatting and Templates
Mobile SDK Push Notification
Widget SDK Tutorial
Widget SDK – Message Formatting and Templates
Web Socket Connect & RTM
Using the BotKit SDK
BotKit SDK Tutorial – Agent Transfer
BotKit SDK Tutorial – Flight Search Sample Bot
Using an External NLP Engine
Bot Administration
Bots Admin Console
User Management
Managing Users
Managing Groups
Managing Role
Bots Management
Inviting Users
Bulk Invites
Importing Users
Synchronizing Users from AD
Security & Compliance
Using Single Sign-On
Security Settings
Cloud Connector
How Tos
Creating a Simple Bot
Creating a Banking Bot
Transfer Funds Task
Update Balance Task
Context Switching
Using Traits
Schedule a Smart Alert
Configure Digital Forms
Add Form Data into Data Tables
Configuring Digital Views
Add Data to Data Tables
Update Data in Data Tables
Custom Dashboard
Custom Tags to filter Bot Metrics
Patterns for Intents & Entities
Build Knowledge Graph
Global Variables
Content Variables
Using Bot Functions
Configure Agent Transfer
  1. Home
  2. Docs
  3. Bots
  4. Channel Enablement
  5. Adding WebHook as a channel

Adding WebHook as a channel

Webhook channel provides a generic webhook integration to connect your bot with any external communication systems. platform provides standard request and response APIs to be used to send and receive text messages. End user’s input through a voice, keypad, or any other means needs to be converted to plain text before it is sent to the platform using the request API.

NOTE: From ver 7.0 you can enable multiple WebHook channels to your Bot, once added the WebHook channel will not be disabled from the Channel list and you can use the same process to enable another WebHook channel with a different name. The webhook channels with name and type mentioned (webhook ) will be available at channels filter at the dashboard and analyze section to views the metrics on the applied channel. You will be able to apply channel-specific overrides for each of the webhook channels created/enabled – channel selection drop will show all the webhook channels created. Further, all the channels will be available for selection during the Bot deployment.


To enable the Webhook channel for your bot, you need to:

  1. Associate App--To enable the Webhook channel for your bot, you need to associate the channel with either an existing app in your account or create a new app.
  2. Select Integration Mode- You will need to enable an integration mode that is supported by the channel based on your business requirement. You can copy the Webhook URL from the configurations tab of the channel.
  3. Review Payload Formats- Review Payload formats for verifying the integration.

To access Bot Platform’s public APIs, the application making the API request requires authentication. uses the JWT (JSON Web Token) technology to handle the authentication. For a quick overview of the JWT token, read Introduction to JWT tokens.

Configuring Webhook as a channel

  1. In the Bots section of the Bot Builder, click the Bot to which you want to add the Webhook channel.
  2. On the Channels tab, click the Webhook icon. The Webhook page gets displayed.
  3. Navigate to Configurations tab of this page and associate this channel with an app.
  4. Give a Name to the Channel.
  5. You may select any of the existing Apps available in your account or create a new app.
  6. Enter a name for the app and click Create. The app gets created and Client ID and Client Secret is generated. Copy the Client ID and Client Secret details.
  7. Webhook channel supports both synchronous and asynchronous modes and depending on your business needs, you can enable one of these modes in the Configurations tab.
    • Synchronous mode delivers full response directly to the incoming requests. Note: Alert can not be set up webhook on webhook channel in synchronous mode, you may want to consider using the onAlert event through BotKit, refer here for details.
    • Asynchronous mode defines the POST_URL of your external system and Access Token to be used for delivering partial or full responses. When hit, the WebHook URL will receive an empty message with 200 status code, the response message will be sent to the POST_URL defined.
  8. Select Yes to Enable Channel.
  9. Save the configuration. The Webhook URL at this channel instance will be created dynamically.
  10. Use the Webhook URL to establish integration with external communication systems. This URL will be available only after enabling the channel.

After completion of these steps, a success message appears on the screen, and a channel request is sent to your Bots Admin for approval.


  • The channel remains non-functional until the Bots Admin approves it.
  • In the case of Bot Import, WebHook channels will also be imported. You would need to configure the channels which are created with the import and associate the channels with an application.
  • In the case of Smart Bots, if the parent has webhook channels configured, these channels will be inherited to the child bots. The channel is inheritance happens to child bot every time a new webhook channel is added at the parent and published.

WebHook API Reference

Receives plain text messages from external communication systems

  • in case of single webhook configuration and in case of multi-webhook configuration for the first instance
    POST  {{host_url}}/chatbot/hooks/{{bot id}}
  • in case of multi-webhook configuration for the second instance onwards:
    POST  {{host_url}}/chatbot/hooks/{{bot id}}/hookInstance/{{webHookId}} 
Query Parameters
Parameter Description
host_url Your Bots Platform URL.
bot id The ID of the bot to which you want to post messages. You can access it from the General Settings page of the bot.

Invoke the API with JWT in the header with the following syntax:

Authorization: bearer {{JWT}}

Generate JWT using the following header and payload from this page.

JWT Header

  "alg": "HS256",
  "typ": "JWT"

JWT Payload

  "appId": "{{clientId of the bot}}",
  "sub" : "{{random number}}"

Note: JWT should be generated and signed by the secret key from the server(backend). JWT should not be generated in the browser. The Secret Key should be kept in the server.

Response content type
Sample Payload Reference
payload : {
             "text" : "Hi",
             "attachments" : [<array of attachment links>]
           "from" :{
             "id": <unique-id-of-sender(mandatory)>
          "mergeIdentity" :<true/false>,
          "preferredChannelForResponse":"<channel name>" //the channel context to be used to generate a response   
Sample cURL
curl -X POST
//{{host_url}}/chatbot/hooks/{{bot id}}/hookInstance/{{webHookId}} in case of multi-webhook configuration
 -H 'authorization: bearer {{JWT Token}}'
 -H 'content-type: application/json'
 -d '{ "message": { 
          "text": "hi" }, 
       "from": { 
          "id": "1323465" }, 
       "mergeIdentity" :true,
Synchronous Response
  "text" : "message"

If the response that needs to sent back is of a template, then the template JSON object will be included in the text array object. Refer here for more on message templates.

Asynchronous Response

When the client app sends the request to Webhook URL configured in Asynchronous mode, the platform responds back with an empty message and a status code 200.


Further, the platform sends the response to the POST_URL configured at the channel based on the request received from the client app.

Following is the format of the response sent to the POST_URL. If the response that needs to sent back is of a template, then the template JSON object will be included in the text array object. Refer here for more on message templates.

 "text" : "message",
 "from" : "from_id",
 "mergeIdentity" :<true/false>

Handling Digital Forms

If your bot has a form that needs user input, for synchronous WebHook channel would be getting the complete form definition in the response and you need to send the formData in the request when interacting with the bot.

Sample Response

    "text": [],
    "form": {
        "formDef": { Formdef },
        "formInitialization": { FormInitialization } //if any
    ..other params if any

(This is the complete Form definition which is used to render the Form)

  "_id": "",
  "refId": "",
  "streamId": "st-####a#d-##fd-#b##-acab-b#f#f######",
  "branding": { 
     "properties": []
  "components": [
     "_id": "fct-#f#e###d-d#b#-###a-#a##-######f###b",
     "refId": "#####f##-###c-###b-##a#-da########1d",
     "metaData": {
         "type": "textField",
         "key": "textField",
         "displayName": "Text Field",
         "name": "TextField0",
         "placeholder": "Provide your input",
         "toolTip": "",
         "isVisible": true,
         "required": false,
         "validations": {
            "validationType": "simple"
         "validateOn": "onBlur"
     "name": "TextField0",
     "type": "textField"
    "_id": "fct-#f#e###d-d#b#-###a-#a##-######f###b",
    "refId": "#####f##-###c-###b-##a#-da########1d",
    "metaData": {
       "type": "textField",
       "key": "textField",
       "displayName": "Text Field",
       "name": "TextField1",
       "placeholder": "Provide your input",
       "toolTip": "",
       "isVisible": true,
       "required": false,
       "validations": {
          "validationType": "simple"
       "validateOn": "onBlur"
      "name": "TextField1",
      "type": "textField"
     "_id": "fct-#f#e###d-d#b#-###a-#a##-######f###b", 
     "refId": "#####f##-###c-###b-##a#-da########1d",
     "metaData": {
        "key": "button",
        "type": "button",
        "displayName": "Submit",
        "name": "Submit",
        "buttonAction": "submit",
        "isVisible": true,
        "buttonStyle": "primary",
        "sourceUrl": ""
     "name": "Submit",
     "type": "button"
   "description": "regular",
   "displayName": "Form 1",
   "name": "firstForm",
   "type": "regular", 
   (... few other fields)

(This should be used for pre-filling Forms)

       "valueMap": {
       "TextField0": "input1",
       "TextField1": "input2"

Sample Request

    "session": {
        "new": false
    "message": {
        "formData": {
            "formId": "frm-2b2f1ae4-9a3b-5f22-8940-b6827710940f",
            "data": [
                    "componentId": "fct-9f7e487d-d4b8-542a-9a77-7806819f141b",
                    "input": "input1"
                    "componentId": "fct-7aae4eae-2ce7-5d1b-8db1-bb5cfadc3342",
                    "input": "input2"
            "meta": {}
    "from": {
        "id": ""
    ..others params if any