Adding WebHook as a channel

Webhook channel provides a generic integration framework to connect your virtual assistant with any external communication systems. Kore.ai XO Platform provides standard request and response APIs to send and receive messages in text format. The end user’s input through a voice, keypad, or any other means must be converted to plain text before it is sent to the Kore.ai XO Platform using the Request API.

Webhook V1.0

Version 1.0 of the Webhook supports simple request and response interfaces for enabling the communication between your custom channel interface and the platform. It is recommended to use the Webhook V2.0 as it supports standardized and modular payloads for exchanging messages and events.

Interaction Flow

Authorization

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.

Response content type

application/json

Request Parameters

The following are the parameters required/supported in the v1.0 of the Webhook channel

session

new

message

text

attachments

{"url":"https://- - "}

from

id

userInfo

firstName

lastName

email

userLevelTags

sessionLevelTags

messageLevelTags

mergeIdentity

preferredChannelForResponse

customData

Sample Request Payload Reference

Below is the Webhook v1 payload format to send messages to the Kore.ai XO Platform:

{ 
	 "session" : {     
                "new" : true
                },
"message": { 
"text": "hi",
"attachments" : 
 	}, 
 	"from": { 
"id": "User01",
	"userInfo" :{
                       "firstName" : “John”,
                       "lastName" : “Doe”,
                       "email" : “john.doe@acme.org”
		}
 },
"metaTags": {
          		"userLevelTags": [
              		{
                  		"name": "customerType",
                  		"value": "Premium"
              		}
          		],
          		"sessionLevelTags": [
              		{
                  "name": "location",
                  "value": "Americas"
              }
],
          "messageLevelTags": [
            		{
                  "name": "messageTag",
                  "value": "messageTag_value"
              }
]
   	    },  
"mergeIdentity" :true,
"preferredChannelForResponse":"rtm",
"customData": {
"name":"John",
"Age":30,
"products": {
"CheckingAccount":"Active",
"LoanAccount":"Inactive",
"CreditCard":"Active"
}
}
 }

You can send additional data from the Webhook channel by including it in the request payload using the customData object. The customData along with the full payload will be available as part of the context.session.BotUserSession.lastMessage object.

Response

The response contains the following fields:

• to– refers to the user to whom the message is delivered to.
• from – identity (Stream Id) of the bot from which the response is generated.
• text – contains the response(s) from the bot. Can be a string, object or an array of strings or objects.
• endOfTask – indicating whether the task was completed or not, values true or false.
• endReason– the reason for the task completion – fulfilled, interrupted, or canceled
• completedTaskId– the id of the dialog task triggered.
• completedTaskName – the name of the dialog task triggered.

If the bot response is a template, then the JSON object required for rendering the template is included in the ‘text’ field as an object or array of objects.

"customData": {"name":"John","age":30,"cars": 
                             {"car1":"Ford","car2":"BMW","car3":"Fiat"}},

Sample Response for Synchronous Mode

{
  "text": [
            "You have $45,000 in your Salary account.",
            "Let me know if you need any other assistance"
           ],
  "endOfTask": true,
  "endReason": "Fulfilled",
  "completedTaskId": "dg-eb0cc36e-06ac-5bff-8234-e4adf501a2ef",
  "completedTaskName": "show balance"
}

Note: The ‘text’ field can contain a string, object or an array of strings or objects.

Sample Response for Asynchronous Mode

{
"to": "john.doe@kore.com",
"from": "st-b3a3dc49-bd57-5c5d-b12c-8e3776192a4c",
"text": "Your available account balance is $31,439.",
}

For Asynchronous integration mode, the platform sends an acknowledgement response to the incoming request with Status Code as 200. The bot response to be delivered to the user is sent to the Post_URL configured for the channel.

• The text field can contain a string, object or an array of strings or objects.
• Separate messages are sent for every bot response to be delivered to the user.
• The conversation flow related fields like “endOfTask“, “endReason“, “completedTaskId” and “completedTaskName“: “show balance” are delivered as a separate message.

