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.
The ChatBotKit SDK for Node is composed of several individual packages. Each package bring a specific features for the targeted platform:
|@chatbotkit/sdk||The ChatBotKit API SDK|
|@chatbotkit/react||The ChatBotKit React SDK|
|@chatbotkit/next||The ChatBotKit Next.js SDK|
|@chatbotkit/fetch||The ChatBotKit isometric fetch implementation|
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:
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/.
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:
All clients must be instantiated with a
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.
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 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.
All methods can throw exceptions. All exceptions have standard error signature. For example:
Every exception contains the following properties:
|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:
|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.
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.
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
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.
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.
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 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.
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.
Explore various aspects of security, including compliance, encryption, privacy, and more. Discover how ChatBotKit ensures the security of your data and protects your privacy. Learn about security testing, compliance protocols, privacy features, encryption standards, monitoring systems, incident response, authentication and authorization, data residency, data retention, and continuous improvement.
Explore the key concepts of ChatBotKit, a state-of-the-art platform for developing conversational AI systems. Learn about backstories, models, stores, bots, datasets, skillsets, conversations, and integrations. Unleash the full potential of ChatBotKit to design intuitive and impactful chatbots.