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:

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 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:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here',
  runAsUserId: '...the child 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:

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:

• userConversationManager: A React Hook for managing conversation flow. Handles all the heavy lifting of sending and receiving messages, as well as thinking and typing indicators.
• 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.
• ChatMessages: A React component that provides a chat messages interface. Useful for chat interfaces to display messages.

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:

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: 'gpt-4', 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: 'gpt-4', 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](/docs/backstories): '...your backstroy here',
  [model](/docs/glossary#model): 'gpt-4'
})

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: 'gpt-4'
})

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

// 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.