Webhook V2.0

The Webhook V2 API provides a more standardized and modular payload format, and also provides additional conversation management capabilities.

Interaction Flow

Authorization

User Identity

The Webhook V2.0 allows you to authenticate the API call with JWT token user identity. If the user identity (‘from’ field) exists in both request payload and JWT token, then the Webhook v2 validates the user identity. Use the following payload for authentication with user identity:

JWT Payload

{
  "appId": "{{clientId of the bot}}",
  "sub" : "{{random number}}"
  "userIdentity": "{{unique user identity}}",
  "iat" : 161639822 
  }

• If the userIdentity is not present in JWT, you can validate the userIdentity authentication using the appId and the from value will be used to generate the userId in the Kore platform..
• If the userIdentity is present in JWT as well as from but both are NOT same, then authentication will be failed and throws an error saying that Invalid access token.
• The userIdentity is present in JWT and from is present in webhook payload and both userIdentity and from are same then it will check against the authentication against the appId and proceed further.

Request Parameters

The following are the parameters required/supported in the v2.0 of the Webhook channel

session

new

message

type

val

attachments

{"url":"https://- - "},
{ "fileName": "Kore_ai_Logo.png", "fileType":"image", "fileId": "6163e17bf60e0xxxxxxxx" }

from

id

InteractiveLanguage

userInfo

firstName

lastName

email

metaTags

userLevelTags

sessionLevelTags

messageLevelTags

mergeIdentity

preferredChannelForResponse

customData

Sample Request

Below is the Webhook v2.0 payload format to send messages to the Kore.ai XO Platform:

{
  "session": {
    "new": true
  	},
  "message": {
  	"type": "text",
"val": "Hi",
 	"attachments": 
  	},
  "from": {
"id": "",
"userInfo": {
"firstName": "",
"lastName": "",
"email": ""
}
},
  "metaTags": {
"userLevelTags": [
{
                  		"name": "customerType",
                  		"value": "Premium"
              	}
          	],
"sessionLevelTags": [
{
                  "name": "location",
                  "value": "Americas"
 }
],
"messageLevelTags": [
            		{
                  "name": "messageTag",
                  "value": "messageTag_value"
              }
]
    },  
"mergeIdentity" :true,
"preferredChannelForResponse":"rtm",
"customData": {
"name":"John",
"Age":30,
"products": {
"CheckingAccount":"Active",
"LoanAccount":"Inactive",
"CreditCard":"Active"
}
}
}

OnConnect Event Request

The Webhook V2.0 supports the OnConnect event as part of the first user message. You can pass the OnConnect as an event parameter. Here is an example on how to trigger the onConnect event:

{
  "session": {
    "new": true
  },
  "message": {
    "type": "event",
    "val": "ON_CONNECT",
    },
  "from": {
    "id": "",
    "userInfo": {
      "firstName": "",
      "lastName": "",
      "email": ""
    }
  }
}

Response

The response contains the following fields:

• to– refers to the user to whom the message is delivered to.
• from – identity (Stream Id) of the bot from which the response is generated.
• text – contains the response(s) from the bot. Can be a string, object or an array of strings or objects.
• endOfTask – indicating whether the task was completed or not, values true or false.
• endReason– the reason for the task completion – fulfilled, interrupted, or canceled
• completedTaskId– the id of the dialog task triggered.
• completedTaskName – the name of the dialog task triggered.

Change Conversation Language Request

To change the language of an ongoing conversation, you can pass the interactiveLanguage as a parameter with a value (language code) of one of the VA languages that are configured.

To change the conversation language from English (en) to French (fr), pass the value as “fr” in the interactiveLanguage parameter:

Sample Request

{
  "session": {
    "new": true
  },
  "message": {
    "type": "text",
    "val": "help",
    },
  "from": {
            "id": "userId"
    },
   "to": {
            "id": "streamId"
    },
    "interactiveLanguage":"fr"
  }
}

