BotKit SDK Functions - Kore.ai Docs

Back to BotKit SDK Overview The BotKit SDK provides functions for controlling message flow, managing agent sessions, and working with async webhook responses. Available functions:

sdk.sendUserMessage
sdk.sendBotMessage
sdk.AsyncResponse
sdk.respondToHook
sdk.registerBot
sdk.saveData
sdk.getSavedData
sdk.getMessages
sdk.clearAgentSession
sdk.startAgentSession
sdk.resetBot
sdk.extendRequestId
sdk.skipBotMessage
sdk.skipUserMessage
sdk.closeConversationSession

sdk.sendUserMessage

Sends a message to the user. Use inside on_bot_message to modify the bot’s reply before delivery. Syntax:

sdk.sendUserMessage(payload, callback)

Payload:

{
  "message": "Spell-corrected message sent by the bot to the user",
  "originalMessage": "Original 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>"
}

When spell correction is unavailable:

{
  "message": "Original message",
  "originalMessage": "Original message",
  "languageInfo": {
    "currentLanguage": "en",
    "detectedLanguages": ["en", "fr"],
    "spellCorrectedInput": { "en": "corrected input" }
  }
}

Meta tags (v8.0+) — Add to payload to tag the conversation:

"metaTags": {
  "userMetaTags":    [{ "name": "<string>", "value": "<string>" }],
  "sessionMetaTags": [{ "name": "<string>", "value": "<string>" }],
  "messageMetaTags": [{ "name": "<string>", "value": "<string>" }]
}

Examples:

// Return error to user
return sdk.sendUserMessage(payload, function(err) {
    if (err) console.log("err", err);
});

// Notify user of agent transfer
data.message = "An Agent will be assigned to you shortly!";
sdk.sendUserMessage(payload, callback);

// Override message based on user selection
if (message == "yes") {
    payload.overrideMessagePayload = {
        body: "Enter the currency code for conversion",
        isTemplate: false
    };
    return sdk.sendUserMessage(payload);
}

sdk.sendBotMessage

Sends a message to the bot. Use inside on_user_message to modify or forward the user’s message. Messages are validated: max 3000 characters total, max 1200 characters per word. Syntax:

sdk.sendBotMessage(payload, callback)

Payload:

{
  "message": "Message sent by the user",
  "channel": "Channel name",
  "context": "<context object>"
}

Examples:

// Forward message to bot
on_user_message: function(requestId, payload, callback) {
    sdk.sendBotMessage(payload, callback);
}

// Intercept and reroute
on_user_message: function(requestId, payload, callback) {
    if (payload.message === "Hi") {
        payload.message = "Hello";
        return sdk.sendUserMessage(payload, callback);  // Return to user
    } else if (!payload.agent_transfer) {
        return sdk.sendBotMessage(payload, callback);   // Forward to bot
    } else {
        payload.message = "Agent Message";
        return sdk.sendUserMessage(payload, callback);
    }
}

sdk.AsyncResponse

Sends an HTTP 202 to the Platform to indicate an async webhook response is in progress. Call sdk.respondToHook(payload) when the response is ready. Syntax:

callback(null, new sdk.AsyncResponse())

Example — Async cab booking:

on_webhook: function(requestId, payload, componentName, callback) {
    if (componentName === 'FindNearbyCabs') {
        findCabs().then(function(cabList) {
            payload.context.cabList = cabList;
            callback(null, data);  // Synchronous
        });
    } else if (componentName === 'BookTheCab') {
        sdk.saveData(requestId, payload).then(function() {
            bookTheCab(requestId, ...);
            callback(null, new sdk.AsyncResponse());  // Async
        });
    }
}

sdk.respondToHook

Sends the final webhook response to the Platform after async processing completes. Syntax:

sdk.respondToHook(payload)

Payload:

{
  "taskId": "Dialog task ID",
  "nodeId": "Current node ID in the dialog flow",
  "channel": "Channel name",
  "context": "<context object>"
}

Example:

function onBookingFailure(requestId) {
    sdk.getSavedData(requestId).then(function(payload) {
        payload.context.successful = false;
        sdk.respondToHook(payload);
    });
}

sdk.registerBot

Registers a bot and its event callbacks. Create one Node.js file per bot and export the required variables. Module structure:

module.exports = {
    botId: "xxxxx",
    botName: "xxxxx",
    on_user_message: function(requestId, data, callback) { /* ... */ },
    on_bot_message: function(requestId, data, componentName, callback) { /* ... */ },
    on_webhook: function(requestId, data, componentName, callback) { /* ... */ }
}

Register the bot:

sdk.registerBot(require('./<BotName>.js'));

Example:

module.exports = {
    botId: botId,
    botName: botName,
    on_user_message: function(requestId, payload, callback) {
        onUserMessage(requestId, payload, callback);
    },
    on_bot_message: function(requestId, payload, callback) {
        onBotMessage(requestId, payload, callback);
    },
    on_agent_transfer: function(requestId, payload, callback) {
        onAgentTransfer(requestId, payload, callback);
    },
    gethistory: gethistory
};

