BotKit SDK Functions

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);
}

---