WebSocket Connect and RTM

Back to Web SDK Overview

Kore.ai SDK libraries use a WebSocket channel to communicate with the Platform. When using the Kore SDKs, you only need to generate and pass a JWT token to the client SDK — the SDK handles the rest.

This page documents the WebSocket initialization flow, RTM events, and error codes for reference and custom client implementations.

---

WebSocket Session Initialization

Prerequisites

• Register the client app and generate a Client ID and Secret Key on the Platform.

Step 1 — Generate a JWT

Generate the JWT on the server using the client app credentials and user identity. Pass it to the client app.

Step 2 — Exchange JWT for an Access Token

Endpoint:

POST https://{{APIHost}}/api/1.1/oAuth/token/jwtgrant

Request body:

{
  "assertion": "{{JWT Token}}",
  "botInfo": {
    "chatBot": "{{Bot Name}}",
    "taskBotId": "st-f74a3430-3b19-55a3-be41-1ab1a35cxxxx"
  }
}

Sample cURL:

curl 'https://{{host}}/api/1.1/oAuth/token/jwtgrant' \
  -H 'content-type: application/json' \
  --data-binary '{"assertion":"{{JWT Token}}","botInfo":{"chatBot":"{{Bot Name}}","taskBotId":"st-f74a3430-3b19-55a3-be41-1ab1a35cxxxx"}}'

Response:

{
  "authorization": {
    "accessToken": "ZdV2OL_UZ_MvHog-rs8k9KJFNWBICvquSc3xxxxxxx_-",
    "token_type": "bearer",
    "expiresDate": "2019-06-28T06:52:23.160Z",
    "issuedDate": "2019-02-28T06:52:23.160Z"
  },
  "userInfo": {
    "userId": "u-4f6c68e0-551a-5dd9-a33a-1af3dc9cxxxx",
    "accountId": "5c66514d09ab3565debxxxxx",
    "orgId": "o-88aad7f1-0d32-5765-93d7-f40c8040xxxx",
    "identity": "cs-5b08ed1e-5fa7-5aaa-9c21-28bf8c90xxxx/[e-mail]",
    "enrollType": "free",
    "managedBy": "5c66514d09ab3565debxxxxa",
    "fName": "",
    "lName": ""
  }
}

Step 3 — Get the WebSocket URL

Endpoint:

POST https://{{host}}/api/1.1/rtm/start

This URL is short-lived and expires in 30 seconds. Connect before it expires.

Request body:

{
  "botInfo": {
    "chatBot": "Twitter",
    "taskBotId": "st-f74a3430-3b19-55a3-be41-1ab1a35cxxxx"
  }
}

Pass the accessToken as a Bearer token in the Authorization header.

Sample cURL:

curl 'https://{{host}}/api/1.1/rtm/start' \
  -H 'content-type: application/json' \
  -H 'Authorization: bearer {{accessToken}}' \
  --data-binary '{"botInfo":{"chatBot":"{{Bot Name}}","taskBotId":"st-f74a3430-3b19-55a3-be41-1ab1a35cxxxx"}}'

Response:

{
  "url": "wss://xxx.yyy.com:443/rtm/bot?sid=GhKrtrEC61g7hAnmvKAVnJIHG0DSxxxx"
}

---

RTM Channel Events

RTM Client Events

Event: /bot.message — Sent when a user posts a message.

{
  "clientMessageId": 1466692440896,
  "message": {
    "body": "Here is the message.",
    "attachments": []
  },
  "resourceid": "/bot.message",
  "botInfo": {
    "chatBot": "CNN",
    "taskBotId": "st-8aaf0939-c34a-5976-8e2e-5c91e685xxxx"
  },
  "id": 1466692440896
}

Pass Custom Data to the Bot

In addition to the message body, you can send custom JSON data to the bot using the customData object. This capability is available for both Web SDK and direct WebSocket integrations. For more information, see How to pass customData to bot from SDK?

Return Custom Data in Bot Responses

Bot responses can also include custom JSON data in addition to the message content. Use the Advanced JavaScript Editor to add custom JSON to text, standard template, or custom template responses. Client applications can consume this data through available Web SDK or WebSocket events and process it separately from the user-visible message.

RTM Server Events

Event: ack — Acknowledgment sent when a client event is received.

{
  "ok": true,
  "replyto": 1466692440896,
  "message": "delivered",
  "type": "ack"
}

Event: bot_response — Sent when a client message is processed.

{
  "type": "bot_response",
  "from": "bot",
  "message": [{ "type": "text", "cInfo": { "body": "Hi." } }],
  "botInfo": { "chatBot": "CNN", "taskBotId": "st-8aaf0939-..." },
  "createdOn": "2016-06-23T14:34:00.025Z",
  "icon": "https://devbots.kxxx.com/api/getMediaStream/..."
}

Event: user_message — Sent to the client when the user sends a message from another simultaneous session.

