Node SDK

ChatBotKit Node SDK allows developers to build conversational AI interfaces and chatbots. Read on to learn how to install and use the SDK, along with its authentication, pagination, and error handling features.

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:

Package	Description
@chatbotkit/sdk	The ChatBotKit API SDK
@chatbotkit/react	The ChatBotKit React SDK
@chatbotkit/next	The ChatBotKit Next.js SDK
@chatbotkit/nextauth	The ChatBotKit NextAuth.js SDK
@chatbotkit/fetch	The ChatBotKit isomorphic fetch implementation
@chatbotkit/agent	The ChatBotKit Agent SDK for building AI agents
@chatbotkit/widget	TypeScript type definitions for the Widget SDK
@chatbotkit/cli	The ChatBotKit command-line interface

Installation

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

npm install @chatbotkit/sdk

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

npm install @chatbotkit/next @chatbotkit/react

Usage

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

const { ChatBotKit } = require('@chatbotkit/sdk')

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

import { ChatBotKit } from '@chatbotkit/sdk'

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:

// access all clients

import { ChatBotKit } from '@chatbotkit/sdk'

Individual client classes can be imported like this:

// access only the conversation client

import { ConversationClient } from '@chatbotkit/sdk/conversation/index.js'

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

import { ConversationClient } from '@chatbotkit/sdk/conversation/index.js'

const client = new ConversationClient({
  // options
})

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

import { Client } from '@chatbotkit/sdk/client.js'
import { conversationList } from '@chatbotkit/sdk/conversation/v1.js'

const client = new Client({
  // options
})

await conversationList(client)

Authentication

All clients must be instantiated with a secret.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

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 pass the runAsUserId parameter to invoke a request in a user context. See the User API. The following example demonstrates how to configure the SDK:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here',
  runAsUserId: '...the user id here'
})

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:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

// get first page

const page1 = await client.conversation.list()

// get the second page

const page2 = await client.conversation.list({ cursor: page1.items.at(-1).id })

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:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

// access all conversations via the .stream() AsyncGenerator

for await (const { type, data } of client.conversation.list().stream()) {
  if (type === 'item') {
	  console.log('conversation', data)
  }
}

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

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const messages = [
  {
    type: 'user',
    text: 'Hello!'
  }
]

// access all conversations via the .stream() AsyncGenerator

for await (const { type, data } of client.conversation.complete(null, { messages }).stream()) {
  if (type === 'token') {
    console.log('token', data)
  }
}

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:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

try {
  const page = await client.conversation.list()
} catch (e) {
  console.log('message', e.message)
  console.log('code', e.code)
}

Every exception contains the following properties:

Property	Type	Description
message	string	The error message
code	string	A short code for the error
request	Request	The request that caused the error
response	Response	The API response

Common code types include:

Code	Description
BAD_REQUEST	The request cannot be accepted
NOT_AUTHENTICATED	The request is not authenticated
NO_SUBSCRIPTION	The account does not have an active subscription
NOT_AUTHORIZED	The request is not authorized
NOT_FOUND	The resource is not found
METHOD_NOT_ALLOWED	The request method is not allowed for this operation
CONFLICT	There is a conflict
TOO_MANY_REQUESTS	The account is above its usage limits

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.

npm install @chatbotkit/agent

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.

import { ChatBotKit } from '@chatbotkit/sdk'
import { execute } from '@chatbotkit/agent/execute'
import { z } from 'zod'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const tools = {
  getWeather: {
    description: 'Get the current weather for a city',
    input: z.object({ city: z.string() }),
    handler: async ({ city }) => {
      return { temperature: '22°C', condition: 'Sunny', city }
    },
  },
}

for await (const { type, data } of execute({
  client,
  messages: [{ type: 'user', text: 'What is the weather in London?' }],
  tools,
  maxIterations: 20,
})) {
  if (type === 'result') {
    console.log('bot:', data.text)
  } else if (type === 'exit') {
    console.log('exit code:', data.code)
  }
}

Options:

Option	Type	Default	Description
`client`	`ChatBotKit`	required	Authenticated SDK client
`messages`	`array`	required (local mode)	Conversation history; the array is mutated as the agent appends bot replies
`conversationId`	`string`	-	Remote mode: ID of an existing conversation; messages are managed server-side
`tools`	`object`	`{}`	Custom tools the agent may call; keys are tool names, values have `description`, `input` (Zod schema), and `handler`
`maxIterations`	`number`	`100`	Maximum number of iterations before the agent exits with a failure code
`abortSignal`	`AbortSignal`	-	Signal to cancel execution mid-stream
`extensions`	`object`	-	Advanced options including `backstory` override and `features` (e.g. skills)

