1. Home
  2. Kore.ai Conversational Platform
  3. Bot Builder Tool
  4. Channel Enablement
  5. Adding WebHook as a channel

Adding WebHook as a channel

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

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

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

Configuring Webhook as a channel:
  1. In the Bots section of the Bot Builder, click the Bot to which you want to add the Webhook channel.
  2. On the Channels tab, click the Webhook icon. The Webhook page gets displayed.
  3. Navigate to Configurations tab of this page and associate this channel with an app. You may select any of the existing Apps available in your Kore.ai account or create a new app.
  4. Enter a name for the app and click Create. The app gets created and Client ID and Client Secret is generated. Copy the Client ID and Client Secret details.
  5. Webhook channel supports both synchronous and asynchronous modes and depending on your business needs, you can enable one of these modes in the Configurations tab.
    • Synchronous mode delivers full response directly to the incoming requests.
    • Asynchronous mode defines the POST_URL of your external system and Access Token to be used for delivering partial or full responses. When hit, the WebHook URL will receive an empty message with 200 status code, the response message will be sent to the POST_URL defined.
  6. From the Webhook URL box, copy the URL that you can use from the external application.
  7. Select Yes to Enable Channel.

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

Note: The channel remains non-functional until the Bots Admin approves it.

WebHook API Reference

Receives plain text messages from external communication systems

POST  {{host_url}}/chatbot/hooks/{{bot id}}

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.

 

Authorization

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

Authorization: bearer {{JWT}}

Generate JWT using the following header and payload

JWT Header

{
  "alg": "HS256",
  "typ": "JWT"
 }

JWT Payload

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

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

Response content type

application/json

Sample Payload Reference

payload : {
           "message":{
             "text" : "Hi",
             "attachments" : [<array of attachment links>]
            },
           "from" :{
             "id": <unique-id-of-sender(mandatory)>
            },
          "to" :{
            "id": <unique-id-of-recipient(mandatory)>
            }
          }

Sample cURL

curl -X POST
{{host}}/chatbot/hooks/{{bot-id}}
 -H 'authorization: bearer {{JWT Token}}'
 -H 'content-type: application/json'
 -d '{ "message": { 
          "text": "hi" }, 
       "from": { 
          "id": "1323465" }, 
       "to" : { 
          "id": "4321" }
     }'

Synchronous Response

{
  "text" : "message"
  }

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

Asynchronous Response

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

 

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

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

{
 "text" : "message",
 "to" : "to_id",
 "from" : "from_id"
 }
Was this article helpful to you? Yes No 12