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

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/admin@example.xyz",
    "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

​WebSocket Session Initialization

​Prerequisites

​Step 1 — Generate a JWT

​Step 2 — Exchange JWT for an Access Token

​Step 3 — Get the WebSocket URL

​RTM Channel Events

​RTM Client Events

​RTM Server Events

​Bot Status Events

​Form Events

​Session Events

​Agent Transfer Events

​User Input Event

​Get Conversation History

​WebSocket Error Codes

WebSocket Session Initialization

Prerequisites

Step 1 — Generate a JWT

Step 2 — Exchange JWT for an Access Token

Step 3 — Get the WebSocket URL

RTM Channel Events

RTM Client Events

RTM Server Events

Bot Status Events

Form Events

Session Events

Agent Transfer Events

User Input Event

Get Conversation History

WebSocket Error Codes