Emitted event types:

Event	Description
`iteration`	Start of each loop iteration; `data.iteration` is the 1-based count
`toolCallStart`	A tool is being invoked; `data.name` and `data.args`
`toolCallEnd`	A tool call completed; `data.name` and `data.result`
`toolCallError`	A tool call failed; `data.name` and `data.error`
`result`	The model produced a response; includes `data.text` and `data.end.reason`
`message`	(local mode) A bot message appended to the conversation history
`exit`	Execution finished; `data.code` (0 = success) and optional `data.message`

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:

const messages = [{ type: 'user', text: 'Perform the task.' }]

const stream = execute({ client, messages, tools })

// inject a user follow-up while the agent is running
messages.push({ type: 'user', text: 'Also handle edge case Y.' })

// inject a context message (not attributed to the user - useful for system updates)
messages.push({ type: 'context', text: 'System: disk usage is now at 90%.' })

for await (const { type, data } of stream) {
  // handle events
}

System tools: Every execute call automatically includes a set of built-in system tools that the model can use to manage task flow. These are merged with any custom tools you provide:

Tool	Description
`plan`	Create or update a step-by-step plan for the task. Accepts `steps` (array) and optional `rationale`.
`progress`	Report task progress. Accepts `completed`, `current`, `blockers`, and `nextSteps` fields.
`exit`	Exit with a status code. Code `0` means success; non-zero means failure. Accepts `code` and optional `message`.
`abort`	Immediately abort the task. Accepts optional `reason` and `hard` (boolean) to kill running processes.

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:

import { tools } from '@chatbotkit/agent/tools'

for await (const { type, data } of execute({
  client,
  messages: [{ type: 'user', text: 'Read src/index.js and summarise it.' }],
  tools,
})) {
  if (type === 'exit') {
    console.log('done, code:', data.code)
  }
}

The built-in tools are:

Tool	Description
`read`	Read file contents with optional `startLine`/`endLine` range
`write`	Write content to a file; supports overwrite, line insert, and line range replace
`edit`	Replace an exact string occurrence in a file (must match exactly once)
`exec`	Execute a non-interactive shell command with configurable `timeout` (seconds)

You can merge built-in tools with your own:

import { tools as builtinTools } from '@chatbotkit/agent/tools'

const myTools = {
  ...builtinTools,
  search: {
    description: 'Search the web',
    input: z.object({ query: z.string() }),
    handler: async ({ query }) => { /* ... */ },
  },
}

loadAgent

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

import { loadAgent } from '@chatbotkit/agent/agent'

const agent = await loadAgent('./my-agent.md')

// agent.backstory, agent.model, agent.name, agent.description, etc.

for await (const { type, data } of execute({
  client,
  backstory: agent.backstory,
  model: agent.model,
  messages: [{ type: 'user', text: 'Start the task.' }],
  tools,
})) {
  if (type === 'exit') {
    console.log('done')
  }
}

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

An optional second argument accepts a roots array of directory paths. When provided, the file is resolved relative to each root in order until it is found. This is useful for resolving agent files from multiple base directories:

const agent = await loadAgent('agents/support.md', {
  roots: ['/workspace', '/shared/agents'],
})

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.

import { loadSkills, createSkillsFeature } from '@chatbotkit/agent/skills'

const { skills, close } = await loadSkills(['./skills'], { watch: true })

for await (const { type, data } of execute({
  client,
  messages: [{ type: 'user', text: 'Run the build.' }],
  tools,
  extensions: {
    features: [createSkillsFeature(skills)],
  },
})) {
  if (type === 'exit') {
    console.log('done')
    close() // stop the file watcher
  }
}

loadSkills(directories, options)

Parameter	Type	Description
`directories`	`string[]`	Paths to scan for skill subdirectories
`options.watch`	`boolean`	Reload skills automatically when `SKILL.md` files change

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.

npm install --global @chatbotkit/cli

Set your API token before using the CLI:

export CHATBOTKIT_API_TOKEN=<your token here>

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.

# show help
cbk --help

cbk api

Manage ChatBotKit resources via the API. Resource subcommands include blueprint, bot, contact, conversation, dataset, file, integration, memory, partner, skillset, team, and more.

# list bots
cbk api bot list

# list conversations
cbk api conversation list

# show help for a specific resource
cbk api bot --help

