GETTING STARTED
Kore.ai XO Platform
Virtual Assistants Overview
Natural Language Processing (NLP)
Concepts and Terminology
Quick Start Guide
Accessing the Platform
Navigating the Kore.ai XO Platform
Building a Virtual Assistant
Help & Learning Resources
Release Notes
Current Version
Recent Updates
Previous Versions
CONCEPTS
Design
Storyboard
Overview
FAQs
Conversation Designer
Overview
Dialog Tasks
Mock Scenes
Dialog Tasks
Overview
Navigate Dialog Tasks
Build Dialog Tasks
Node Types
Overview
Intent Node
Dialog Node
Dynamic Intent Node
GenAI Node
GenAI Prompt
Entity Node
Form Node
Confirmation Node
Message Nodes
Logic Node
Bot Action Node
Service Node
Webhook Node
Script Node
Process Node
Agent Transfer
Node Connections
Node Connections Setup
Sub-Intent Scoping
Entity Types
Entity Rules
User Prompts or Messages
Voice Call Properties
Knowledge AI
Introduction
Knowledge Graph
Introduction
Terminology
Build a Knowledge Graph
Manage FAQs
Knowledge Extraction
Import or Export Knowledge Graph
Prepare Data for Import
Importing Knowledge Graph
Exporting Knowledge Graph
Auto-Generate Knowledge Graph
Knowledge Graph Analysis
Answer from Documents
Alert Tasks
Small Talk
Digital Skills
Overview
Digital Forms
Digital Views
Introduction
Widgets
Panels
Session and Context Variables
Context Object
Intent Discovery
Train
NLP Optimization
ML Engine
Overview
Model Validation
FM Engine
KG Engine
Traits Engine
Ranking and Resolver
Training Validations
NLP Configurations
NLP Guidelines
LLM and Generative AI
Introduction
LLM Integration
Kore.ai XO GPT Module
Prompts & Requests Library
Co-Pilot Features
Dynamic Conversations Features
Intelligence
Introduction
Event Handlers
Contextual Memory
Contextual Intents
Interruption Management
Multi-intent Detection
Amending Entities
Default Conversations
Conversation Driven Dialog Builder
Sentinment Management
Tone Analysis
Default Standard Responses
Ignore Words & Field Memory
Test & Debug
Overview
Talk to Bot
Utterance Testing
Batch Testing
Conversation Testing
Conversation Testing Overview
Create a Test Suite
Test Editor
Test Case Assertion
Test Case Execution Summary
Glossary
Health and Monitoring
NLP Health
Flow Health
Integrations
Actions
Actions Overview
Asana
Configure
Templates
Azure OpenAI
Configure
Templates
BambooHR
Configure
Templates
Bitly
Configure
Templates
Confluence
Configure
Templates
DHL
Configure
Templates
Freshdesk
Configure
Templates
Freshservice
Configure
Templates
Google Maps
Configure
Templates
Here
Configure
Templates
HubSpot
Configure
Templates
JIRA
Configure
Templates
Microsoft Graph
Configure
Templates
Open AI
Configure
Templates
Salesforce
Configure
Templates
ServiceNow
Configure
Templates
Stripe
Configure
Templates
Shopify
Configure
Templates
Twilio
Configure
Templates
Zendesk
Configure
Templates
Agents
Agent Transfer Overview
Custom (BotKit)
Drift
Genesys
Intercom
NiceInContact
NiceInContact(User Hub)
Salesforce
ServiceNow
Configure Tokyo and Lower versions
Configure Utah and Higher versions
Unblu
External NLU Adapters
Overview
Dialogflow Engine
Test and Debug
Deploy
Channels
Publishing
Versioning
Analyze
Introduction
Dashboard Filters
Overview Dashboard
Conversations Dashboard
Users Dashboard
Performance Dashboard
Custom Dashboards
Introduction
Custom Meta Tags
Create Custom Dashboard
Create Custom Dashboard Filters
LLM and Generative AI Logs
NLP Insights
Task Execution Logs
Conversations History
Conversation Flows
Conversation Insights
Feedback Analytics
Usage Metrics
Containment Metrics
Universal Bots
Introduction
Universal Bot Definition
Universal Bot Creation
Training a Universal Bot
Universal Bot Customizations
Enabling Languages
Store
Manage Assistant
Team Collaboration
Plan & Usage
Overview
Usage Plans
Templates
Support Plans
Invoices
Authorization
Conversation Sessions
Multilingual Virtual Assistants
Get Started
Supported Components & Features
Manage Languages
Manage Translation Services
Multiingual Virtual Assistant Behavior
Feedback Survey
Masking PII Details
Variables
Collections
IVR Settings
General Settings
Assistant Management
Manage Namespace
Data
Overview
Data Table
Table Views
App Definitions
Data as Service
HOW TOs
Build a Travel Planning Assistant
Travel Assistant Overview
Create a Travel Virtual Assistant
Design Conversation Skills
Create an ‘Update Booking’ Task
Create a Change Flight Task
Build a Knowledge Graph
Schedule a Smart Alert
Design Digital Skills
Configure Digital Forms
Configure Digital Views
Train the Assistant
Use Traits
Use Patterns
Manage Context Switching
Deploy the Assistant
Use Bot Functions
Use Content Variables
Use Global Variables
Use Web SDK
Build a Banking Assistant
Design Conversation Skills
Create a Sample Banking Assistant
Create a Transfer Funds Task
Create a Update Balance Task
Create a Knowledge Graph
Set Up a Smart Alert
Design Digital Skills
Configure Digital Forms
Configure Digital Views
Add Data to Data Tables
Update Data in Data Tables
Add Data from Digital Forms
Train the Assistant
Composite Entities
Use Traits
Use Patterns for Intents & Entities
Manage Context Switching
Deploy the Assistant
Configure an Agent Transfer
Use Assistant Functions
Use Content Variables
Use Global Variables
Intent Scoping using Group Node
Analyze the Assistant
Create a Custom Dashboard
Use Custom Meta Tags in Filters
Migrate External Bots
Google Dialogflow Bot
APIs & SDKs
API Reference
API Introduction
Rate Limits
API List
koreUtil Libraries
SDK Reference
SDK Introduction
Web SDK
How the Web SDK Works
SDK Security
SDK Registration
Web Socket Connect and RTM
Tutorials
Widget SDK Tutorial
Web SDK Tutorial
BotKit SDK
BotKit SDK Deployment Guide
Installing the BotKit SDK
Using the BotKit SDK
SDK Events
SDK Functions
Tutorials
BotKit - Blue Prism
BotKit - Flight Search Sample VA
BotKit - Agent Transfer
  1. Home
  2. Docs
  3. Virtual Assistants
  4. Channel Enablement
  5. Adding WebHook as a channel

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 sending to the Kore.ai XO Platform using the Request API.