sdk.saveData

Saves payload data to Redis by requestId. Use during async webhook handling to persist state between the initial event and the final response. Syntax:

sdk.saveData(requestId, payload)

Example:

on_webhook: function(requestId, payload, componentId, callback) {
    if (componentId === 'BookTheCab') {
        sdk.saveData(requestId, payload).then(function() {
            payload.successful = 'true';
            payload.bookedCab = context.entities.selectedCab || {};
            callback(null, payload);
        });
    }
}

sdk.getSavedData

Reads payload data from Redis by requestId. Use when responding to an async webhook to retrieve the saved state. Syntax:

sdk.getSavedData(requestId, payload)

Example:

function onBookingSuccess(requestId) {
    sdk.getSavedData(requestId).then(function(payload) {
        payload.context.bookedCab = payload.entities.selectedCab;
        payload.context.successful = true;
        sdk.respondToHook(payload);
    });
}

sdk.getMessages

Retrieves the conversation history between the bot and user in reverse chronological order. Supports pagination. Syntax:

sdk.getMessages(requestData, callback)

Parameters:

Parameter	Description
`stream_id`	Bot ID (from Config Settings)
`user_id`	User whose history to fetch
`skip`	Number of messages to skip
`limit`	Number of messages per page
`channelType`	(Optional) channel filter

Example:

data.limit = 100;
sdk.getMessages(data, function(err, resp) {
    if (err) { res.status(400); return res.json(err); }
    res.status(200).json(resp.messages);
});

sdk.clearAgentSession

Clears the agent session and re-establishes the conversation with the bot. Call this when the live agent closes the chat (triggered by a chat_closed event from the third-party provider). Syntax:

sdk.clearAgentSession(requestData, callback)

Example:

if (event.type === "chat_closed") {
    delete userResponseDataMap[visitorId];
    delete _map[visitorId];
    sdk.clearAgentSession(data);
}

sdk.startAgentSession

Notifies the Platform that an agent transfer is in progress. After calling this, the data object received by BotKit will have agent_session: true. When sdk.clearAgentSession is called, the Platform sets it back to false. Syntax:

sdk.startAgentSession(requestData, callback)

Example:

function connectToAgent(requestId, data, cb) {
    data.message = "An Agent will be assigned to you shortly!";
    sdk.sendUserMessage(data, cb);
    sdk.startAgentSession(data, cb);  // Notify Platform before initChat
    return api.initChat(visitorId, formdata).then(function(res) {
        _map[visitorId] = { secured_session_id: res.secured_session_id, ... };
    });
}

sdk.resetBot

Clears the bot context and silently discards the current task. Use when a user explicitly requests a reset. Syntax:

sdk.resetBot(requestData, callback)

Example:

on_user_message: function(requestId, data, callback) {
    if (data.message === "reset bot") {
        sdk.resetBot(data, callback);
    }
}

sdk.extendRequestId

Extends the time window for BotKit to send messages to the Platform. Use during prolonged agent transfer sessions where the Platform might stop receiving messages. Syntax:

sdk.extendRequestId(requestData, callback)

Extension is ineffective after 15 minutes of conversation inactivity. An inactive session resets agent_transfer mode regardless.

Example:

function onBotMessage(requestId, data, cb) {
    event = schedular.scheduleJob("*/4 * * * *", function() {
        sdk.extendRequestId(data, cb);
    });
}

sdk.skipBotMessage

Skips a specific bot message and proceeds to the next dialog step without waiting for BotKit delivery. Syntax:

sdk.skipBotMessage(requestData, callback)

Example:

if (data.message === "skipBotMessage") {
    sdk.skipBotMessage(data, cb);
}

sdk.skipUserMessage

Skips a specific user message and proceeds to the next dialog step without waiting for BotKit confirmation. Syntax:

sdk.skipUserMessage(requestData, callback)

Example:

if (data.message === "skipUserMessage") {
    sdk.skipUserMessage(data, cb);
}

sdk.closeConversationSession

Closes the current conversation session. Syntax:

sdk.closeConversationSession(requestData, callback)

Example:

if (data.message === "closeConversationSession") {
    sdk.closeConversationSession(data, cb);
}

​sdk.sendUserMessage

​sdk.sendBotMessage

​sdk.AsyncResponse

​sdk.respondToHook

​sdk.registerBot

​sdk.saveData

​sdk.getSavedData

​sdk.getMessages

​sdk.clearAgentSession

​sdk.startAgentSession

​sdk.resetBot

​sdk.extendRequestId

​sdk.skipBotMessage

​sdk.skipUserMessage

​sdk.closeConversationSession

sdk.sendUserMessage

sdk.sendBotMessage

sdk.AsyncResponse

sdk.respondToHook

sdk.registerBot

sdk.saveData

sdk.getSavedData

sdk.getMessages

sdk.clearAgentSession

sdk.startAgentSession

sdk.resetBot

sdk.extendRequestId

sdk.skipBotMessage

sdk.skipUserMessage

sdk.closeConversationSession