cbk agent

Run an agent as a background worker that executes a given prompt. The --prompt flag is required. Pass an agent markdown file with --agent to supply a backstory, model, and other configuration.

# run an agent with a prompt
cbk agent --prompt "Summarise the file src/index.js"

# run an agent using an agent file with a skillset
cbk agent --agent ./my-agent.md --prompt "Perform the daily report"

# run with specific built-in tools enabled and a max iteration limit
cbk agent --prompt "Fix the failing tests" --tools read write edit exec --max-iterations 50

Options:

Option	Description
`-a, --agent <file>`	Path to an agent markdown file
`-b, --bot <id>`	Bot ID to use for the conversation
`-m, --model <name>`	Model name override
`--skillset <id>`	Skillset ID to attach
`--dataset <id>`	Dataset ID to attach
`-p, --prompt <text>`	The prompt to execute (required)
`-t, --tools <names...>`	Specific tools to enable (e.g. `read write edit exec`)
`-s, --skills <dirs...>`	Directories to load skills from
`-i, --max-iterations <n>`	Maximum number of iterations (default: 100)
`-d, --debug`	Print raw stream items to stderr

cbk chat

Start an interactive chat session in the terminal. Accepts the same agent and model options as cbk agent.

# start a plain chat session
cbk chat

# chat with a specific bot
cbk chat --bot <bot-id>

# chat using an agent file
cbk chat --agent ./my-agent.md

Options:

Option	Description
`-a, --agent <file>`	Path to an agent markdown file
`-b, --bot <id>`	Bot ID
`-m, --model <name>`	Model name override
`--skillset <id>`	Skillset ID to attach
`--dataset <id>`	Dataset ID to attach
`-t, --tools <names...>`	Specific tools to enable
`-s, --skills <dirs...>`	Directories to load skills from
`-d, --debug`	Print raw stream items to stderr

cbk run

Execute a JavaScript file with all @chatbotkit/* packages available without requiring a local node_modules installation. Useful for quick scripts and automation.

# run a script
cbk run ./my-script.js

# run a script and pass arguments to it
cbk run ./my-script.js --arg value

Any @chatbotkit/* package can be imported inside the script without prior npm install:

import { ChatBotKit } from '@chatbotkit/sdk'
import { execute } from '@chatbotkit/agent'

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:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const messages = [
  {
    type: 'user',
    text: 'Hello!'
  }
]

const { text } = await client.conversation.complete({ model: 'glm-5.2', messages })

console.log('bot:', text)

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

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const messages = [
  {
    type: 'user',
    text: 'Hello!'
  }
]

// access all conversations via the .stream() AsyncGenerator

for await (const { type, data } of client.conversation.complete(null, { model: 'glm-5.2', messages }).stream()) {
  if (type === 'result') {
    console.log('bot:', data)
  }
}

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.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const conversation = await client.conversation.create({
  backstory: '...your backstroy here',
  model: 'glm-5.2'
})

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

for await (const { type, data } of conversation.complete(null, { text: 'Hello!' }).stream()) {
  if (type === 'result') {
    console.log('bot:', data)
  }
}

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:

await conversation.send({ text: 'Hello!' })

We can receive the bot message like this:

const { text } = await conversation.receive()

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.

// server

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const conversation = await client.conversation.create({
  backstory: '...your backstroy here',
  model: 'glm-5.2'
})

const { token } = await client.conversation.session.create(conversation.id)

// pass the token to the client

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

// client

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: token // is the token passed from the server
})

await conversation.send({ text: 'Hello!' })

const { text } = await conversation.receive()

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.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const dataset = await client.dataset.create({
  name: '...the dataset name',
  description: '...the dataset description',
})

await client.dataset.record.create(dataset.id, {
  text: '...the record text'
})

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.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const { records } = await client.dataset.search('...dataset id', '...my search')

// do something wihth the found records

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.

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

ChatBotKit nodejs SDK conversational ai programming ai chatbot development react react.js next next.js

Node SDK

SDKs

Installation

Usage

Compatibility

Instantiation

Authentication

Pagination

Streaming

Exceptions

React

Agent SDK

execute

Built-in tools

loadAgent

loadSkills

CLI

cbk api

cbk agent

cbk chat

cbk run

Next

Examples

Conversation Completion

Creating and Completing Conversations

Conversation Sessions

Creating Datasets and Records

Searching Datasets

Conclusion

Related SDKs and Tools

Terraform Provider

Widget SDK

OpenAI