For the list of Supported Bot Languages codes, read Getting Started with Multilingual Virtual Assistant article.

Close Conversation Session Event Request

The Webhook V2.0 supports the closeConversationSession event as part of the user message. You can pass the Session_Closure as an event parameter.

Here is a sample request to trigger the Session_Closure event:

Sample Request

{
  "session": {
    "new": true
  },
  "message": {
    "type": "event",
    "val": "SESSION_CLOSURE",
    },
  "from": {
            "id": "userId"
    },
   "to": {
            "id": "streamId"
    },
  }
}

Sample Responses

The following are the possible response scenarios.

Sample Response for Synchronous Mode

Scenario 1: Response without need for polling

The platform delivers the message or messages to the client and waits for the user input to continue any ongoing flow or initiate new flow.

Response:
{
 "to": "john.doe@kore.com",
 "from": "st-b3a3dc49-bd57-5c5d-b12c-xxxxxxxxxx",
 "data": [
        {
            "type": "text",
            "val": "The balance in your Salary Account ending with 3984 is $54,883",
            "createdOn": "2022-05-11T06:27:06.764Z",
            "messageId": "ms-16535527-0f27-5116-bee3-xxxxxxxx"
        },
        {
            "type": "text",
            "val": "The balance in your Checking Account ending with 9964 is $21,657",
            "createdOn": "2022-05-11T06:27:07.032Z",
            "messageId": "ms-e3e92480-3d23-50a7-a2e5-xxxxxxxxxxx"
        }
    ],
    "_v": "v2",
    "endOfTask": false,
    "endReason": "Fulfilled",
    "completedTaskId": "dg-79950d7e-cdc6-5ff4-a4be-xxxxxxxxx",
    "completedTaskName": "Show Balance"
}

Scenario 2: Responses with need for polling

If there are one or more Service / Script / Webhook nodes between messages, the platform delivers the messages along with a ‘pollid’ to the incoming request. The client should implement a polling framework to process the flow using the ‘pollid’ provided by the platform.

• The platform delivers the first message or set of consecutive messages along with a ‘pollid’ to the incoming request
• The client should make a poll request to the platform using the ‘pollid’ provided by the platform in the response to the original request
• The response to the poll request can result in one of the following:
  • The ‘status’ is returned as ‘Inprogress’ if the execution of service / script / webhook nodes is still in progress.
  • The response will include the message payload if the execution of service / script / webhook is completed.
  • The response will give an error message if the message for a ‘pollid’ is already delivered to the client.

Response with messages and ‘pollid’

The platform delivers the first message or set of consecutive messages along with a ‘pollid’ to the incoming request. The platform initiates the execution of Service / Script / Webhook nodes.

{
    "data": [
        {
            "type": "text",
            "val": "Sample message for Message0013",
            "createdOn": "2022-05-11T06:48:50.801Z",
            "messageId": "ms-3a3538a7-91b8-5c09-af72-xxxxxxxx"
        }
    ],
    "_v": "v2",
    "pollId": "a69b1077c3541e76253be58aa340950b"
}

Response to poll request when the execution is in progress

URL:	   /chatbot/v2/webhook/:streamId/poll/:pollId
Method: GET
{
   "status": "Inprogress",
   "pollId": "a89627d5b85ba70257871bxxxxxxxxxe",
   "_v": "v2"
}

Response to poll request when the execution is complete

If the processing of service / script / webhook is completed, then the platform responds to the poll request with the message payload.

• The response format will be the same the regular response.
• If the flow execution includes execution of service / script / webhook nodes, then the response will include a new ‘pollid’ to be used for subsequent execution.

Response to expired poll request

The messages for a ‘pollid’ are provided by the platform only once. The platform responds with an error message if the client makes a poll request for a ‘pollid’ for which the platform has already delivered the messages.

{
   "errors": [
       {
           "msg": "No data found",
           "code": 400
       }
   ]
}

Response when polling is disabled

When you deselect the Enable the Polling in Webhook V2 option in the Configurations tab, the platform retrieves the complete response, all at once, without the need for polling. Learn more.

