Skip to main content
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);
}