The Webhook Channel will continue to be available under the ‘Available Channels’ list, and you can choose to create additional instances. Each Webhook channel instances is presented as an independent channel to define messages, prompts, filters, etc., across the application.

Webhook Versions

The platform supports two versions of the Webhook channel i.e., V1.0 and V2.0.

Note: V2.0 is the recommended version as it provides a scalable request and response format.

Here are the key differences:

Feature Webhook V1.0
Webhook V2.0
Events Not supported Supports ‘on connect’ event
Poll Mechanism Not supported Supported in Synchronous Mode
File Upload in Chunks Not supported Supported

Integration Mode

The platform supports Synchronous and Asynchronous modes of integrations for the Webhook channel. Here are the key differences:

  • Synchronous Mode: The bot responses are directly delivered as a response to the incoming requests. The bot will execute the flow, identify the response or responses to be delivered, and provide them as the response to the incoming request. Some platform functionalities like Alert Tasks, Agent Transfer, and Proactive Session Closure messages are not supported in the Synchronous mode. You may consider using the onAlert event through BotKit, Learn more.
    Note: Synchronous Webhook channel requests timeout after 15 seconds. We recommend using the Asynchronous Webhook Channel if you expect the requests to take beyond 15 seconds.
  • Asynchronous Mode: Asynchronous mode is useful if you want to deliver the bot responses to a URL other than the incoming request’s URL. You have to configure the POST_URL of your external system to enable the Async mode. The bot responses are asynchronously delivered to this POST_URL. Do note the that Kore.ai XO Platform does not provide the service to host the POST URL. You need to host a custom service or use a third-party service for this.

Step 1: Associate an App

To associate an App, follow the below steps:

  1. In the XO Platform, select the assistant to which you want to add the channel.
  2. Go to Deploy > Channels > Webhook.
  3. Go to the Configurations tab of this page and associate this channel with an app.
  4. Enter a Name for the channel.
    1. Select one of these scopes for the app:
      • Allow anonymous users to chat with the assistant: enables anonymous users to interact with the assistant.
      • Auto register new users on Kore.ai XO Platform: Select to control the auto-user registration in Kore.ai if the user assertion is unknown.
    2. In the JWT Signing Algorithms Used For Client App Authentication drop-down list, select one of the following security algorithms:
      • RS256/RS512: Select to enable the Public Key. The Private key, used for encryption, is provided by the user, and the Public key, used for decryption, is provided by the Platform. Both the keys have to be used for generating the token. The Public Key is used by the XO Platform to authenticate the client application.
      • HS256/HS512: Select to generate a Secret Key and a Client ID. The Client ID is required for app initialization, and the Secret Key is used by the XO Platform to authenticate the client application
    3. Click Create. The app is created, and Client ID and Client Secret are generated. Copy the Client ID and Client Secret details
  5. If you want to use the JSON Web Encryption (JWE) standard, you can view the Public Key by clicking the link provided below the Client Secret field.
  6. The Webhook channel supports both synchronous and asynchronous modes. Depending on your business needs, you can enable one of these modes in the Configurations tab.
  7. (Only for Webhook v2.0) In the Synchronous mode, by default, the Enable the Polling for Webhook v2 option is selected.
  8. Deselect the Enable the Polling in Webhook V2 option to retrieve the complete response, all at once, without the need for polling.
    Note: This option is available only in Webhook v2.0. Learn more.
  9. Select Yes to Enable Channel.
  10. Save the configuration. The Webhook URL in this channel instance is created dynamically.

Step 2: Select the Integration Mode

Use the Webhook URL to establish integration with external communication systems. This URL is available only after enabling the channel.

Step 3: Deploy the Client SDK (Optional)

You may skip this step if you already have a messaging application to integrate with the Webhook channel. Optionally, you can use the Kore.ai Platform’s Web/Mobile SDK libraries to integrate with the Webhook channel.  Use V2 of the Webhook APIs with synchronous mode for integrating with the client libraries. You can select the API version by going to the Instructions tab of the Webhook channel and scrolling down to Step 4.

After completing these steps, a success message appears on the screen, and a channel request is sent to your Administrator for approval.

  • The channel will be enabled for the end users only after the channel configurations are published. The publish request must be auto-approved or approved by the account admin.
  • Webhook channel instances are included in the bot export copy, and are imported when the definition is imported into another bot. The channel instances are imported as placeholders, and you need to associate them with a valid app from the target VA.