{
  "botInfo": { "chatBot": "CNN", "taskBotId": "st-8aaf0939-..." },
  "from": "self",
  "message": { "body": "how are you doing", "attachments": [] },
  "id": 1466692871803,
  "type": "user_message"
}

---

Bot Status Events

Event: /bot_active — Triggered when a WebSocket connection is established with the bot.

{
  "type": "bot_active",
  "from": "bot",
  "botInfo": { "chatBot": "John", "taskBotId": "st-2e2663f4-..." },
  "sessionId": "642d2f34f7eb45387a7xxxx",
  "formMetaInfo": { "isSecured": true, "formLinkExpiry": 300, "submitExpiry": 600 },
  "traceId": "4a663e27051cxxxx"
}

Event: /botKitUnreachable — Sent to the WebSDK when BotKit is unreachable. Default message: "Sorry, there was an error in continuing the conversation. Please retry." Developers can customize this message.

{
  "type": "botKitUnreachable",
  "from": "bot",
  "botInfo": { "chatBot": "new bot hangouts", "taskBotId": "st-f3ad01a6-..." },
  "message": "Sorry, there was an error in continuing the conversation. Please retry.",
  "traceId": "c070f2b7de24xxxx",
  "timestamp": 1693394943443
}

---

Form Events

Event: /form_delivered — Triggered when a form is delivered to a user.

Event: /form_submitted — Triggered when a user submits a form.

Event: /form_failure — Triggered when a form fails for any reason.

All form events share the same payload structure:

{
  "type": "form_delivered|form_submitted|form_failure",
  "from": "bot",
  "botInfo": { "chatBot": "John", "taskBotId": "st-2e2663f4-..." },
  "sessionId": "642d2f34f7eb45387a7bxxxx",
  "formMetaInfo": { "isSecured": true, "formLinkExpiry": 300, "submitExpiry": 600 },
  "traceId": "4a663e27051cxxxx"
}

---

Session Events

Event: /session_start — Triggered when a session starts.

Triggers on:

• On-Connect event (open, refresh, or disable chat window).
• A message sent after 15 minutes of inactivity.
• A message sent after the idle timeout configured in Manage Sessions.

Event: /session_end — Triggered when a session ends.

Triggers on:

• On-Connect event (close, refresh, or disable chat window).
• Session timeout after 15 minutes.

Both share the same payload:

{
  "type": "session_start|session_end",
  "from": "bot",
  "botInfo": {
    "chatBot": "jarvis_new_import",
    "taskBotId": "st-496bf3e4-...",
    "hostDomain": "https://localhost",
    "os": "Linux",
    "device": "Other"
  },
  "sessionId": "6426bf7e916562382331xxxx",
  "traceId": "a33d81825f3bxxxx"
}

---

Agent Transfer Events

Event: /agent_session_start — Triggered when chat is handed off to an agent.

Event: /agent_session_end — Triggered when the agent conversation ends.

Both share the same payload:

{
  "type": "agent_session_start|agent_session_end",
  "from": "bot",
  "botInfo": { "chatBot": "John", "taskBotId": "st-2e2663f4-..." },
  "sessionId": "642d2f34f7eb45387a7bxxxx",
  "formMetaInfo": { "isSecured": true, "formLinkExpiry": 300, "submitExpiry": 600 },
  "traceId": "4a663e27051cxxxx"
}

For details, see Agent Transfer Integrations.

---

User Input Event

Event: /waiting_for_user_input — Triggered when the VA waits for user input (from an Entity, Confirmation, or Standard Response node).

{
  "type": "waiting_for_user_input",
  "from": "bot",
  "botInfo": { "chatBot": "John", "taskBotId": "st-2e2663f4-..." },
  "sessionId": "642d2f34f7eb45387a7bxxxx",
  "formMetaInfo": { "isSecured": true, "formLinkExpiry": 300, "submitExpiry": 600 },
  "traceId": "4a663e27051cxxxx"
}

---

Get Conversation History

Endpoint:

GET https://{{host}}/api/botmessages/rtm?botId={{botId}}

Query parameters:

Parameter	Required	Description
botId	Yes	Bot ID from General Settings
skip / offset	No	Number of messages to skip
limit	No	Number of messages to fetch

Pass accessToken as Authorization: bearer <token>.

Sample cURL:

curl 'https://{{host}}/api/botmessages/rtm?botId={{botId}}&limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: bearer {{accessToken}}' \
  -H 'content-type: application/json'

---

WebSocket Error Codes

Code	Reason
1002	Protocol error
1005	User closed the chat window or reconnected
1006	Server restarted
1007	Bot received non-UTF-8 content instead of text
1008	Rate limit exceeded, bot suspended, user blocked, or channel user ID blocked
1009	Payload size exceeds the maximum limit
1011	Unhandled exception while WebSocket connection is active

---