Node SDK

ChatBotKit Node SDK is a software development kit that allows developers to build conversational AI interfaces and chatbots. It provides a set of tools, libraries, and APIs to help developers create chatbots for different platforms.

SDKs

The ChatBotKit SDK for Node is composed of several individual packages. Each package bring a specific features for the targeted platform:

Installation

To install ChatBotKit Node SDK, simply run the following command in your terminal:

Additional SDKs for your platform of choice can be installed in a similar way:

Usage

ChatBotKit Node SDK supports both CommonJS and Modules out of the box. You can import the SDK in your code as follows:

…or if you prefer the module style you can do this:

TypeScript documentation is also available at https://chatbotkit.github.io/node-sdk/.

Compatibility

The Node SDK is compatible with all JavaScript environments including: AWS Lambda, Vercel Serverless, Vercel Edge, Cloudflare Workers, Browser and much more.

Instantiation

The SDK consists of several client libraries. Clients are class objects that contain all available methods for interacting with a particular category of API methods in ChatBotKit. Methods can be imported and used independently. Therefore, both object-oriented and functional programming approaches are fully supported.

Importing the top ChatBotKit class gives you access to all functionalities. For example:

Individual client classes can be imported like this:

Before you start using a client you must instantiate is class. This principle applies to all SDK clients.

Accessing individual methods is as easy as import the base client and the desired method version. For example:

Authentication

All clients must be instantiated with a secret.

The secret can be an API token, which gives you access to all API methods, or a limited session token, which gives you only access to a few conversation methods. The later is used to securely access conversations linked to your individual users.

In addition to the secret you can also pass in runAsUserId parameter if you need to invoke the request no behalf of a child account in a parent-child account configuration (see Partner API). The following example demonstrates how to configure the SDK:

Pagination

All list methods support cursor-based pagination. Results are always in reverse chronological order, meaning that most recent items are always at the top. To get the next page, the cursor must specify the ID of the last item. For example:

You can also use streaming to access all items without manually pagination the results. This powerful feature is discussed in the next section.

Streaming

Streaming is a powerful feature which allows you to access large quantities of ChatBotKit data without manually paginating the results. Streaming is also useful to tap into ChatBotKit events when interacting with your ChatBotKit bots and integrations. Streaming simplifies tremendously all types of access patterns.

All list methods support streaming by default, which means that we can easily paginate through all items and access all results without manual paginations. For example:

Similarly, we can access various events when performing completion and other types of operations, for example:

Notice that the stream method yields objects composed of type and data parameters. The type corresponds to the event type and the data represents the associated information. Methods such as conversation.complete yields various types of event, not just plain tokens.

Exceptions

All methods can throw exceptions. All exceptions have standard error signature. For example:

Every exception contains the following properties:

Common code types include:

All API exception also produce the corresponding status code.

React

The ChatBotKit React SDK offers a comprehensive set of features and capabilities, including:

• useConversationManager: A React Hook for managing conversation flow. Handles all the heavy lifting of sending and receiving messages, as well as thinking and typing indicators.
• useConversationManagerRemote: A React Hook that creates a remote completion function for use with useConversationManager. Accepts a client, endpoint, token, conversationId, botId, backstory, model, and other options. Returns an async generator function compatible with the conversation manager.
• AutoScroller: A React component that automatically scrolls its container when new content is added. Supports anchor (top or bottom), delay, and disabled props.
• AutoTextarea: A React component that automatically resizes the textarea to fit the content. Useful for chat interfaces to allow users to type messages.
• ChatInput: A React component that provides a chat input interface. Useful for chat interfaces to allow users to type messages. It automatically handles modifiers such as ctrl, cmd and shift.
• ChatMessage: A React component that renders a single chat message as Markdown. Supports remarkPlugins, rehypePlugins, and components for custom rendering.
• ChatMessages: A React component that provides a chat messages interface with automatic scrolling. Useful for chat interfaces to display messages.
• ConversationManager: A React context provider component that wraps useConversationManager and exposes the conversation state via ConversationContext. Accepts the same options as useConversationManager.

Agent SDK

The @chatbotkit/agent package provides primitives for building autonomous AI agents that can use tools and run multi-step tasks. It supports both local (stateless) and remote (conversation-backed) execution modes.