Step 4: Review Payload Formats

To select the API Version for your integration, go to the Instructions tab of the Webhook channel you are working with. You can use the following code snippets of the payload formats to verify the integration. The Webhook API V2 is the latest version and includes a more standardized request and response payload.

Webhook Endpoints

The structure of the Webhook URL of the first instance varies from any additional instances enabled for the bot.

  • In case you have either – only one webhook channel. Or for the first webhook channel in case you have multiple webhook channels configured:
    POST  {{host_url}}/chatbot/hooks/{{bot id}}
  • in case of multi-webhook configuration for the second instance onwards In case you have multiple webhook channels configured, this applies to the second instance onwards:
    POST  {{host_url}}/chatbot/hooks/{{bot id}}/hookInstance/{{webHookId}}  (This is auto-generated)
Query Parameters
Parameter Description
host_url Your Kore.ai 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.

Webhook V1.0

Webhook version 1.0 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

Scenario Synchronous Mode
Asynchronous Mode
Single Response VA responses are sent as a response to the incoming request. VA response is sent to the Post_URL configured as part of the channel configurations.
Multiple consecutive response nodes VA responses are sent as an array to the incoming request. Each of the bot response is sent to the Post_URL configured as part of the channel configurations
Multiple response nodes with service / script / webhook nodes in between The platform completes the service / script / webhook execution and sends the bot responses as an array to the incoming request. Each of the bot response is sent to the Post_URL after processing the relevant service / script / webhook nodes.

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

Parameter Name Description
Data Type
Required/Optional Possible Values
session
Details of how the conversation session should be handled. Objects. Optional N/A
new
Parameter to define whether to start a new conversion or continue with the existing. Boolean Optional
  • true
  • false
message
Includes the contents of the incoming request to the bot. Object Required N/A
text
The message text to be sent to the bot. String Required N/A
attachments
The list of attachments to be passed to the bot. Array of Objects Optional
{"url":"https://- - "}
from
Details of the request origin. It usually includes user information. Object Required N/A
id
The unique identity of the user interacting with the bot. String Required Usually a random string, alphanumeric number, email id etc.,
userInfo
The user profile information. Object Optional N/A
firstName
The first name of the user. String Optional N/A
lastName
The last name of the user. String Optional N/A
email
The email address of the user. String Optional N/A
userLevelTags
Array of user level meta tags to be added to the current user. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
sessionLevelTags
Array of session level meta tags to be added to the current conversion session. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
messageLevelTags
Array of message level tags to be added to the current message. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
mergeIdentity
To merge the current conversation with any other conversation in progress. String Optional
    • true
    • false

</ul

preferredChannelForResponse
To request the platform to provide a response for a different channel. By default, the platform provides the Webhook channel (instance) related responses. String Optional Any valid channel name.
customData
To send additional custom data from the Webhook channel by including it in the request payload. Object Optional N/A

Sample Request Payload Reference

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

curl -X POST 'https://bots.kore.ai/chatbot/hooks/st-xxxxxxxx-1dbc-xxx-aa8f-1fxxx6626ea' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-xxxxT19tsM-hkU3gU7a6lU' \
--header 'Content-Type: application/json' \
--data '{
    "session": {
        "new": false
    },
    "message": {
        "text": "asdf",
        "attachments": [
            {
                "fileId": "6511643xxxxxxx19b79",
                "fileType": "txt",
                "fileName": "IVR Doc"
            }
        ]
    },
    "from": {
        "id": "xxxx12xxx6",
        "userInfo": {
            "firstName": "",
            "lastName": "",
            "email": ""
        }
    }
}'

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 additional conversation management capabilities.

Interaction Flow

Scenario Synchronous Mode
Asynchronous Mode
Single Response VA response is sent as a response to the incoming request. VA response is sent to the Post_URL configured as part of the channel configurations.
Multiple consecutive response nodes VA responses are sent as an array to the incoming request. Each of the bot response is sent to the Post_URL configured as part of the channel configurations
Multiple response nodes with service / script / webhook nodes in between  

  • The consecutive messages are delivered to the request along with a ‘pollid’.
  • The platform initiates the execution of service / script / webhook nodes.
  • The client should poll the platform using the ‘pollid’ at short intervals.
  • The platform responds to the poll request with the status of the execution. If the execution is complete, then the response will include the next set of consecutive messages.
Each of the VA response is sent to the Post_URL after processing the relevant service / script / webhook nodes.

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 the request the 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 the webhook payload, and both userIdentity and from are the 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.

Parameter Name Description
Data Type
Required/Optional Possible Values
session
Details of how the conversation session should be handled. Objects. Optional N/A
new
Parameter to define whether to start a new conversion or continue with the existing. Boolean Optional
  • true
  • false
message
Includes the contents of the incoming request to the bot. Object Required N/A
type
The type of message sent to the platform. String Required
  • text” – If you want to send a plain text message.
  • template” or “formData” – If you want to send a JavaScript template message or form data.
    Note: Ensure that you send only a JSON object.
  • event” – If you want to trigger the “ON_CONNECT” and “SESSION_CLOSURE” events.
val
The value of the sent message. String or Object Required
  • If the type = “text” then the val will be String.
  • If the type = “template” or “formData” then the val will be Object.
  • If you want to trigger the on-connect event, then type = “event” and the val must be “ON_CONNECT.
  • If you want to close the active session, then type = “event” and the val must be “SESSION_CLOSURE.”