Sample Response:

{
"data": [
{
"type": "text",
"val": ""The City Name is Kondapur""The State Name is Telangana"",
"createdOn": "2022-09-29T07:17:52.451Z",
"messageId": "ms-e941520d-a512-5dac-98e3-xxxxxxxxx"
},
{
"type": "text",
"val": "End of Conversation Event",
"createdOn": "2022-09-29T07:17:52.741Z",
"messageId": "ms-e9473e2b-a8f8-5628-9146-xxxxxxxxx"
}
],
"_v": "v2",
"endOfTask": true,
"endReason": "Fulfilled",
"completedTaskId": "dg-2e50c369-ae83-50cb-9abf-xxxxxxxx",
"completedTaskName": "get state name"
}

Response as a Request to Post URL

Then use the pollId from the Response#1 to get the response of the second Message node.

Here is the sample curl to use pollId to fetch the response:

curl --location --request GET 'https://bots.kore.ai/chatbot/v2/webhook/st-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx/poll/a69b1077c3541e762xxxxxxxxx0b' \
--header 'Authorization: bearer ' \
--header 'Content-Type: application/json' \
--data-raw ''

{
    "data": [
        {
            "type": "text",
            "val": "Current weather haze",
            "createdOn": "2022-05-11T06:48:51.545Z",
            "messageId": "ms-0421201b-6c7e-59a6-9246-xxxxxxxxx"
        },
        {
            "type": "text",
            "val": "Let me know if you need any other assistance",
            "createdOn": "2022-05-11T06:48:52.138Z",
            "messageId": "ms-c533f0d8-4495-58f8-9839-xxxxxxxxxx"
        }
    ],
    "_v": "v2",
    "endOfTask": true,
    "endReason": "Fulfilled",
    "completedTaskId": "dg-xxxxx-xxxx-xxxx-xxxx-xxxxxxx",
    "completedTaskName": "current weather"
}

Change Conversation Language Response

Here is the sample response for the change conversation language:

{
    "data": [
        {
            "type": "text",
            "val": ""Voici les tâches que je peux effectuer pour vous.\n a) ADialog \n b) BDialog \n c) Get user data \n 
            d) Raise Complain \n e) Search song \n",
            "createdOn": "2022-07-28T07:06:55.843Z",
             "messageId": "ms-d4ca9e2e-6d2d-xxxx-xxxx-xxxxxxxxx"

        },
        {
            "type": "text",
            "val": "Salut, comment puis-je vous aider?",
            "createdOn": "2022-07-28T07:06:55.843Z",
            "messageId": "ms-d4ca9e2e-6d2d-xxxx-xxxx-xxxxxxxxx"
        }
    ],
    "_v": "v2",
    "endOfTask": true,
    "endReason": "Fulfilled",
    "completedTaskId": "dg-xxxxx-xxxx-xxxx-xxxx-xxxxxxx",
    "completedTaskName": "welcome_task"
}

Close Conversation Session Event Responses

Here are sample responses for the SESSION_CLOSURE:

Response 1: When an active session does exist