execute

The core function is execute, an async generator that runs a conversation loop until the model calls the built-in exit tool, the maxIterations limit is reached, or an abortSignal is triggered. Iterate over the stream with for await...of to receive events as they occur.

Options:

Emitted event types:

Message injection (local mode): You can push new messages onto the messages array while the generator is running. They are included in context at the start of the next iteration:

Built-in tools

The @chatbotkit/agent/tools module exports a ready-to-use tools object containing common filesystem and shell utilities. These are especially useful for coding agents:

The built-in tools are:

You can merge built-in tools with your own:

loadAgent

Load an agent definition from a Markdown file with optional YAML front matter:

The front matter fields supported in agent files are: name, description, backstory, model, botId, skillsetId, and datasetId. The Markdown body is appended to backstory.

loadSkills

The loadSkills function discovers skill definitions from directories. Each skill is a subdirectory containing a SKILL.md file with a YAML front matter block that has name and description fields.

loadSkills(directories, options)

Returns { skills: SkillDefinition[], close: () => void }. Call close() to stop the file watcher when watch is enabled.

createSkillsFeature(skills) wraps the skill list into the extensions.features format expected by execute.

CLI

The @chatbotkit/cli package provides a command-line interface for managing ChatBotKit resources and running AI agents from the terminal.

Set your API token before using the CLI:

The CLI loads environment variables from .env.local, .env, or ~/.cbk/env (in that order), so you can store your token globally and override it per project.

Next

The ChatBotKit SDK for Next.js is crafted to integrate chatbot functionalities seamlessly into Next.js applications, specifically optimized for Next.js Edge runtime environments.

The SDK currently includes the following utilities:

• stream: This function can be used to stream any ChatBotKit streaming response to the client. It will automatically encode the response as JSONL and it is fully compatible with the @chatbotkit/react useConversationManager hook.

Examples

In the upcoming section, we'll delve into a variety of typical use-cases, providing practical insights for your understanding. For those seeking more complex scenarios, a wealth of advanced examples is readily available in the official Node SDK Examples repository. This resource is designed to further enrich your knowledge and skill set.

Conversation Completion

You can complete the next message in a conversation by providing the full history of the conversation so far. For example, to get the next conversation message we can do the following:

Note that the complete method is subject to 30 seconds timeout. For this reason we recommend using the streaming API instead.

The example above does not store your conversation. The next example demonstrates how to do that.

Creating and Completing Conversations

In order to store a conversation, we need to create it first.

After that we can interact with the conversation similar to the previous example.

Notice that instead of sending the full conversation history, we are only sending the user message with the text parameter.

You can also breakdown this into two steps. This particularly useful when you have an async process where the message is captured at one place but completed at a completed at a different part of code. For example:

We can receive the bot message like this:

Keep in mind that the receive method also supports streaming.

Conversation Sessions

To enable secure client-side interaction, we need to create a session and initialise the SDK client-side. We are still using the same code-base server-side and client-side without swapping our mental model. Here is an example.

On the client we can use the token to interact with the API securely.

Keep in mind that sessions expire. We provide the server expiry time in the expiresAt respond parameter. You need to keep track of this time or handle exceptions (NOT_AUTHORIZED code). Also keep in mind that session tokens are limited to the current conversation only. In other words the user can only interact with the chatbot and not any other method in the API.

Creating Datasets and Records

A common use-case is to create and import Datasets and Dataset Records. This is a very easy process.

Searching Datasets

Searching the dataset is part of the conversational flow so typically you do not need to do that when interacting with your conversational AI bot. However, this method is also available in case it is needed. This is how to use it.

Conclusion

This concludes the documentation for ChatBotKit Node SDK. For more information on how to use the SDK, please refer to the official repository at https://github.com/chatbotkit/node-sdk.

Related SDKs and Tools

• Go SDK: https://github.com/chatbotkit/go-sdk - Official Go SDK for building conversational AI applications
• Terraform Provider: chatbotkit/chatbotkit - Infrastructure as Code for ChatBotKit resources
• Widget SDK: See the Widget SDK documentation for embedding AI widgets in web pages