Base SDK reference
Full API reference for Cord's base chatbot SDK, npm package @cord-sdk/chatbot-base
Overview #
This page is a detailed reference of the base chatbot SDK. For a beginner's overview of how this all fits together, see our Getting Started document, which includes chatbot example code.
Defining a Chatbot #
In order to define a Chatbot object, you'll need to specify the following properties and methods:
A description of the representation of this bot in the Cord UI, i.e., the bot's name, profile picture, etc. The structure of this data is identical to that accepted by the create/update user REST API.
This is an object with the following fields:
Show property details
Called whenever any message is added to any thread anywhere in the Cord application (including messages from the bot itself). Determines whether or not this bot wants to respond to that message. This lets you filter down to only respond on certain threads, only respond to certain people, etc. You'll almost certainly want to start this function with
if (eventIsFromBot(event)) return false so that the bot does not get stuck in a loop responding to itself.What this function returns #
boolean | Promise<boolean>
Whether or not this bot wants to respond to this event. If
true, getResponse will later be called to actually compute the response. If false, then getResponse will be entirely skipped.Arguments this function takes #
event
MessageCreatedWebhookEvent
This is an object with the following fields:
Show property details
Called in order to have the chatbot AI logic generate a new message to add to the end of a thread.
What this function returns #
undefined | null | string | Promise<string | null | undefined> | AsyncIterable<string | null | undefined>
Contents of a new message to add to the end of the thread. This can be returned directly as a
string, or as a Promise which resolves to a string. You can also return an AsyncIterator which yields the message incrementally; the message will be streamed to Cord and appear on users' screens bit-by-bit as the iterator yields it (with the final message being the concatenation of all of the strings yielded). Can also return null or undefined to signal that no new message should be added (but it is better for performance to return false from shouldRespondToEvent instead).Arguments this function takes #
messages
CoreMessageData[]
List of messages in the thread, sorted oldest message first. The message structure is the same as returned by the message REST API.
This is an array of objects, each of which has the following fields:
Show property details
thread
CoreThreadData
Data about the thread. The thread structure is the same as returned by the thread REST API.
This is an object with the following fields:
Show property details
Optional callback, called after
getResponse has finished sending a new message to Cord, with the contents of that message. This can occasionally be useful when you need to do something with the completed Cord message, such as setting metadata on the message. You might also use this callback in a complex game in order to call forceRespond to cause a different AI to continue the conversation!What this function returns #
void | Promise<void>
The return value is ignored.
Arguments this function takes #
response
CoreMessageData
The new message added by
getResponse. The message structure is the same as returned by the message REST API.This is an object with the following fields:
Show property details
messages
CoreMessageData[]
List of messages in the thread, sorted oldest message first. This is exactly the same list of messages which was sent to
getResponse, so it will not include the response message. The message structure is the same as returned by the message REST API.This is an array of objects, each of which has the following fields:
Show property details
thread
CoreThreadData
Data about the thread. The thread structure is the same as returned by the thread REST API.
This is an object with the following fields:
Show property details
Using the ChatbotRegistry #
To create a new ChatbotRegistry, you'll need your Cord project ID and project secret from the Cord console. Then you can call chatbots(project_id, project_secret) to create a new registry. You'll typically do this only once, at server startup.
The resulting registry has the following methods you can call on it:
register #
Registers a new bot. You'll typically call this only once per bot, at server startup.
What this function returns #
Promise<void>
A promise which you should await to ensure the bot has been set up correctly. Rejects if there is an issue talking to the Cord REST API when setting up the bot, resolves with no value otherwise.
Arguments this function takes #
botID
string
A unique identifier for the bot. This uniquely identifies your bot, so you should use the same one at each server startup. It will also be used as the identifier for the bot's Cord user.
bot
Chatbot
The new
Chatbot object to register.This is an object with the following fields:
Show property details
webhookReceived #
Function which you should call in the HTTP POST handler which receives Cord webhooks. See the getting started guide for more information on how to set this up.
What this function returns #
Promise<boolean>
A promise, which will resolve to a boolean. If that boolean is
true, that means that this function has fully handled the webhook and you should respond to the HTTP request with success. If that boolean is false, then this function didn't handle the webhook; you can either handle the webhook yourself (e.g., if you have other uses for Cord webhooks beyond chatbots) or otherwise return an HTTP failure code.Arguments this function takes #
req
Request
The original
Request object received by the webhook HTTP POST handler.forceRespond #
You can call this function to force the bot to respond on a thread, even if there is no incoming message on the thread. This will completely bypass
shouldRespondToEvent and move directly to getResponse. This is useful if you want a bot to start a conversation unprompted, for example.Utility functions #
The SDK provides a couple of small utility functions to help write your chatbot logic.
eventIsFromBot #
Determines if an event was generated by a bot sending a message (as opposed to a human doing so). This is particularly useful for
shouldRespondToEvent to make sure that a bot does not respond to itself.This function works by checking for a special metadata field set on bots registered via this SDK. If you use the Cord APIs to change the metadata on your bot, then this function will no longer detect events coming from it as being from a bot.
messageIsFromBot #
Determines if a message was sent by a bot (as opposed to a human). This can be useful when sending Cord messages to an LLM completion API, which needs to know which messages came from the LLM and which came from a human.
This function works by checking for a special metadata field set on messages sent via this SDK. If you directly use the Cord APIs to have your bot send a message, or use the Cord APIs to change the metadata of any messages sent via this SDK, then this function will not detect them as being from a bot.
What this function returns #
boolean
true if that message was sent by a bot, false otherwise.Arguments this function takes #
message
CoreMessageData
This message structure is the same as returned by the message REST API.
This is an object with the following fields:
Show property details
Not finding the answer you need? Ask our Developer Community