Skip to main content

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.

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

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:
ParameterDescription
stream_idBot ID (from Config Settings)
user_idUser whose history to fetch
skipNumber of messages to skip
limitNumber 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);
}