{
    "data": [
        {
            "type": "event",
            "val": "SESSION_CLOSURE",
            "eventType": "SESSION_CLOSURE_IGNORED",
             "description": "Active session doesn't exist"
}

Response 1: When an active session exists

{
    "data": [
        {
            "type": "event",
            "val": "SESSION_CLOSURE",
            "eventType": "SESSION_CLOSURE_SUCCESS",
             "description": "session closed successfully",
        }
      ],
   "_v": "v2"
}

Sample Response for Asynchronous Mode

The POST_URL is the customer’s own asynchronous URL to send and receive requests. Kore.ai does not provide any POST _URL for Asynchronous setup because this URL is different from customer to customer.

The following response is an example for a successful asynchronous call:

Request Acknowledgement

{
  "status": "ok"
  "_v": "v2",
  "traceId":"RTM-TRACE-9JOHE3ALB"
}

Response as a Request to Post URL

{
   "data": [
       {
           "type": "text",
           "val": "Please provide your account number",
           "createdOn": "2021-10-11T13:44:34.675Z"
       }
   ],
   "_v": "v2",
}

For Asynchronous integration mode, the platform sends an acknowledgement response to the incoming request with Status Code as 200. The bot response to be delivered to the user is sent to the Post_URL configured for the channel.

• The ‘text’ field can contain a string, object or an array of strings or objects.
• Separate messages are sent for every bot response to be delivered to the user.
• The conversation flow related fields like “endOfTask“, “endReason“, “completedTaskId” and “completedTaskName“: “show balance” are delivered as a separate message.

Support for Attachments

The Webhook API can be used to send attachments from the end users to the bot. Files can be sent in multiple ways

Option 1: Upload Files from Web URLs

You can upload files that are hosted on external services by providing the Web URL of the file location. Make sure that the URL is accessible by the platform. Following is an example:

{
  "session": {
    "new": true
  },
  "message": {
    "type": "{}",
    "val": "image",
    "attachments": ""
  },
  "from": {
    "id": "",
    "userInfo": {
      "firstName": "",
      "lastName": "",
      "email": ""
    }

Option 2: Upload Files to Kore.ai XO Platform

You can upload files directly to the Kore.ai XO Platform, capture the ‘file id’ provided by the platform and share it with the bot during the conversation. This option is supported only when the Webhook v2.0 is used.

Use the following API to upload your file to the platform. These APIs do not require any scopes and are accessible using any of the valid apps present in the bot/account.

Request
URL:  /api/attachments/file/:streamId/:channelType
Method: POST
Body:
{
file:,
fileContext :,
fileExtension : ,
filename:
}

Response

Response: {
fileId:
hash: 
}

You can use the following API to upload file in chunks

Token API

URL: /api/attachments/:streamId/:channelType/token
Method: POST
Headers: {
authorization:bearer jwttoken
}
Body:{
}

Chunk Upload API

URL: /api/attachments/:streamId/:channelType/token/:token/chunk
Method: POST
Headers: {
authorization:bearer jwttoken
}
Body:{
chunk:””,
chunkNo:2
}

Commit API

URL: /api/attachments/:streamId/:channelType/token/:token/chunk
Method: PUT
Headers: {
authorization:bearer jwttoken
}
Body:{
fileContext:””,
filename:””,
totalChunks:””,
fileExtension:””
}

Note: You can also use the filename or fileID to upload a file. For example, use this syntax to upload a file with name and ID: { "fileName": "Kore_ai_Logo%405x.png", "fileType":"image", "fileId": "6163e17bf60e0a7e4799f423" }.

Handle Digital Forms

If your bot has a form that needs user input, the synchronous WebHook channel gets 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
}

FormDef
(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)
}

FormInitialization
(This must 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
}

Error Scenarios in Webhook v2 Responses

The following is the failure response for 401 Error:

{	
  "errors": [
    {
      "msg": "Invalid Access token",
      "code": 401
    }
  ],
  "_v": "v2", //versionId
  "_t": "RTM-TRACE-9JOHE3ALB" //traceId
}

The following is the failure response for 429 Error (Rate Limit)

{
  "errors": [
    {
      "msg": "Too Many requests",
      "code": 429
    }
  ],
  "_v": "v2", //versionId
  "_t": "RTM-TRACE-9JOHE3ALB" //traceId
}

The following is the failure response for 504 Error:

{
  "errors": [
    {
      "msg": "The request has been timed-out",
      "code": 504
    }
  ],
  "_v": "v2", //versionId
  "_t": "RTM-TRACE-9JOHE3ALB" //traceId
}

The following is the failure response for 400 Error:

{
  "errors": [
    {
      "msg": "Invalid Request Payload",
      "code": 400
    }
  ],
  "_v": "v2", //versionId
  "_t": "RTM-TRACE-9JOHE3ALB" //traceId
},