attachments
The list of attachments to be passed to the VA.

Note: If attachment is used, set type as text and the val parameter cannot be blank and it has to contain some user utterance.

Array of Objects Optional
{"url":"https://- - "},
{ "fileName": "Kore_ai_Logo.png", "fileType":"image", "fileId": "6163e17bf60e0xxxxxxxx" }
from
Details of the request origin. It usually includes user information. Object Required N/A
id
The unique identity of the user interacting with the VA. String Required Usually a random string, alphanumeric number, email id etc.,
InteractiveLanguage
The interaction language of the virtual assistant. String Optional Any language that is configured for the VA.
For the list of Supported Bot Languages, read Getting Started with Multilingual Virtual Assistant article.
userInfo
The user profile information. Object Optional N/A
firstName
The first name of the user. String Optional N/A
lastName
The last name of the user. String Optional N/A
email
The email address of the user. String Optional N/A
metaTags
Refers to the meta tags to be added. String Optional N/A
userLevelTags
Array of user level meta tags to be added to the current user. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
sessionLevelTags
Array of session level meta tags to be added to the current conversion session. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
messageLevelTags
Array of message level tags to be added to the current message. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
mergeIdentity
To merge the current conversation with any other conversation in progress. String Optional
    • true
    • false

</ul

preferredChannelForResponse
To request the platform to provide a response for a different channel. By default, the platform provides the Webhook channel (instance) related responses. String Optional Any valid channel name.
customData
To send additional custom data from the Webhook channel by including it in the request payload. Object Optional N/A

Sample Request

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

curl -X POST 'https://bots.kore.ai/chatbot/v2/webhook/st-e4xxxxa3-1dbc-xxxx-aa8f-1f2xxx626ea' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-Unwx5eM7qT19tsM-hkU3gU7a6lU' \
--header 'Content-Type: application/json' \
--data '{
    "session": {
        "new": false
    },
    "message": {
        "type": "text",
        "val": "asdg",
        "attachments": [
            {
                "fileId": "65116439cd838811d9819b79",
                "fileType": "txt",
                "fileName": "IVR Doc"
            }
        ]
    },
    "from": {
        "id": "New1234",
        "userInfo": {
            "firstName": "",
            "lastName": "",
            "email": ""
        }
    },
    "metaTags": {
        "userLevelTags": [
            {
                "name": "",
                "value": ""
            }
        ],
        "sessionLevelTags": [
            {
                "name": "",
                "value": ""
            }
        ],
        "messageLevelTags": [
            {
                "name": "",
                "value": ""
            }
        ]
    },
    "mergeIdentity": true,
    "preferredChannelForResponse": "rtm",
    "customData": {
        "customText": "This is generated by customData"
    }
}'

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:

