Adding WebHook as a channel

Documentation Index

Fetch the complete documentation index at: https://koreai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​

Webhook Versions

​

Integration Mode

• Synchronous Mode: The app responses are directly delivered as a response to the incoming requests. The app 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.

• Asynchronous Mode: Asynchronous mode is useful if you want to deliver the app 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 app responses are asynchronously delivered to this POST_URL. Do note the that 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

1. In the Platform, select the assistant to which you want to add the channel.
2. Go to Channels & Flows > Channels > Digital > All > 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:
      1. Allow anonymous users to chat with the assistant: enables anonymous users to interact with the assistant.
      2. Auto register new users on 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:
      1. 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 Platform to authenticate the client application.
      2. 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 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.
   This option is available only in Webhook v2.0. Learn more.
9. In the ASynchronous mode, enable Proactive Notifications to send relevant updates to the users without requiring them to initiate interaction with the app first.
10. Select Yes to Enable Channel.
11. Save the configuration. The Webhook URL in this channel instance is created dynamically.

​

Step 2: Select the Integration Mode

​

Step 3: Deploy the Client SDK (Optional)

• 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 app export copy, and are imported when the definition is imported into another app. The channel instances are imported as placeholders, and you need to associate them with a valid app from the target AI Agent.

​

Step 4: Review Payload Formats

​

Webhook Endpoints

• 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

​

Webhook V1.0

​

Interaction Flow

​

Authorization

Authorization: bearer {{JWT}}

​

Response content type

application/json

​

Request Parameters

​

Sample Response for Asynchronous Mode

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

• The text field can contain a string, object or an array of strings or objects.
• Separate messages are sent for every app 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

​

Interaction Flow

​

Authorization

​

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

​

Option 2: Upload Files to Platform

Request
URL: https://{{host}}/api/public/uploadfile
   Method: POST
   Body:
     {
        File:,
        fileContext :,
        fileExtension : ,
        Filename:
   }
Response
          Response: {
                        fileId:
                        hash:
  }

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

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

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

​

Handle Digital Forms

​

Sample Request

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

{
  "_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)
}

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

​

Error Scenarios in Webhook v2 Responses

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

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

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

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