### Project Setup and Build Commands (Shell)

Source: https://github.com/chatbotkit/node-sdk

Shell commands for setting up, checking, and building a monorepo project managed with pnpm and turbo build. These commands are essential for local development and contribution. They cover installation, type/lint checks, and project-wide or package-specific builds.

```shell
pnpm install
pnpm check
pnpm lint
pnpm build
pnpm -F @chatbotkit/${PACKAGE_NAME} build
```

--------------------------------

### Install ChatBotKit SDK via npm

Source: https://github.com/chatbotkit/node-sdk

Installs the ChatBotKit SDK package using npm. This command should be run in the project root before importing the SDK. No additional dependencies are required beyond a Node.js environment.

```bash
npm install @chatbotkit/sdk
```

--------------------------------

### Streaming Conversation Example in JavaScript

Source: https://chatbotkit.github.io/node-sdk

This example demonstrates using the ConversationClient to handle streaming responses in Edge and Serverless environments with async iteration. It requires the @chatbotkit/sdk package and a valid configuration object. Inputs include a null conversation ID and model specification; outputs streamed events with type and data. Limitations include incomplete model specification in the example.

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

const client = new ConversationClient(/* configuration */)

for await (const { type, data } of client
  .complete(null, {
    model: '
```

--------------------------------

### GET /api/v1/whatsapp/integrations

Source: https://chatbotkit.github.io/node-sdk

Lists all WhatsApp integrations. This endpoint retrieves a list of all configured WhatsApp integrations.

```APIDOC
## GET /api/v1/whatsapp/integrations

### Description
Retrieves a list of all WhatsApp integrations configured in the system.

### Method
GET

### Endpoint
/api/v1/whatsapp/integrations

### Response
#### Success Response (200)
- **items** (array) - List of WhatsApp integration objects

#### Response Example
{
  "items": [
    {
      "id": "whatsapp-integration-123",
      "config": {
        "phoneNumber": "+1234567890"
      }
    }
  ]
}
```

--------------------------------

### Next.js Integration with ChatBotKit SDK (JavaScript/JSX)

Source: https://github.com/chatbotkit/node-sdk

Shows how to embed ChatBotKit components in a Next.js project, including a page component and a chat area with conversation context. The example covers client‑side rendering, usage of the ConversationContext, and rendering streamed messages. Requires @chatbotkit/react and React 18+.

```javascript
// file: ./app/page.jsx
import ChatArea from '../components/ChatArea.jsx'

export default function Page() {
  return <ChatArea />
}
```

```javascript
// file: ./components/ChatArea.jsx
'use client'
import { useContext } from 'react'
import { complete } from '../actions/conversation.jsx'
import { ChatInput, ConversationContext } from '@chatbotkit/react'
import ConversationManager from '@chatbotkit/react/components/ConversationManager'

export function ChatMessages() {
  const { thinking, text, setText, messages, submit } = useContext(ConversationContext)
  return (
    <div>
      {messages.map(({ id, type, text, children }) => {
        switch (type) {
          case 'user':
            return (
              <div key={id}>
                <strong>user:</strong> {text}
              </div>
            )
          case 'bot':
            return (
              <div key={id}>
                <strong>bot:</strong> {text}
                {children ? <div>{children}</div> : null}
              </div>
            )
          default:
            return null
        }
      })}
      {thinking ? (
        <div><strong>bot:</strong>...</div>
      ) : null}
      <ChatInput
        value={text}
        onChange={e => setText(e.target.value)}
        onSubmit={submit}
        placeholder="Type something..."
        style={{ border: 0, outline: 'none', resize: 'none', width: '100%', marginTop: '10px' }}
      />
 </div>
  )
}

```

--------------------------------

### Define Server Actions for Chatbot AI Functions (React/JSX)

Source: https://github.com/chatbotkit/node-sdk

This code defines server-side actions for a chatbot using '@chatbotkit/react/actions/complete'. It includes example functions like getUserName, getCalendarEvents, and declineCalendarEvent, which can be called by the AI model. Dependencies include '@chatbotkit/react' and '@chatbotkit/sdk'.

```jsx
import CalendarEvents from '../components/CalendarEvents.jsx'
import { streamComplete } from '@chatbotkit/react/actions/complete'
import { ChatBotKit } from '@chatbotkit/sdk'

const cbk = new ChatBotKit({
  secret: process.env.CHATBOTKIT_API_SECRET,
})

export async function complete({ messages }) {
  return streamComplete({
    client: cbk.conversation,
    messages,
    functions: [
      {
        name: 'getUserName',
        description: 'Get the authenticated user name',
        parameters: {},
        handler: async () => {
          return 'John Doe'
        },
      },
      {
        name: 'getCalendarEvents',
        description: 'Get a list of calendar events',
        parameters: {},
        handler: async () => {
          const events = [
            { id: 1, title: 'Meeting with Jane Doe' },
            { id: 2, title: 'Meeting with Jill Doe' },
          ]
          return {
            children: null,
            result: {
              events,
            },
          }
        },
      },
      {
        name: 'declineCalendarEvent',
        description: 'Decline a calendar event',
        parameters: {
          type: 'object',
          properties: {
            id: {
              type: 'number',
              description: 'The ID of the event to decline',
            },
          },
          required: ['id'],
        },
        handler: async ({ id }) => {
          return `You have declined the event with ID ${id}`
        },
      },
    ],
  })
}
```

--------------------------------

### Stream AI Responses with ConversationClient (JavaScript)

Source: https://github.com/chatbotkit/node-sdk

Demonstrates how to use the ConversationClient to request a completion from a language model and stream token‑by‑token output. It works in edge and serverless runtimes and outputs each token to stdout. Requires the @chatbotkit/sdk package and appropriate model configuration.

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

const client = new ConversationClient(/* configuration */)

for await (const { type, data } of client
  .complete(null, { model: 'gpt-4', messages })
  .stream()) {
  if (type === 'token') {
    process.stdout.write(data.token)
  }
}
```

--------------------------------

### Advanced Conversational AI with Streaming in Next.js

Source: https://chatbotkit.github.io/node-sdk

This example demonstrates building a sophisticated conversational AI interface in Next.js using streaming responses, function calls, and server-side rendering. It depends on the @chatbotkit/react library and ChatbotKit SDK for API interactions. Inputs include user messages and function parameters; outputs are streamed bot responses and UI updates. Limitations include requiring Next.js 13+ and proper API secret configuration for functionality.

```javascript
// file: ./app/page.jsx
import ChatArea from '../components/ChatArea.jsx'
export default function Page() {
  return <ChatArea />
}

// file: ./components/ChatArea.jsx
'use client'
import { useContext } from 'react'
import { complete } from '../actions/conversation.jsx'
import { ChatInput, ConversationContext } from '@chatbotkit/react'
import ConversationManager from '@chatbotkit/react/components/ConversationManager'

export function ChatMessages() {
  const { thinking, text, setText, messages, submit, } = useContext(ConversationContext)
  return (
    <div>
      {messages.map(({ id, type, text, children }) => {
        switch (type) {
          case 'user':
            return (
              <div key={id}>
                <strong>user:</strong> {text}
              </div>
            )
          case 'bot':
            return (
              <div key={id}>
                <strong>bot:</strong> {text}
                {children ? (
                  <div>{children}</div>
                ) : null}
              </div>
            )
        }
      })}
      {thinking ? (
        <div>
          <strong>bot:</strong> thinking...
        </div>
      ) : null}
    </div>
  )
}

export function ChatInputArea() {
  const { text, setText, submit } = useContext(ConversationContext)
  return (
    <ChatInput
      value={text}
      onChange={(e) => setText(e.target.value)}
      onSubmit={submit}
      placeholder="Type something..."
      style={{ border: 0, outline: 'none', resize: 'none', width: '100%', marginTop: '10px', }}
    />
  )
}

export default function ChatArea() {
  return (
    <ConversationManager>
      <ChatMessages />
      <ChatInputArea />
    </ConversationManager>
  )
}

// file: ./actions/conversation.jsx
'use server'
import CalendarEvents from '../components/CalendarEvents.jsx'
import { streamComplete } from '@chatbotkit/react/actions/complete'
import { ChatBotKit } from '@chatbotkit/sdk'

const cbk = new ChatBotKit({
  secret: process.env.CHATBOTKIT_API_SECRET,
})

export async function complete({ messages }) {
  return streamComplete({
    client: cbk.conversation,
    messages,
    functions: [
      {
        name: 'getUserName',
        description: 'Get the authenticated user name',
        parameters: {},
        handler: async () => {
          return 'John Doe'
        },
      },
      {
        name: 'getCalendarEvents',
        description: 'Get a list of calendar events',
        parameters: {},
        handler: async () => {
          const events = [
            { id: 1, title: 'Meeting with Jane Doe' },
            { id: 2, title: 'Meeting with Jill Doe' },
          ]
          return {
            children: <CalendarEvents events={events} />,
            result: { events, },
          }
        },
      },
      {
        name: 'declineCalendarEvent',
        description: 'Decline a calendar event',
        parameters: {
          type: 'object',
          properties: {
            id: {
              type: 'number',
              description: 'The ID of the event to decline',
            },
          },
          required: ['id'],
        },
        handler: async ({ id }) => {
          return `You have declined the event with ID ${id}`
        },
      },
    ],
  })
}
```

--------------------------------

### Basic Chat Implementation in Next.js

Source: https://chatbotkit.github.io/node-sdk

This example shows a simple way to integrate chat functionality into a Next.js application using the ChatbotKit SDK. It relies on @chatbotkit/react for hooks and components, with an API endpoint for completion. User inputs are text messages; outputs are displayed chat messages. Note that it requires a valid API endpoint and does not include advanced features like streaming.

```javascript
// file: ./pages/index.js
import { AutoTextarea, useConversationManager } from '@chatbotkit/react'

export default function Index() {
  const { thinking, text, setText, messages, submit, } = useConversationManager({
    endpoint: '/api/conversation/complete',
  })

  function handleOnKeyDown(event) {
    if (event.keyCode === 13) {
      event.preventDefault()
      submit()
    }
  }

  return (
    <div>
      {messages.map(({ id, type, text }) => (
        <div key={id}>
          <strong>{type}:</strong> {text}
        </div>
      ))}
      {thinking && (
        <div>
          <strong>bot:</strong> thinking...
        </div>
      )}
      <AutoTextarea
        value={text}
        onChange={(e) => setText(e.target.value)}
        onKeyDown={handleOnKeyDown}
        placeholder="Type something..."
        style={{ border: 0, outline: 'none', resize: 'none', width: '100%', marginTop: '10px', }}
      />
    </div>
  )
}
```

--------------------------------

### Basic Next.js Chatbot Client Component (React/JSX)

Source: https://github.com/chatbotkit/node-sdk

A basic Next.js client-side component for a chatbot using '@chatbotkit/react'. It utilizes the `useConversationManager` hook to handle user input, display messages, and submit them to the conversation endpoint. Dependencies include '@chatbotkit/react'.

```jsx
import { AutoTextarea, useConversationManager } from '@chatbotkit/react'

export default function Index() {
  const {
    thinking,
    text,
    setText,
    messages,
    submit,
  } = useConversationManager({
    endpoint: '/api/conversation/complete',
  })

  function handleOnKeyDown(event) {
    if (event.keyCode === 13) {
      event.preventDefault()
      submit()
    }
  }

  return (
    <>
      {messages.map(({ id, type, text }) => (
        <div key={id}>
          <strong>{type}:</strong> {text}
        </div>
      ))}
      {thinking && (
        <div>
          <strong>bot:</strong> thinking...
        </div>
      )}
      <AutoTextarea
        value={text}
        onChange={(e) => setText(e.target.value)}
        onKeyDown={handleOnKeyDown}
        placeholder="Type something..."
        style={{
          border: 0,
          outline: 'none',
          resize: 'none',
          width: '100%',
          marginTop: '10px',
        }}
      />
    </>
  )
}
```

--------------------------------

### Next.js API Route for Chatbot Streaming (JavaScript/Node.js)

Source: https://github.com/chatbotkit/node-sdk

An Edge API route for a Next.js application that handles chatbot conversation streaming using '@chatbotkit/next/edge'. It initializes the ChatBotKit SDK with an API secret and streams the conversation completion response. Requires '@chatbotkit/sdk' and '@chatbotkit/next'.

```javascript
import { ChatBotKit } from '@chatbotkit/sdk'
import { stream } from '@chatbotkit/next/edge'

const cbk = new ChatBotKit({
  secret: process.env.CHATBOTKIT_API_SECRET,
})

export default async function handler(req) {
  const { messages } = await req.json()
  return stream(cbk.conversation.complete(null, { messages }))
}

export const config = {
  runtime: 'edge',
}
```

--------------------------------

### POST /api/v1/whatsapp/integrations

Source: https://chatbotkit.github.io/node-sdk

Creates a new WhatsApp integration. This endpoint allows you to set up a new WhatsApp integration with the specified configuration.

```APIDOC
## POST /api/v1/whatsapp/integrations

### Description
Creates a new WhatsApp integration with the provided configuration.

### Method
POST

### Endpoint
/api/v1/whatsapp/integrations

### Request Body
- **config** (object) - Required - WhatsApp integration configuration details

### Request Example
{
  "config": {
    "phoneNumber": "+1234567890",
    "apiKey": "whatsapp_api_key"
  }
}

### Response
#### Success Response (201)
- **id** (string) - Unique identifier for the created integration
- **config** (object) - Configuration details of the integration

#### Response Example
{
  "id": "whatsapp-integration-123",
  "config": {
    "phoneNumber": "+1234567890"
  }
}
```

--------------------------------

### POST /api/v1/widget/integrations

Source: https://chatbotkit.github.io/node-sdk

Creates a new widget integration. This endpoint allows you to set up a new widget integration with the specified configuration.

```APIDOC
## POST /api/v1/widget/integrations

### Description
Creates a new widget integration with the provided configuration.

### Method
POST

### Endpoint
/api/v1/widget/integrations

### Request Body
- **config** (object) - Required - Widget integration configuration details

### Request Example
{
  "config": {
    "domain": "example.com",
    "theme": "light"
  }
}

### Response
#### Success Response (201)
- **id** (string) - Unique identifier for the created integration
- **config** (object) - Configuration details of the integration

#### Response Example
{
  "id": "widget-integration-456",
  "config": {
    "domain": "example.com",
    "theme": "light"
  }
}
```

--------------------------------

### File Management API

Source: https://chatbotkit.github.io/node-sdk

This section details the file management endpoints, enabling operations such as uploading, downloading, deleting, and listing files.

```APIDOC
## POST /api/v1/files/upload

### Description
Uploads a new file.

### Method
POST

### Endpoint
/api/v1/files/upload

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **file** (file) - Required - The file to upload.

### Request Example
{
  "file": "file.txt"
}

### Response
#### Success Response (201)
- **fileId** (integer) - The ID of the uploaded file.

#### Response Example
{
  "fileId": 456
}
```

--------------------------------

### POST /api/v1/magic/generate

Source: https://chatbotkit.github.io/node-sdk

Generates magical content using AI. This endpoint creates content based on the provided prompt and configuration.

```APIDOC
## POST /api/v1/magic/generate

### Description
Generates content using AI based on the provided prompt and configuration.

### Method
POST

### Endpoint
/api/v1/magic/generate

### Request Body
- **prompt** (string) - Required - The prompt to generate content from
- **config** (object) - Optional - Configuration for content generation

### Request Example
{
  "prompt": "Write a short story about a robot learning to love",
  "config": {
    "temperature": 0.8,
    "maxTokens": 500
  }
}

### Response
#### Success Response (200)
- **content** (string) - The generated content
- **metadata** (object) - Metadata about the generation process

#### Response Example
{
  "content": "Once upon a time, there was a robot named R-42 who...",
  "metadata": {
    "tokensUsed": 245,
    "generationTime": 1.2
  }
}
```

--------------------------------

### Dataset Management API

Source: https://chatbotkit.github.io/node-sdk

This section describes the endpoints for managing datasets within ChatBotKit.  It covers creating, deleting, fetching, listing, searching, and updating datasets.

```APIDOC
## POST /api/v1/datasets

### Description
Creates a new dataset.

### Method
POST

### Endpoint
/api/v1/datasets

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **datasetName** (string) - Required - The name of the dataset.
- **description** (string) - Optional - A description of the dataset.

### Request Example
{
  "datasetName": "my_dataset",
  "description": "This is a sample dataset."
}

### Response
#### Success Response (201)
- **datasetId** (integer) - The ID of the newly created dataset.

#### Response Example
{
  "datasetId": 123
}

```

```APIDOC
## DELETE /api/v1/datasets/{datasetId}

### Description
Deletes a dataset by its ID.

### Method
DELETE

### Endpoint
/api/v1/datasets/{datasetId}

### Parameters
#### Path Parameters
- **datasetId** (integer) - Required - The ID of the dataset to delete.

#### Query Parameters
- None

#### Request Body
- None

### Response
#### Success Response (204)
- None

#### Response Example
{}

```

```APIDOC
## GET /api/v1/datasets/{datasetId}

### Description
Fetches a dataset by its ID.

### Method
GET

### Endpoint
/api/v1/datasets/{datasetId}

### Parameters
#### Path Parameters
- **datasetId** (integer) - Required - The ID of the dataset to fetch.

#### Query Parameters
- None

#### Request Body
- None

### Response
#### Success Response (200)
- **datasetName** (string) - The name of the dataset.
- **description** (string) - The description of the dataset.

#### Response Example
{
  "datasetName": "my_dataset",
  "description": "This is a sample dataset."
}
```

```APIDOC
## GET /api/v1/datasets

### Description
Lists all datasets.

### Method
GET

### Endpoint
/api/v1/datasets

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Response
#### Success Response (200)
- **datasets** (array) - An array of dataset objects.

#### Response Example
[
  {
    "datasetId": 123,
    "datasetName": "my_dataset",
    "description": "This is a sample dataset."
  }
]
```

```APIDOC
## POST /api/v1/datasets/search

### Description
Searches for datasets based on specified criteria.

### Method
POST

### Endpoint
/api/v1/datasets/search

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **query** (string) - Required - The search query.

### Request Example
{
  "query": "sample"
}

### Response
#### Success Response (200)
- **datasets** (array) - An array of dataset objects matching the query.

#### Response Example
[
  {
    "datasetId": 123,
    "datasetName": "my_dataset",
    "description": "This is a sample dataset."
  }
]
```

```APIDOC
## PUT /api/v1/datasets/{datasetId}

### Description
Updates a dataset by its ID.

### Method
PUT

### Endpoint
/api/v1/datasets/{datasetId}

### Parameters
#### Path Parameters
- **datasetId** (integer) - Required - The ID of the dataset to update.

#### Query Parameters
- None

#### Request Body
- **datasetName** (string) - Optional - The new name of the dataset.
- **description** (string) - Optional - The new description of the dataset.

### Request Example
{
  "datasetName": "new_dataset_name",
  "description": "This dataset has been updated."
}

### Response
#### Success Response (200)
- **datasetId** (integer) - The ID of the updated dataset.

#### Response Example
{
  "datasetId": 123
}
```

--------------------------------

### POST /api/v1/memory

Source: https://chatbotkit.github.io/node-sdk

Creates a new memory entry. This endpoint allows you to store information that can be retrieved later for context-aware interactions.

```APIDOC
## POST /api/v1/memory

### Description
Creates a new memory entry that can be used for context-aware interactions.

### Method
POST

### Endpoint
/api/v1/memory

### Request Body
- **content** (string) - Required - The content to store in memory
- **metadata** (object) - Optional - Additional metadata for the memory entry

### Request Example
{
  "content": "User's preference for sci-fi movies",
  "metadata": {
    "userId": "user-123",
    "category": "entertainment"
  }
}

### Response
#### Success Response (201)
- **id** (string) - Unique identifier for the created memory
- **content** (string) - The stored content
- **metadata** (object) - Associated metadata

#### Response Example
{
  "id": "memory-789",
  "content": "User's preference for sci-fi movies",
  "metadata": {
    "userId": "user-123",
    "category": "entertainment",
    "createdAt": "2023-10-01T12:00:00Z"
  }
}
```

--------------------------------

### POST /api/conversation/complete

Source: https://chatbotkit.github.io/node-sdk

Completes a conversation using the ChatBotKit API. This endpoint takes in a list of messages representing the conversation history and returns a streamed response.

```APIDOC
## POST /api/conversation/complete

### Description
Completes a conversation using the ChatBotKit API. This endpoint takes in a list of messages representing the conversation history and returns a streamed response.

### Method
POST

### Endpoint
/api/conversation/complete

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `messages` (array) - Required - The list of messages in the conversation.

### Request Example
{
  "example": "[{\"role\": \"user\", \"content\": \"Hello\"}, {\"role\": \"assistant\", \"content\": \"Hi there!\"}]";
}

### Response
#### Success Response (200)
- Streaming response of the chatbot's reply.
```

--------------------------------

### DELETE /api/v1/whatsapp/integrations/{id}

Source: https://chatbotkit.github.io/node-sdk

Deletes an existing WhatsApp integration. This endpoint removes the specified WhatsApp integration from the system.

```APIDOC
## DELETE /api/v1/whatsapp/integrations/{id}

### Description
Deletes the specified WhatsApp integration from the system.

### Method
DELETE

### Endpoint
/api/v1/whatsapp/integrations/{id}

### Path Parameters
- **id** (string) - Required - Unique identifier of the WhatsApp integration to delete

### Response
#### Success Response (204)
No content returned on successful deletion.

#### Response Example
{
  "message": "Integration deleted successfully"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.