curl -x POST 'https://bots.kore.ai/chatbot/v2/webhook/st-e4xxxa3-1dbc-xxxx-aa8f-1f225xxxx6ea' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-Unwx5eM7qT19tsM-hkU3gU7a6lU' \
--header 'Content-Type: application/json' \
--data '{
    "session": {
        "new": true
    },
    "message": {
        "type": "event",
        "val": "ON_CONNECT"
    },
    "from": {
        "id": "Kore9",
        "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.
  • 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.
  • endOfTask – indicates whether the task is completed or not in the asynchronous mode. It gets added to the response after executing a dialog or fallback task. Possible values are true or false.
  • endOfMessage – indicates the last message of a session and is added in the asynchronous mode. It is added whenever a Smalltalk, Standard Response, or SessionClosure Event message is triggered, or after the execution of the entity node in the flow.
  • partialMessage – indicates that the message node is executed within the flow in the asynchronous mode.
  • createdOn – indicates the response is from a regular dialog node in a synchronous mode.

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 configured VA languages.

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

Sample Request

curl -X POST 'https://bots.kore.ai/chatbot/v2/webhook/st-a77a38cd-xxxx-xxxx-81c6-227xxxx8d48' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-Unwx5eM7qT19tsM-hkU3gU7a6lU' \
--header 'Content-Type: application/json' \
--data '{
    "session": {
        "new": false
    },
    "message": {
        "type": "text",
        "val": "hola"
    },
    "from": {
        "id": "Kore987"
    },
    "to": {
        "id": "st-9ed05a51-3c93-xxxx-xxx-c41xxxx3b0e1"
    },
    "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

curl -X POST 'https://bots.kore.ai/chatbot/v2/webhook/st-xxx5a51-xxxx-56bb-af81-c41ff9b3b0e1' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-Unwx5eM7qT19tsM-hkU3gU7a6lU' \
--header 'Content-Type: application/json' \
--data '{
    "session": {
        "new": false
    },
    "message": {
        "type": "event",
        "val": "SESSION_CLOSURE"
    },
    "from": {
        "id": "xxx1234xxx"
    },
    "to": {
        "id": "st-9ed05a51-3c93-xxxx-xxx-c41xxxx3b0e1"
    }
}'

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 a 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.

Sample request with messages and ‘pollid’

curl -X GET 'https://bots.kore.ai/chatbot/v2/webhook/st-8e031d0a-xxxx-xxx-bf4c-b8axxxf0685/poll/7c1a981xxxxxxxxd9dbcb9345af39b2d' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-Unwx5eM7qT19tsM-hkU3gU7a6lU'

Sample 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/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:

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

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

Response 1: When an active session does not exist

{
    "data": [
        {
            "type": "event",
            "val": "SESSION_CLOSURE",
            "eventType": "SESSION_CLOSURE_IGNORED",
             "description": "Active session doesn't exist"
         ], 
        "_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

Type 1 : Upload File with URL

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

curl -X POST 
'https://bots.kore.ai/chatbot/v2/webhook/st-4xxx3f-xxx-5657-xxx-a8cxxxxa086/hookInstance/ivrInst-c867xx54-e4b6-xxx-9471-dxxxx37305c' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NixxxxxxxkpXVCJ9.eyJhxxxxxx5ODk0NWYxLTRjMmUtNTc5NC1iMGJkLWUxZjUwYzY3ODVkZiJ9.RQQAw-jKwbKWxwwP1xxxxxxrzuGF9oOqz77aRw' \
--header 'Cookie: filetoken=cc7c5f79-xxxx-xxx-8c6b-a9xxxx26113' \
--data-raw '{
    "message": {
        "type": "text",
        "val": "Some description of the image",
        "attachments": [
            {
                "url": "https://user-images.gxxxrcontent.com/4432322/14xxx568-dbxxx6c9-xxxx-xxx-b104-a6xxx24890.png"
            }
        ]
    },
    "from": {
        "id": "10xxx0601",
        "userInfo": {
            "firstName": "first name",
            "lastName": "last name",
            "email": "example@abc.com",
            "user_data": {}
        }
    }
}'

For parameter descriptions, refer to the request parameters table.

Type 2:  Using fileId obtained from file upload API

You can upload a file using the fileId obtained from file upload API. The following example uses a webhook instance when multiple webhook channels are configured:

curl -X POST
'https://bots.kore.ai/chatbot/v2/webhook/st-4b8ee63f-0bad-xxxx-xxx-a8c4xxxxx086/xxxInstance/ivrInst-c86xxxx54-xxxx-xxxx-9471-dfxxxx37305c' \
--header 'Authorization: Bearer {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "message": {
        "type": "text",
        "val": "User utterance",
        "attachments": [
            {
                "fileName": "My image file",
                "fileType": "image",
                "fileId": "650c3XXXXXXbXXc31"
            }
        ]
    },
    "from": {
        "id": "103XXXXX601",
        "userInfo": {
        "userInfo": {
     		 "firstName": "<first-name(optional)>",
      	 "lastName": "<second-name(optional)>",
      	 "email": "<email@domain.com(optional)>"
             "user_data": {}
        }
    }
}'

For parameter descriptions, refer to the request parameters table.

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: https://{{host}}/api/public/uploadfile 
   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 Request

You can get the Webhook API URL on the WebHook channel Configurations tab. Learn more.
Note: This URL is available only after enabling the channel.

 "session": {
       "new": false
   },
   "message": {
       "val": {
           "formId": "{{formId}}",
           "data": [
               {
                   "componentId": "{{ComponentId}}",
                   "input": "{{user input1}}"
               },
               {
                   "componentId": "{{ComponentId}}",
                   "input": "{{user input2}}"
               },
               {
                   "componentId": "{{ComponentId}}",
                   "input": "Submit"
               }
           ],
           "meta": {}
       },
       "type": "formData"
   },
   "from": {
       "id": "",
       "userInfo": {
           "firstName": "",
           "lastName": "",
           "email": ""
       }
   },
   "to": {
       "id": "",
       "groupInfo": {
           "id": "",
           "name": ""
       }
   },
Others if any
}

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

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
},

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 sending to the Kore.ai XO Platform using the Request API.

The Webhook Channel will continue to be available under the ‘Available Channels’ list, and you can choose to create additional instances. Each Webhook channel instances is presented as an independent channel to define messages, prompts, filters, etc., across the application.

Webhook Versions

The platform supports two versions of the Webhook channel i.e., V1.0 and V2.0.

Note: V2.0 is the recommended version as it provides a scalable request and response format.

Here are the key differences:

Feature Webhook V1.0
Webhook V2.0
Events Not supported Supports ‘on connect’ event
Poll Mechanism Not supported Supported in Synchronous Mode
File Upload in Chunks Not supported Supported

Integration Mode

The platform supports Synchronous and Asynchronous modes of integrations for the Webhook channel. Here are the key differences:

  • Synchronous Mode: The bot responses are directly delivered as a response to the incoming requests. The bot will execute the flow, identify the response or responses to be delivered, and provide them as the response to the incoming request. Some platform functionalities like Alert Tasks, Agent Transfer, and Proactive Session Closure messages are not supported in the Synchronous mode. You may consider using the onAlert event through BotKit, Learn more.
    Note: Synchronous Webhook channel requests timeout after 15 seconds. We recommend using the Asynchronous Webhook Channel if you expect the requests to take beyond 15 seconds.
  • Asynchronous Mode: Asynchronous mode is useful if you want to deliver the bot responses to a URL other than the incoming request’s URL. You have to configure the POST_URL of your external system to enable the Async mode. The bot responses are asynchronously delivered to this POST_URL. Do note the that Kore.ai XO Platform does not provide the service to host the POST URL. You need to host a custom service or use a third-party service for this.

Step 1: Associate an App

To associate an App, follow the below steps:

  1. In the XO Platform, select the assistant to which you want to add the channel.
  2. Go to Deploy > Channels > Webhook.
  3. Go to the Configurations tab of this page and associate this channel with an app.
  4. Enter a Name for the channel.
    1. Select one of these scopes for the app:
      • Allow anonymous users to chat with the assistant: enables anonymous users to interact with the assistant.
      • Auto register new users on Kore.ai XO Platform: Select to control the auto-user registration in Kore.ai if the user assertion is unknown.
    2. In the JWT Signing Algorithms Used For Client App Authentication drop-down list, select one of the following security algorithms:
      • RS256/RS512: Select to enable the Public Key. The Private key, used for encryption, is provided by the user, and the Public key, used for decryption, is provided by the Platform. Both the keys have to be used for generating the token. The Public Key is used by the XO Platform to authenticate the client application.
      • HS256/HS512: Select to generate a Secret Key and a Client ID. The Client ID is required for app initialization, and the Secret Key is used by the XO Platform to authenticate the client application
    3. Click Create. The app is created, and Client ID and Client Secret are generated. Copy the Client ID and Client Secret details
  5. If you want to use the JSON Web Encryption (JWE) standard, you can view the Public Key by clicking the link provided below the Client Secret field.
  6. The Webhook channel supports both synchronous and asynchronous modes. Depending on your business needs, you can enable one of these modes in the Configurations tab.
  7. (Only for Webhook v2.0) In the Synchronous mode, by default, the Enable the Polling for Webhook v2 option is selected.
  8. Deselect the Enable the Polling in Webhook V2 option to retrieve the complete response, all at once, without the need for polling.
    Note: This option is available only in Webhook v2.0. Learn more.
  9. Select Yes to Enable Channel.
  10. Save the configuration. The Webhook URL in this channel instance is created dynamically.

Step 2: Select the Integration Mode

Use the Webhook URL to establish integration with external communication systems. This URL is available only after enabling the channel.

Step 3: Deploy the Client SDK (Optional)

You may skip this step if you already have a messaging application to integrate with the Webhook channel. Optionally, you can use the Kore.ai Platform’s Web/Mobile SDK libraries to integrate with the Webhook channel.  Use V2 of the Webhook APIs with synchronous mode for integrating with the client libraries. You can select the API version by going to the Instructions tab of the Webhook channel and scrolling down to Step 4.

After completing these steps, a success message appears on the screen, and a channel request is sent to your Administrator for approval.

  • The channel will be enabled for the end users only after the channel configurations are published. The publish request must be auto-approved or approved by the account admin.
  • Webhook channel instances are included in the bot export copy, and are imported when the definition is imported into another bot. The channel instances are imported as placeholders, and you need to associate them with a valid app from the target VA.

Step 4: Review Payload Formats

To select the API Version for your integration, go to the Instructions tab of the Webhook channel you are working with. You can use the following code snippets of the payload formats to verify the integration. The Webhook API V2 is the latest version and includes a more standardized request and response payload.

Webhook Endpoints

The structure of the Webhook URL of the first instance varies from any additional instances enabled for the bot.

  • In case you have either – only one webhook channel. Or for the first webhook channel in case you have multiple webhook channels configured:
    POST  {{host_url}}/chatbot/hooks/{{bot id}}
  • in case of multi-webhook configuration for the second instance onwards In case you have multiple webhook channels configured, this applies to the second instance onwards:
    POST  {{host_url}}/chatbot/hooks/{{bot id}}/hookInstance/{{webHookId}}  (This is auto-generated)
Query Parameters
Parameter Description
host_url Your Kore.ai 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.

Webhook V1.0

Webhook version 1.0 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

Scenario Synchronous Mode
Asynchronous Mode
Single Response VA responses are sent as a response to the incoming request. VA response is sent to the Post_URL configured as part of the channel configurations.
Multiple consecutive response nodes VA responses are sent as an array to the incoming request. Each of the bot response is sent to the Post_URL configured as part of the channel configurations
Multiple response nodes with service / script / webhook nodes in between The platform completes the service / script / webhook execution and sends the bot responses as an array to the incoming request. Each of the bot response is sent to the Post_URL after processing the relevant service / script / webhook nodes.

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

Parameter Name Description
Data Type
Required/Optional Possible Values
session
Details of how the conversation session should be handled. Objects. Optional N/A
new
Parameter to define whether to start a new conversion or continue with the existing. Boolean Optional
  • true
  • false
message
Includes the contents of the incoming request to the bot. Object Required N/A
text
The message text to be sent to the bot. String Required N/A
attachments
The list of attachments to be passed to the bot. Array of Objects Optional
{"url":"https://- - "}
from
Details of the request origin. It usually includes user information. Object Required N/A
id
The unique identity of the user interacting with the bot. String Required Usually a random string, alphanumeric number, email id etc.,
userInfo
The user profile information. Object Optional N/A
firstName
The first name of the user. String Optional N/A
lastName
The last name of the user. String Optional N/A
email
The email address of the user. String Optional N/A
userLevelTags
Array of user level meta tags to be added to the current user. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
sessionLevelTags
Array of session level meta tags to be added to the current conversion session. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
messageLevelTags
Array of message level tags to be added to the current message. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
mergeIdentity
To merge the current conversation with any other conversation in progress. String Optional
    • true
    • false

</ul

preferredChannelForResponse
To request the platform to provide a response for a different channel. By default, the platform provides the Webhook channel (instance) related responses. String Optional Any valid channel name.
customData
To send additional custom data from the Webhook channel by including it in the request payload. Object Optional N/A

Sample Request Payload Reference

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

curl -X POST 'https://bots.kore.ai/chatbot/hooks/st-xxxxxxxx-1dbc-xxx-aa8f-1fxxx6626ea' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-xxxxT19tsM-hkU3gU7a6lU' \
--header 'Content-Type: application/json' \
--data '{
    "session": {
        "new": false
    },
    "message": {
        "text": "asdf",
        "attachments": [
            {
                "fileId": "6511643xxxxxxx19b79",
                "fileType": "txt",
                "fileName": "IVR Doc"
            }
        ]
    },
    "from": {
        "id": "xxxx12xxx6",
        "userInfo": {
            "firstName": "",
            "lastName": "",
            "email": ""
        }
    }
}'

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 additional conversation management capabilities.

Interaction Flow

Scenario Synchronous Mode
Asynchronous Mode
Single Response VA response is sent as a response to the incoming request. VA response is sent to the Post_URL configured as part of the channel configurations.
Multiple consecutive response nodes VA responses are sent as an array to the incoming request. Each of the bot response is sent to the Post_URL configured as part of the channel configurations
Multiple response nodes with service / script / webhook nodes in between  

  • The consecutive messages are delivered to the request along with a ‘pollid’.
  • The platform initiates the execution of service / script / webhook nodes.
  • The client should poll the platform using the ‘pollid’ at short intervals.
  • The platform responds to the poll request with the status of the execution. If the execution is complete, then the response will include the next set of consecutive messages.
Each of the VA response is sent to the Post_URL after processing the relevant service / script / webhook nodes.

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 the request the 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 the webhook payload, and both userIdentity and from are the 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.

Parameter Name Description
Data Type
Required/Optional Possible Values
session
Details of how the conversation session should be handled. Objects. Optional N/A
new
Parameter to define whether to start a new conversion or continue with the existing. Boolean Optional
  • true
  • false
message
Includes the contents of the incoming request to the bot. Object Required N/A
type
The type of message sent to the platform. String Required
  • text” – If you want to send a plain text message.
  • template” or “formData” – If you want to send a JavaScript template message or form data.
    Note: Ensure that you send only a JSON object.
  • event” – If you want to trigger the “ON_CONNECT” and “SESSION_CLOSURE” events.
val
The value of the sent message. String or Object Required
  • If the type = “text” then the val will be String.
  • If the type = “template” or “formData” then the val will be Object.
  • If you want to trigger the on-connect event, then type = “event” and the val must be “ON_CONNECT.
  • If you want to close the active session, then type = “event” and the val must be “SESSION_CLOSURE.”
attachments
The list of attachments to be passed to the VA.

Note: If attachment is used, set type as text and the val parameter cannot be blank and it has to contain some user utterance.

Array of Objects Optional
{"url":"https://- - "},
{ "fileName": "Kore_ai_Logo.png", "fileType":"image", "fileId": "6163e17bf60e0xxxxxxxx" }
from
Details of the request origin. It usually includes user information. Object Required N/A
id
The unique identity of the user interacting with the VA. String Required Usually a random string, alphanumeric number, email id etc.,
InteractiveLanguage
The interaction language of the virtual assistant. String Optional Any language that is configured for the VA.
For the list of Supported Bot Languages, read Getting Started with Multilingual Virtual Assistant article.
userInfo
The user profile information. Object Optional N/A
firstName
The first name of the user. String Optional N/A
lastName
The last name of the user. String Optional N/A
email
The email address of the user. String Optional N/A
metaTags
Refers to the meta tags to be added. String Optional N/A
userLevelTags
Array of user level meta tags to be added to the current user. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
sessionLevelTags
Array of session level meta tags to be added to the current conversion session. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
messageLevelTags
Array of message level tags to be added to the current message. Array of Objects Optional Every tag to be added using “name” and “value’ keys.
mergeIdentity
To merge the current conversation with any other conversation in progress. String Optional
    • true
    • false

</ul

preferredChannelForResponse
To request the platform to provide a response for a different channel. By default, the platform provides the Webhook channel (instance) related responses. String Optional Any valid channel name.
customData
To send additional custom data from the Webhook channel by including it in the request payload. Object Optional N/A

Sample Request

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

curl -X POST 'https://bots.kore.ai/chatbot/v2/webhook/st-e4xxxxa3-1dbc-xxxx-aa8f-1f2xxx626ea' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-Unwx5eM7qT19tsM-hkU3gU7a6lU' \
--header 'Content-Type: application/json' \
--data '{
    "session": {
        "new": false
    },
    "message": {
        "type": "text",
        "val": "asdg",
        "attachments": [
            {
                "fileId": "65116439cd838811d9819b79",
                "fileType": "txt",
                "fileName": "IVR Doc"
            }
        ]
    },
    "from": {
        "id": "New1234",
        "userInfo": {
            "firstName": "",
            "lastName": "",
            "email": ""
        }
    },
    "metaTags": {
        "userLevelTags": [
            {
                "name": "",
                "value": ""
            }
        ],
        "sessionLevelTags": [
            {
                "name": "",
                "value": ""
            }
        ],
        "messageLevelTags": [
            {
                "name": "",
                "value": ""
            }
        ]
    },
    "mergeIdentity": true,
    "preferredChannelForResponse": "rtm",
    "customData": {
        "customText": "This is generated by customData"
    }
}'

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:

curl -x POST 'https://bots.kore.ai/chatbot/v2/webhook/st-e4xxxa3-1dbc-xxxx-aa8f-1f225xxxx6ea' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-Unwx5eM7qT19tsM-hkU3gU7a6lU' \
--header 'Content-Type: application/json' \
--data '{
    "session": {
        "new": true
    },
    "message": {
        "type": "event",
        "val": "ON_CONNECT"
    },
    "from": {
        "id": "Kore9",
        "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.
  • 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.
  • endOfTask – indicates whether the task is completed or not in the asynchronous mode. It gets added to the response after executing a dialog or fallback task. Possible values are true or false.
  • endOfMessage – indicates the last message of a session and is added in the asynchronous mode. It is added whenever a Smalltalk, Standard Response, or SessionClosure Event message is triggered, or after the execution of the entity node in the flow.
  • partialMessage – indicates that the message node is executed within the flow in the asynchronous mode.
  • createdOn – indicates the response is from a regular dialog node in a synchronous mode.

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 configured VA languages.

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

Sample Request

curl -X POST 'https://bots.kore.ai/chatbot/v2/webhook/st-a77a38cd-xxxx-xxxx-81c6-227xxxx8d48' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-Unwx5eM7qT19tsM-hkU3gU7a6lU' \
--header 'Content-Type: application/json' \
--data '{
    "session": {
        "new": false
    },
    "message": {
        "type": "text",
        "val": "hola"
    },
    "from": {
        "id": "Kore987"
    },
    "to": {
        "id": "st-9ed05a51-3c93-xxxx-xxx-c41xxxx3b0e1"
    },
    "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

curl -X POST 'https://bots.kore.ai/chatbot/v2/webhook/st-xxx5a51-xxxx-56bb-af81-c41ff9b3b0e1' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-Unwx5eM7qT19tsM-hkU3gU7a6lU' \
--header 'Content-Type: application/json' \
--data '{
    "session": {
        "new": false
    },
    "message": {
        "type": "event",
        "val": "SESSION_CLOSURE"
    },
    "from": {
        "id": "xxx1234xxx"
    },
    "to": {
        "id": "st-9ed05a51-3c93-xxxx-xxx-c41xxxx3b0e1"
    }
}'

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 a 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.

Sample request with messages and ‘pollid’

curl -X GET 'https://bots.kore.ai/chatbot/v2/webhook/st-8e031d0a-xxxx-xxx-bf4c-b8axxxf0685/poll/7c1a981xxxxxxxxd9dbcb9345af39b2d' \
--header 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInxxxxxxxxxxxxxxxxxxxxxxxxQ3LTcwYTlmOTg3Yjg0NCJ9._pztYVnP2UfJNu4-Unwx5eM7qT19tsM-hkU3gU7a6lU'

Sample 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/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:

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

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

Response 1: When an active session does not exist

{
    "data": [
        {
            "type": "event",
            "val": "SESSION_CLOSURE",
            "eventType": "SESSION_CLOSURE_IGNORED",
             "description": "Active session doesn't exist"
         ], 
        "_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

Type 1 : Upload File with URL

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

curl -X POST 
'https://bots.kore.ai/chatbot/v2/webhook/st-4xxx3f-xxx-5657-xxx-a8cxxxxa086/hookInstance/ivrInst-c867xx54-e4b6-xxx-9471-dxxxx37305c' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NixxxxxxxkpXVCJ9.eyJhxxxxxx5ODk0NWYxLTRjMmUtNTc5NC1iMGJkLWUxZjUwYzY3ODVkZiJ9.RQQAw-jKwbKWxwwP1xxxxxxrzuGF9oOqz77aRw' \
--header 'Cookie: filetoken=cc7c5f79-xxxx-xxx-8c6b-a9xxxx26113' \
--data-raw '{
    "message": {
        "type": "text",
        "val": "Some description of the image",
        "attachments": [
            {
                "url": "https://user-images.gxxxrcontent.com/4432322/14xxx568-dbxxx6c9-xxxx-xxx-b104-a6xxx24890.png"
            }
        ]
    },
    "from": {
        "id": "10xxx0601",
        "userInfo": {
            "firstName": "first name",
            "lastName": "last name",
            "email": "example@abc.com",
            "user_data": {}
        }
    }
}'

For parameter descriptions, refer to the request parameters table.

Type 2:  Using fileId obtained from file upload API

You can upload a file using the fileId obtained from file upload API. The following example uses a webhook instance when multiple webhook channels are configured:

curl -X POST
'https://bots.kore.ai/chatbot/v2/webhook/st-4b8ee63f-0bad-xxxx-xxx-a8c4xxxxx086/xxxInstance/ivrInst-c86xxxx54-xxxx-xxxx-9471-dfxxxx37305c' \
--header 'Authorization: Bearer {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "message": {
        "type": "text",
        "val": "User utterance",
        "attachments": [
            {
                "fileName": "My image file",
                "fileType": "image",
                "fileId": "650c3XXXXXXbXXc31"
            }
        ]
    },
    "from": {
        "id": "103XXXXX601",
        "userInfo": {
        "userInfo": {
     		 "firstName": "<first-name(optional)>",
      	 "lastName": "<second-name(optional)>",
      	 "email": "<email@domain.com(optional)>"
             "user_data": {}
        }
    }
}'

For parameter descriptions, refer to the request parameters table.

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: https://{{host}}/api/public/uploadfile 
   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 Request

You can get the Webhook API URL on the WebHook channel Configurations tab. Learn more.
Note: This URL is available only after enabling the channel.

 "session": {
       "new": false
   },
   "message": {
       "val": {
           "formId": "{{formId}}",
           "data": [
               {
                   "componentId": "{{ComponentId}}",
                   "input": "{{user input1}}"
               },
               {
                   "componentId": "{{ComponentId}}",
                   "input": "{{user input2}}"
               },
               {
                   "componentId": "{{ComponentId}}",
                   "input": "Submit"
               }
           ],
           "meta": {}
       },
       "type": "formData"
   },
   "from": {
       "id": "",
       "userInfo": {
           "firstName": "",
           "lastName": "",
           "email": ""
       }
   },
   "to": {
       "id": "",
       "groupInfo": {
           "id": "",
           "name": ""
       }
   },
Others if any
}

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

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
},
Menu