BotKit SDK Events - Kore.ai Docs

Back to BotKit SDK Overview The BotKit SDK lets you handle Platform events to customize conversation behavior. Register handlers for the following events in your bot’s Node.js module. Supported events:

onMessage — User or bot message
onWebhook — Webhook node in dialog
onAgentTransfer — Agent Transfer node
onEvent — Dialog or FAQ ends
onAlert — Alert message received
onVariableUpdate — Bot published
onClientEvent — Client event from third-party app

onMessage

Fired for every message exchange. Contains two sub-events:

onUserMessage

Triggered when a user message is received by the channel adapter. Syntax:

on_user_message: function(requestId, data, callback)

Parameters:

Parameter	Description
`requestId`	Unique ID for the message event
`payload`	JSON payload (see below)
`callback`	Call at completion to send updated message and context back to the Platform

{
  "message": "message sent by the bot to the user",
  "taskId": "Dialog task Id",
  "nodeId": "current node id in the dialog flow",
  "channel": "channel name",
  "context": "context object"
}

Example — Route to live agent or forward to bot:

function onUserMessage(requestId, payload, callback) {
    var visitorId = payload.context.session.UserContext._id;
    var entry = _map[visitorId];

    if (payload.message === "clearagent") {
        sdk.clearAgentSession(payload);
    }

    if (entry) {
        // Route to live agent
        var formdata = {};
        formdata.secured_session_id = entry.secured_session_id;
        formdata.license_id = config.liveagentlicense;
        formdata.message = payload.message;
        return api.sendMsg(visitorId, formdata)
            .catch(function(e) {
                delete userDataMap[visitorId];
                delete _map[visitorId];
                return sdk.sendBotMessage(payload, callback);
            });
    } else {
        return sdk.sendBotMessage(payload, callback);
    }
}

onBotMessage

Triggered when the bot sends a message to the user. Syntax:

on_bot_message: function(requestId, data, callback)

Parameters:

Parameter	Description
`requestId`	Unique ID for the message event
`payload`	JSON payload (see below)
`callback`	Call at completion to send updated message and context back to the user

{
  "message": "message sent to the user",
  "channel": "channel name",
  "context": "context object"
}

Example — Switch to live agent when anger tone level ≥ 2:

function onBotMessage(requestId, payload, callback) {
    var visitorId = _.get(payload, 'channel.from');
    var entry = _map[visitorId];

    if (data.message.length === 0 || payload.message === '') return;

    var message_tone = _.get(payload, 'context.message_tone');
    if (message_tone && message_tone.length > 0) {
        var angry = _.filter(message_tone, {tone_name: 'angry'});
        if (angry.length && angry[0].level >= 2) {
            return connectToAgent(requestId, data);
        }
    }

    if (!entry) {
        sdk.sendUserMessage(payload, callback);
    }
}

onWebhook

Triggered when the Platform NL Engine reaches a Webhook node in the dialog flow. Execute business logic and send the updated context back. Syntax:

on_webhook: function(requestId, componentId, payload, callback)

Parameters:

Parameter	Description
`requestId`	Unique ID for the webhook event
`componentId`	Unique ID of the Webhook node
`payload`	JSON payload including context
`callback`	Call at completion to send updated context back to the Platform

Example — Return hotel results:

on_webhook: function(requestId, payload, componentId, callback) {
    if (componentId === 'sendResponse') {
        var hotels = { "hotels": ["Taj Banjara", "Novotel"] };
        payload.context.hotelResults = hotels;
        callback(null, data);
    }
}

Example — Look up flight data by component:

on_webhook: function(requestId, payload, componentId, callback) {
    var context = payload.context;
    if (componentId === 'FlightsInfo') {
        findFlights(context.entities.Source, context.entities.Dest, context.entities.Date)
            .then(function(flightResults) {
                payload.context.flightResults = flightResults;
                callback(null, data);
            });
    } else if (componentId === 'GetSourceAirports') {
        findAirports(context.entities.SourceName)
            .then(function(airportResults) {
                payload.context.sourceAirports = airportResults;
                callback(null, data);
            });
    } else if (componentId === 'GetDestAirports') {
        findAirports(context.entities.DestName)
            .then(function(airportResults) {
                payload.context.destAirports = airportResults;
                callback(null, data);
            });
    }
}

onAgentTransfer

Triggered when the Platform NL Engine reaches an Agent Transfer node. Use this to seamlessly hand off to a live agent. Syntax:

function onAgentTransfer(requestId, data, callback) {
    connectToAgent(requestId, data, callback);
}

Parameters:

Parameter	Description
`requestId`	Unique ID for the event
`payload`	JSON payload including `callbackUrl` and context
`callback`	Call at completion to send updated context back to the Platform

Example payload:

{
  "requestId": "150124415xxxx",
  "botId": "st-b4a22e86-e95b-575c-b888-e106d083xxxx",
  "callbackUrl": "https://platform.kore.ai/api/botsdk/stream/.../serviceCallback/...",
  "context": "..."
}

Example — Connect user to LiveChat agent:

function connectToAgent(requestId, data, cb) {
    var formdata = {};
    formdata.license_id = config.liveagentlicense;
    formdata.welcome_message = "";
    var visitorId = _.get(data, 'channel.channelInfos.from') || _.get(data, 'channel.from');
    visitorId = data.context.session.UserContext._id;
    userDataMap[visitorId] = data;
    data.message = "A human Agent will be assigned to you shortly!";
    sdk.sendUserMessage(data, cb);
    formdata.welcome_message = "Chat history: " + config.app.url + "/history/index.html?visitorId=" + visitorId;
    return api.initChat(visitorId, formdata)
        .then(function(res) {
            _map[visitorId] = {
                secured_session_id: res.secured_session_id,
                visitorId: visitorId,
                last_message_id: 0
            };
        });
}

