←back to manuals

Node SDK

The ChatBotKit Node.js SDK is a powerful, production-ready library for building conversational AI applications. It provides full TypeScript support, streaming capabilities optimized for Edge and Serverless environments, and comprehensive access to all ChatBotKit platform features.

Key Features

  • Full TypeScript Support: Complete type definitions for all API operations
  • Streaming by Default: Optimized for real-time responses in Edge and Serverless environments
  • Comprehensive API Coverage: Access to all ChatBotKit resources and operations
  • Modern Architecture: Built on ES modules with async/await patterns
  • Flexible Client System: Specialized clients for each resource type
  • Production Ready: Battle-tested with retry logic and error handling

Installation

Install the SDK using npm or your preferred package manager:

Requirements:

  • Node.js 14.x or higher
  • ES modules support
  • A ChatBotKit API secret key

Quick Start

The simplest way to get started is with stateless conversation completion:

This example demonstrates the SDK's streaming capabilities, perfect for building responsive chat interfaces.

Client Architecture

The SDK is organized into specialized clients, each handling a specific resource type. You can use individual clients or the main ChatBotKit client that provides access to all resources.

SDK Structure Maps to API Routes

Important: The SDK follows the exact structure of the API routes. This means that every API endpoint has a direct corresponding method in the SDK, making it intuitive to translate between REST API calls and SDK method calls.

The mapping pattern is straightforward:

  • API route: /api/v1/bot/list → SDK method: cbk.bot.list()
  • API route: /api/v1/bot/create → SDK method: cbk.bot.create()
  • API route: /api/v1/dataset/fetch → SDK method: cbk.dataset.fetch()
  • API route: /api/v1/conversation/complete → SDK method: cbk.conversation.complete()

This 1:1 mapping applies to all resources and operations, making it easy to:

  • Reference API documentation when using the SDK
  • Convert curl commands or HTTP requests to SDK calls
  • Understand the SDK structure based on the API reference

For example, if you see an API endpoint /api/v1/skillset/ability/create, you can immediately know the SDK method is cbk.skillset.ability.create(). This consistent structure extends to all nested resources and operations throughout the SDK.

Main Client

Individual Clients

For tree-shaking and smaller bundle sizes, import only the clients you need:

Available Clients

The SDK provides clients for all ChatBotKit resources:

  • Platform: platform - Platform-wide operations and settings
  • Bots: bot - Bot creation and management with sessions
  • Conversations: conversation - Conversation management with messages, sessions, and attachments
  • Datasets: dataset - Knowledge base management with records and files
  • Skillsets: skillset - Skillset management with abilities
  • Files: file - File upload, download, and management
  • Tasks: task - Scheduled task automation
  • Contacts: contact - Contact management with conversations, secrets, spaces, and tasks
  • Secrets: secret - Secure credential storage
  • Integrations: integration - Third-party service integrations (Discord, Slack, Widget, etc.)
  • Memory: memory - Conversation memory management
  • Spaces: space - Organizational spaces
  • Teams: team - Team collaboration features
  • Partners: partner - Multi-tenant account management
  • Channels: channel - Real-time pub/sub messaging
  • Magic: magic - Simplified integrations
  • Policies: policy - Access control and policies
  • Portal: portal - Portal management
  • Usage: usage - Usage statistics and monitoring
  • Reports: report - Analytics and reporting
  • GraphQL: graphql - GraphQL query interface
  • Blueprints: blueprint - Template management

Configuration Options

All clients accept the same configuration options:

Working with Bots

Bots are AI agents configured with specific behaviors, models, and capabilities.

Creating Bots

Managing Bots

Bot Sessions

Bot sessions provide isolated conversation contexts:

Bot Ratings

Collect feedback on bot interactions:

Conversations

Conversations are the core of chat interactions, supporting both stateless and stateful patterns.

Stateless Conversations

Perfect for one-off interactions without persistent storage:

Stateful Conversations

Create persistent conversation records:

Conversation Messages

Manage message history:

Conversation Attachments

Add files to conversations:

Conversation Ratings

Track conversation quality:

Datasets

Datasets provide knowledge bases that bots can reference during conversations.

Creating and Managing Datasets

Dataset Records

Add and manage individual entries:

Dataset Files

Bulk import data from files:

Skillsets

Skillsets provide bots with custom abilities and function-calling capabilities.

Managing Skillsets

Skillset Abilities

Add specific abilities to skillsets:

Files

Manage file uploads and downloads.

File Operations

Tasks

Create scheduled or on-demand automated workflows.

Task Management

Contacts

Manage user contacts and associate them with conversations.

Contact Operations

Streaming Responses

The SDK is optimized for streaming, essential for real-time chat experiences.

Understanding Stream Types

Streaming responses emit different event types:

Non-Streaming Responses

For simpler use cases, await the complete response:

Partner API

Build multi-tenant applications with account management.

Managing Partner Users

Running Operations as Partner User

Secrets

Securely store credentials for integrations.

Integration Management

Configure third-party service integrations.

Widget Integration

Slack Integration

Discord Integration

Usage Monitoring

Track API usage and resource consumption.

Error Handling

The SDK provides structured error handling:

TypeScript Support

The SDK includes comprehensive TypeScript definitions:

Best Practices

Security

  • Never commit API secrets: Use environment variables or secret management services
  • Rotate credentials regularly: Change API keys periodically
  • Use separate keys per environment: Different keys for development, staging, and production
  • Enable privacy and moderation: Protect user data and filter inappropriate content
  • Validate user inputs: Sanitize data before passing to the SDK

Performance

  • Use streaming for chat interfaces: Provides better user experience
  • Implement pagination: Don't fetch all records at once
  • Cache static data: Store frequently accessed bots, datasets, etc.
  • Use individual clients: Import only what you need for smaller bundles
  • Monitor token usage: Track consumption to optimize costs

Architecture

  • Use stateless conversations for simple use cases: Reduces overhead
  • Use stateful conversations for complex flows: Enables history tracking
  • Implement proper error handling: Gracefully handle API errors
  • Use TypeScript: Catch errors at compile time
  • Leverage contact fingerprints: Automatic contact creation with deduplication

Edge and Serverless

The SDK is optimized for Edge and Serverless environments:

Additional Resources

Support

SDKNode.jsTypeScriptStreaming