onEvent

Triggered when a Dialog Task or FAQ ends. Syntax:

on_event: function(requestId, data, callback)

Parameters:

Parameter	Description
`requestId`	Unique ID for the event
`data`	JSON payload including `event.eventType` (`"endDialog"` or `"endFAQ"`)
`callback`	Call at completion

Example:

on_event: function(requestId, data, callback) {
    return sdk.sendAlertMessage(data, callback);
}

The data object includes:

{
  "event": {
    "eventType": "endDialog"
  }
}

Contact Center Events

The Platform emits real-time Contact Center Events to the BotKit channel via onEventNode. These events cover agent actions and conversation lifecycle changes.

These events are only emitted for bots connected to the BotKit channel.

agent_accepted

Triggered when an agent accepts an incoming conversation. Payload fields: sessionId, agentId, agentName, assignedAt, acceptedAt, channelType, userId, conversationId, botId, queueId

"CCAIMetaInfo": {
  "agentFullName": "agent_name",
  "agentEmail": "agent@example.com",
  "agentRole": "Administrator",
  "agentId": "a-c0e6303-...",
  "conversationId": "c-3043b67-...",
  "botId": "st-82e472f0-...",
  "orgId": "o-cf84dff6-...",
  "agentAssignedTime": "2025-07-04T07:35:03.336Z",
  "agentAcceptedTime": "2025-07-04T07:35:36.017Z",
  "queueId": "qu-1a32679-...",
  "sessionId": "686784207f066ea8e0a1xxxx",
  "source": "rtm"
}

conversation_transfer

Triggered when an agent transfers the conversation to another agent or queue. Payload fields: sessionId, fromAgentId, toAgentId or toQueueId, transferSummary, timestamp

"CCAIMetaInfo": {
  "conversationId": "c-3043b67-...",
  "sessionId": "686784207f066ea8e0a1xxxx",
  "source": "rtm",
  "transferSummary": {
    "fromQueue": "qu-1a32679-...",
    "transferredType": "OTHERS",
    "transferredTo": [{ "type": "AGENT", "name": "agent_name" }],
    "transferredAt": "2025-07-04T07:36:51.156Z",
    "isWarmTransfer": false
  }
}

agent_joined_conversation

Triggered when an agent joins an ongoing conference-style conversation. Payload fields: sessionId, agentId, timestampJoin, timestampLeave

agent_exited_conversation

Triggered when an agent exits a conference conversation. Payload fields: sessionId, agentId, timestampJoin, timestampLeave

conversation_terminated

Triggered when a conversation ends (by user, agent, or timeout). Payload fields: sessionId, agentId, userId, timestamp, dispositionSummary, dispositionSets

disposition_submitted

Triggered when a disposition code is submitted post-conversation. Payload fields: sessionId, agentId, dispositionCode, dispositionSummary, timestamp

onAlert

Triggered when a user receives an alert message. Syntax:

on_alert: function(requestId, data, callback)

Example:

on_alert: function(requestId, data, callback) {
    return sdk.sendAlertMessage(data, callback);
}

onVariableUpdate

Triggered when the bot is published (variable_update event). Syntax:

variable_update: function(requestId, data, callback)

Example — Fetch or update bot variables on publish:

var event = data.eventType;
if (first || event == "variable_update") {
    sdk.fetchBotVariable(data, langArr, function(err, response) {
        dataStore.saveAllVariables(response, langArr);
        first = false;
    });
} else {
    var lang = data.language;
    updateBotVariableInDataStore(botVariables, data, event, lang);
}

onClientEvent

Triggered when the bot receives a client event from a third-party application. Used to handle typing indicators and read receipts. Syntax:

on_client_event: function(requestId, data, callback)

Example:

on_client_event: function(requestId, data, callback) {
    console.log("on_client_event:", data.preDefinedEvent, data.customEvent);
    return sdk.sendBotEvent(data, callback);
}

Supported predefined event types:

Event	Request `preDefinedEvent.type`
User started typing	`TYPING_STARTED`
User stopped typing	`TYPING_STOPPED`
User read a message	`MESSAGE_READ` (include `"id": "<msg-id>"`)

Example requests and responses: Typing started — Request:

{
  "resourceid": "/bot.clientEvent",
  "preDefinedEvent": { "type": "TYPING_STARTED" },
  "customEvent": { "test": "test" },
  "botInfo": { "chatBot": "<bot-name>", "taskBotId": "<bot-id>" }
}

Response (ack):

{ "ok": true, "type": "ack" }

Response (event echo):

{
  "type": "events",
  "from": "bot",
  "botInfo": { "chatBot": "<bot-name>", "taskBotId": "<bot-id>" },
  "preDefinedEvent": { "type": "TYPING_STARTED" },
  "customEvent": { "test": "test" },
  "traceId": "6b12f4cc73c806dd"
}

​onMessage

​onUserMessage

​onBotMessage

​onWebhook

​onAgentTransfer

​onEvent

​Contact Center Events

​agent_accepted

​conversation_transfer

​agent_joined_conversation

​agent_exited_conversation

​conversation_terminated

​disposition_submitted

​onAlert

​onVariableUpdate

​onClientEvent

onMessage

onUserMessage

onBotMessage

onWebhook

onAgentTransfer

onEvent

Contact Center Events

agent_accepted

conversation_transfer

agent_joined_conversation

agent_exited_conversation

conversation_terminated

disposition_submitted

onAlert

onVariableUpdate

onClientEvent