---
title: Conversations
description: Conversations are interactive sessions where messages are exchanged between users and AI bots, enabling rich dialogue experiences with context awareness, memory, and intelligent responses.
category: Objects/Conversations
tags:
  - conversation
  - chat
  - messaging
index: 1
source:
  - pages/api/v1/conversation/create.js
  - pages/api/v1/conversation/list.js
  - pages/api/v1/conversation/[conversationId]/fetch.js
  - pages/api/v1/conversation/[conversationId]/receive.js
  - pages/api/v1/conversation/[conversationId]/update.js
  - pages/api/v1/conversation/[conversationId]/delete.js
  - pages/api/v1/conversation/[conversationId]/send.js
  - pages/api/v1/conversation/export.js
  - pages/api/v1/conversation/[conversationId]/compact.js
  - pages/api/v1/conversation/[conversationId]/complete.js
  - pages/api/v1/conversation/[conversationId]/initiate.js
  - pages/api/v1/conversation/[conversationId]/message/batch/create.js
---

Conversations are the foundation of interactive AI experiences in ChatBotKit,
providing a structured way to manage ongoing dialogues between users and AI
bots. Each conversation maintains its own context, history, and state, allowing
for natural, context-aware interactions that can span multiple messages and
sessions.

A conversation serves as a container for messages, maintaining the dialogue
history and configuration that determines how the AI responds. Conversations
can be associated with bots, contacts, tasks, and spaces, providing flexible
organization and management capabilities for different use cases.

## Creating Conversations

Creating a conversation initializes a new interactive session with specific
configuration options that control the AI's behavior. You can create a
conversation by referencing an existing bot (which provides the backstory,
model, and other settings) or by providing the configuration directly in the
request.

To create a conversation, send a POST request to the conversation creation
endpoint with your desired configuration:

```http
POST /api/v1/conversation/create
Content-Type: application/json

{
  "name": "Customer Support Session",
  "description": "Support conversation for user inquiry",
  "botId": "bot_abc123",
  "contactId": "contact_xyz789"
}
```

When creating a conversation, you can specify several key parameters:

- **name**: A descriptive name for the conversation (optional)
- **description**: Additional context about the conversation's purpose (optional)
- **botId**: Reference to an existing bot that provides configuration (optional)
- **contactId**: Link to a contact record for tracking user interactions (optional)
- **taskId**: Associate the conversation with a specific task (optional)
- **spaceId**: Organize the conversation within a space (optional)
- **messages**: Include initial messages to start the conversation (optional)

### Configuration Options

If you don't reference a bot, you can provide configuration directly:

- **backstory**: Instructions that define the AI's personality and behavior
- **model**: The language model to use (e.g., "gpt-4", "claude-3-5-sonnet")
- **datasetId**: Reference to a dataset for knowledge retrieval
- **skillsetId**: Reference to a skillset for extended capabilities
- **privacy**: Enable privacy mode to prevent data retention
- **moderation**: Enable content moderation for safety

### Including Initial Messages

You can initialize a conversation with messages by including a messages array:

```http
POST /api/v1/conversation/create
Content-Type: application/json

{
  "botId": "bot_abc123",
  "messages": [
    {
      "type": "user",
      "text": "Hello, I need help with my order"
    }
  ]
}
```

The API will return the created conversation ID and any processed messages,
allowing you to immediately continue the interaction.

**Important Notes:**

- Conversations inherit configuration from their associated bot if a botId is
  provided, but you can override specific settings by providing them directly
- Each conversation maintains its own message history and context
- Conversations can be organized using contacts, tasks, and spaces for
  different tracking and filtering needs
- Privacy mode prevents message content from being stored, useful for
  sensitive conversations

## Listing Conversations

Retrieving a list of conversations allows you to access and manage all
conversations associated with your account. The list endpoint provides
powerful filtering, pagination, and ordering capabilities to help you find
and organize conversations efficiently.

To list conversations, send a GET request to the list endpoint:

```http
GET /api/v1/conversation/list
```

This returns all conversations for the authenticated user, ordered by creation
date (most recent first) by default.

### Pagination and Ordering

The list endpoint supports cursor-based pagination for efficient retrieval of
large conversation sets:

```http
GET /api/v1/conversation/list?take=20&order=desc
```

Available parameters for pagination and ordering include:

- **cursor**: A pagination cursor from the previous response to fetch the next
  page of results
- **take**: Number of conversations to retrieve (default and maximum depend on
  your plan)
- **order**: Sort order, either "asc" (ascending) or "desc" (descending) by
  creation date

The response includes an items array containing conversation objects, each with
their ID, name, description, configuration, and timestamps. If there are more
results available, the response will include a cursor for fetching the next
page.

### Filtering by Relationships

You can filter conversations by their associated resources using query
parameters:

```http
GET /api/v1/conversation/list?botId=bot_abc123&contactId=contact_xyz789
```

Supported filter parameters include:

- **botId**: Filter by associated bot
- **contactId**: Filter by associated contact
- **taskId**: Filter by associated task

### Filtering by Metadata

Conversations with custom metadata can be filtered using meta queries. This
allows you to organize and retrieve conversations based on your own custom
fields and values.

### Response Format

Each conversation in the response includes:

- Core identifiers (id)
- Basic information (name, description)
- Resource relationships (botId, contactId, taskId, spaceId, datasetId,
  skillsetId)
- Configuration (backstory, model, privacy, moderation)
- Metadata (meta)
- Timestamps (createdAt, updatedAt)

**Best Practices:**

- Use pagination for large conversation sets to improve performance
- Apply filters to narrow results when searching for specific conversations
- Consider the order parameter based on your use case (recent conversations
  vs. oldest first)
- Store cursors for efficient navigation through paginated results

## Fetching a Conversation

Retrieving a specific conversation provides access to its complete
configuration, including all settings, relationships, and metadata. This is
useful when you need to inspect a conversation's current state, verify its
configuration, or retrieve details for display or modification.

To fetch a conversation, send a GET request with the conversation ID:

```http
GET /api/v1/conversation/{conversationId}/fetch
```

Replace `{conversationId}` with the actual ID of the conversation you want to
retrieve. The conversation ID is returned when you create a conversation or
can be obtained from the list endpoint.

### Response Details

The response includes the complete conversation object with all configuration
and relationship information, including references to associated resources,
conversation settings, and metadata.

### Use Cases

Fetching a conversation is commonly used to:

- Verify the current configuration before sending messages
- Display conversation details in a user interface
- Retrieve the conversation state for analytics or monitoring
- Check which bot, dataset, or skillset is associated
- Access custom metadata for application-specific logic

**Security Note:** You can only fetch conversations that belong to your
account. Attempting to access another user's conversation will result in an
authorization error.

## Receiving AI Responses

The receive endpoint enables you to request and receive AI-generated responses
within a conversation. This endpoint is essential for real-time chat interactions
where you need the AI to process the conversation history and generate an
appropriate response based on the context, backstory, and any configured
datasets or skillsets.

Unlike the send endpoint which adds user messages and triggers processing, the
receive endpoint focuses specifically on getting the AI's response, giving you
fine-grained control over the conversation flow and allowing you to customize
behavior with extensions and runtime configurations.

### Basic Usage

To receive an AI response, send a POST request to the receive endpoint. The
endpoint returns a streaming response containing the AI-generated message:

```http
POST /api/v1/conversation/{conversationId}/receive
Content-Type: application/json

{}
```

The response is delivered as a server-sent events (SSE) stream, allowing you
to process the AI's response as it is generated in real-time, providing a
smooth user experience with progressive text rendering.

### Extending Conversations with Runtime Configuration

One of the most powerful features of the receive endpoint is the ability to
extend and customize the conversation at runtime without modifying the
underlying bot or conversation configuration. You can provide extensions that
temporarily augment the conversation with additional context, data sources,
and capabilities:

```http
POST /api/v1/conversation/{conversationId}/receive
Content-Type: application/json

{
  "extensions": {
    "backstory": "Additional context: The user is asking about enterprise pricing.",
    "datasets": [
      {
        "name": "Pricing Information",
        "description": "Enterprise pricing and plans",
        "records": [
          {
            "text": "Enterprise plan starts at $500/month for 10 users",
            "meta": {}
          }
        ]
      }
    ],
    "skillsets": [
      {
        "name": "Sales Tools",
        "description": "Tools for sales conversations",
        "abilities": [
          {
            "name": "check_inventory",
            "description": "Check product inventory status",
            "instruction": "fetch https://api.example.com/inventory",
            "meta": {}
          }
        ]
      }
    ]
  }
}
```

### Extension Capabilities

The extensions object supports multiple types of runtime customizations:

**Backstory Extensions**: Add or override conversation instructions temporarily
without modifying the bot's base configuration. This is useful for providing
conversation-specific context, handling special cases, or adapting behavior
based on user attributes or session data.

**Dataset Extensions**: Inject additional knowledge into the conversation
dynamically. This allows you to provide context-specific information without
permanently adding it to your datasets, ideal for user-specific data,
session-specific context, or temporary information that may change frequently.

**Skillset Extensions**: Temporarily grant the AI access to additional
capabilities and tools for specific conversations. This enables you to provide
specialized functionality based on user permissions, conversation type, or
specific workflow requirements without permanently modifying the bot's skillset.

**Feature Extensions**: Enable or disable specific conversation features at
runtime, such as tool calling, code interpretation, or image understanding,
allowing fine-grained control over AI capabilities on a per-interaction basis.

### Function Calling

The receive endpoint supports function calling, enabling the AI to invoke
predefined functions during response generation. Define available functions
in your request:

```http
POST /api/v1/conversation/{conversationId}/receive
Content-Type: application/json

{
  "functions": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name"
          }
        },
        "required": ["location"]
      }
    }
  ]
}
```

When the AI determines that a function call is needed, the response stream
will include function call requests that your application should handle and
respond to, enabling dynamic, interactive conversations with external data
sources and services.

### Streaming Response Format

The receive endpoint returns responses as a streaming SSE (Server-Sent Events)
format, allowing you to process the AI's response progressively as it is
generated. This provides a better user experience compared to waiting for the
complete response.

The stream emits tagged events that indicate different types of responses:

- **result**: Contains chunks of the AI-generated text response
- **error**: Indicates an error occurred during processing
- **done**: Signals the end of the response stream

**Important Notes:**

- The receive endpoint is typically used in conjunction with the send endpoint
  in client-side applications
- Extensions are temporary and do not modify the underlying bot or conversation
  configuration
- Function responses must be handled by your application and fed back into the
  conversation
- The endpoint supports both API key authentication and conversation session
  tokens
- Response streaming requires proper SSE handling in your client application

**Security Considerations:**

When using extensions, be mindful of the data you inject into conversations.
Extensions allow powerful runtime customization but should be used carefully
to avoid exposing sensitive information or granting unintended capabilities.
Always validate and sanitize any user-provided data before including it in
extensions.

## Updating a Conversation

Modifying a conversation allows you to change its configuration, update
relationships, or adjust settings after creation. This is useful for adapting
the conversation's behavior, correcting information, or changing associations
as your application's needs evolve.

To update a conversation, send a POST request with the conversation ID and the
fields you want to modify:

```http
POST /api/v1/conversation/{conversationId}/update
Content-Type: application/json

{
  "name": "Updated Support Session",
  "backstory": "You are an expert technical support assistant...",
  "model": "gpt-4-turbo"
}
```

Replace `{conversationId}` with the actual ID of the conversation you want to
update. You only need to include the fields you want to change; all other
fields will remain unchanged.

### Updateable Fields

You can update the following conversation properties:

**Basic Information:**
- **name**: Change the conversation's display name
- **description**: Update the conversation's description

**Relationships:**
- **botId**: Change the associated bot (null to remove association)
- **contactId**: Change the associated contact (null to remove)
- **taskId**: Change the associated task (null to remove)
- **spaceId**: Change the associated space (null to remove)
- **datasetId**: Change the dataset for knowledge retrieval (null to remove)
- **skillsetId**: Change the skillset for capabilities (null to remove)

**Configuration:**
- **backstory**: Modify the AI's instructions and behavior
- **model**: Switch to a different language model
- **privacy**: Enable or disable privacy mode
- **moderation**: Enable or disable content moderation

**Metadata:**
- **meta**: Update or add custom metadata fields

### Example: Changing AI Behavior

You can modify the conversation's backstory to change how the AI responds:

```http
POST /api/v1/conversation/{conversationId}/update
Content-Type: application/json

{
  "backstory": "You are a specialized product expert who helps users find the perfect product. Be enthusiastic and knowledgeable about product features."
}
```

### Example: Switching Models

To use a different language model for better performance or cost optimization:

```http
POST /api/v1/conversation/{conversationId}/update
Content-Type: application/json

{
  "model": "claude-3-5-sonnet"
}
```

### Example: Updating Relationships

Associate the conversation with a different bot or dataset:

```http
POST /api/v1/conversation/{conversationId}/update
Content-Type: application/json

{
  "botId": "bot_new123",
  "datasetId": "dataset_xyz789"
}
```

### Metadata Management

The update operation intelligently merges metadata. If you provide a meta
object, it will merge with existing metadata rather than replacing it
entirely, preserving fields you don't explicitly update.

**Important Considerations:**

- Updating a conversation does not affect its existing message history
- Configuration changes apply to future messages in the conversation
- Changing the model or backstory will change how the AI responds going forward
- Updates are applied immediately and affect the next interaction
- You can only update conversations that belong to your account

## Deleting a Conversation

Deleting a conversation permanently removes it along with all associated
messages and data. This operation is irreversible and should be used carefully,
typically for cleanup, privacy compliance, or when a conversation is no longer
needed.

To delete a conversation, send a POST request with the conversation ID:

```http
POST /api/v1/conversation/{conversationId}/delete
Content-Type: application/json

{}
```

Replace `{conversationId}` with the actual ID of the conversation you want to
delete. The request body should be an empty JSON object.

### What Gets Deleted

When you delete a conversation, the following data is permanently removed:

- The conversation record itself
- All messages within the conversation
- Any associated metadata and configuration
- Message history and context
- File attachments and other associated data
- Related usage statistics for that conversation

### Response

Upon successful deletion, the API returns the ID of the deleted conversation:

```json
{
  "id": "conv_abc123"
}
```

This confirms which conversation was deleted and can be used for logging or
auditing purposes.

### Data Relationships

Deleting a conversation does not affect:

- The bot referenced by the conversation (if any)
- The contact associated with the conversation (if any)
- The task linked to the conversation (if any)
- Any datasets or skillsets referenced by the conversation
- Other conversations or resources in your account

Only the conversation itself and its direct contents (messages) are removed.

### Use Cases

Common scenarios for deleting conversations include:

- **Privacy Compliance**: Removing user data upon request (GDPR, CCPA)
- **Cleanup**: Removing test or obsolete conversations
- **Data Management**: Pruning old conversations to manage storage
- **Error Correction**: Removing conversations created by mistake
- **User-Initiated Deletion**: Allowing users to delete their conversation
  history

### Bulk Deletion

To delete multiple conversations, you'll need to call the delete endpoint for
each conversation individually. Consider implementing rate limiting and error
handling when performing bulk deletions to avoid overwhelming the API.

**Warning:** This operation is permanent and cannot be undone. Ensure you have
proper authorization checks and confirmation flows in your application before
allowing conversation deletion. Consider implementing a soft-delete pattern in
your application if you need the ability to recover deleted conversations.

**Security Note:** You can only delete conversations that belong to your
account. Attempting to delete another user's conversation will result in an
authorization error.

## Sending Messages to a Conversation

The send endpoint allows you to send a user message to a conversation and
add it to the conversation history. The message is processed and events may
be generated, but this endpoint does not produce an AI response. To receive
the AI's response, you need to call the receive route separately. This design
provides flexibility in controlling conversation flow and separating message
sending from response generation.

To send a message to a conversation, use a POST request with streaming support:

```http
POST /api/v1/conversation/{conversationId}/send
Content-Type: application/json

{
  "text": "What are your business hours?"
}
```

Replace `{conversationId}` with the actual ID of the conversation. The text
field is required and contains the user's message.

### How Send Works

The send endpoint adds your message to the conversation and processes it, but
does not generate an AI response. It may generate events and perform some
processing based on the message content, but to receive a message from the AI
agent, you need to call the receive route separately. This allows you to have
more control over the conversation flow and separate the message sending from
the response generation phases.

The response is delivered as a stream of JSON lines (JSONL), where each line
represents an event related to message processing.

### Advanced Features

The send endpoint supports several advanced features for enhanced
functionality:

**Function Calling:**

You can enable the AI to call functions during the conversation:

```http
POST /api/v1/conversation/{conversationId}/send
Content-Type: application/json

{
  "text": "What's the weather in San Francisco?",
  "functions": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name"
          }
        }
      },
      "result": {}
    }
  ]
}
```

When the AI determines a function call is appropriate, it will include function
call information in the streaming response. The result object is used to return
the function execution results.

**Extensions (Trusted Sessions Only):**

For trusted API sessions, you can temporarily extend the conversation's
capabilities:

- **extensions.backstory**: Add additional instructions for this message only
- **extensions.datasets**: Provide inline dataset records for context
- **extensions.skillsets**: Add temporary abilities for this interaction
- **extensions.features**: Enable specific features for this message

### Response Structure

The final result event includes the ID of the created message and usage
statistics for the operation.

### Message Flow

When you send a message:

1. Your message is added to the conversation history
2. The message is processed and events may be generated
3. The message ID is returned in the result event
4. No AI response is generated (use the receive route to get the AI response)
5. The conversation is ready for further interactions

### Best Practices

- **Handle Streaming Properly**: Implement proper streaming parsing in your
  client to handle JSONL responses
- **Handle Errors Gracefully**: Watch for error events in the stream and
  display appropriate messages
- **Respect Rate Limits**: Be aware of message and token rate limits for your
  account

**Important Notes:**

- The conversation maintains full message history for context
- The send operation adds your message to the conversation but does not
  generate an AI response
- To receive an AI response, call the receive route after sending
- Token usage is tracked and counted against your account limits
- Streaming responses can be interrupted if the connection is lost

## Exporting Conversations

The export endpoint enables you to retrieve conversations and their complete
message histories in bulk, supporting multiple output formats for different
use cases. This capability is essential for data analysis, backup purposes,
training data preparation, compliance requirements, and migrating conversations
between systems.

Unlike the standard list endpoint that returns basic conversation metadata,
the export endpoint provides comprehensive conversation data including full
message histories, making it ideal for scenarios where you need complete
conversation records rather than just metadata summaries.

### Supported Export Formats

The export endpoint supports three output formats, each optimized for different
use cases:

**JSON Format** (`application/json`): Returns conversations as a structured
JSON array, ideal for programmatic processing, API integrations, and when you
need to work with conversation data in JavaScript or other modern applications.
This format provides the most structured and easily parseable output.

**JSONL Format** (`application/jsonl`): Delivers conversations as JSON Lines
(newline-delimited JSON), where each line represents a single conversation.
This format is optimized for streaming large datasets, processing data
line-by-line, and integration with data pipeline tools that expect JSONL input.
It's particularly useful for large-scale exports that might exceed memory limits
if loaded entirely at once.

**CSV Format** (`text/csv`): Exports conversations in comma-separated values
format, ideal for spreadsheet applications, data analysis tools, and situations
where human readability and Excel compatibility are priorities. This format
flattens the conversation structure for easier tabular analysis.

### Basic Export Request

To export conversations, send a GET request with the desired format specified
in the Accept header:

```http
GET /api/v1/conversation/export
Accept: application/json
```

For JSONL format:

```http
GET /api/v1/conversation/export
Accept: application/jsonl
```

For CSV format:

```http
GET /api/v1/conversation/export
Accept: text/csv
```

### Pagination and Filtering

The export endpoint supports pagination and filtering to manage large datasets
efficiently:

**Cursor-based Pagination**: Use the `cursor` parameter to paginate through
large result sets. The response includes a cursor that you can use to fetch
the next page of results:

```http
GET /api/v1/conversation/export?cursor=eyJpZCI6ImNvbnZfYWJjMTIzIn0&take=100
Accept: application/json
```

**Ordering**: Control the sort order of exported conversations using the `order`
parameter. Use `desc` for most recent first (default) or `asc` for oldest first:

```http
GET /api/v1/conversation/export?order=asc&take=50
Accept: application/json
```

**Record Limits**: Specify the number of conversations to retrieve per request
using the `take` parameter. This helps manage export size and processing time:

```http
GET /api/v1/conversation/export?take=25
Accept: application/json
```

**Metadata Filtering**: Filter conversations by metadata using the `meta`
parameter with deep object notation. This allows you to export only conversations
matching specific criteria:

```http
GET /api/v1/conversation/export?meta[tier]=premium&meta[region]=us-east
Accept: application/json
```

### Export Data Structure

Each exported conversation includes comprehensive information:

- **Basic Information**: ID, name, description, creation and update timestamps
- **Configuration**: Bot settings, model configuration, privacy and moderation
  settings
- **Associations**: Contact ID, task ID, space ID for organizational relationships
- **Message History**: Complete conversation messages with type, text, entities,
  and metadata
- **Metadata**: Custom metadata fields for tracking and categorization

The exact structure depends on the output format, but all formats include
complete conversation data suitable for archival, analysis, or migration purposes.

### Use Cases

**Data Backup and Archival**: Regularly export conversations for backup purposes,
ensuring you have offline copies of important conversation data.

**Compliance and Audit**: Export conversation records for compliance reviews,
legal discovery, or audit requirements where complete conversation histories
are needed.

**Training Data Preparation**: Extract conversations to create training datasets
for fine-tuning language models or improving AI performance.

**Analytics and Reporting**: Export conversation data for analysis in business
intelligence tools, spreadsheets, or custom analytics platforms.

**System Migration**: Transfer conversations between systems, environments, or
accounts using the export functionality.

**Quality Assurance**: Review conversation quality by exporting samples for
manual review, analysis, or testing purposes.

### Performance Considerations

Exporting large volumes of conversations can be resource-intensive. Follow
these best practices:

**Use Pagination**: Don't attempt to export all conversations at once. Use the
`take` parameter to limit export size and process data in manageable chunks.

**Implement Incremental Exports**: Export conversations periodically (e.g.,
daily) rather than attempting to export your entire history at once.

**Choose Appropriate Formats**: Use JSONL for large exports to enable streaming
and line-by-line processing rather than loading everything into memory.

**Schedule Off-Peak Exports**: Run large export operations during off-peak
hours to minimize impact on system performance.

**Filter Effectively**: Use metadata filters to export only the conversations
you actually need rather than exporting everything and filtering locally.

**Important Notes:**

- Exports include all messages in each conversation, which can result in large
  data volumes for conversations with extensive histories
- The default sort order is newest conversations first (desc), which is typically
  most useful for incremental exports
- CSV format may not preserve all data structures perfectly due to flattening;
  use JSON or JSONL for complete data fidelity
- Exported data includes sensitive information; ensure proper security measures
  when storing or transmitting exports
- Large exports may take significant time to complete; implement appropriate
  timeout handling in your client code

## Compacting a Conversation

As conversations grow longer, they can accumulate many messages that slow
down processing and increase token usage for AI completions. The compact
endpoint addresses this by summarizing all messages since the last checkpoint
into a single concise checkpoint message. This reduces context size while
preserving the essential meaning and history of the conversation.

To compact a conversation, send a POST request:

```http
POST /api/v1/conversation/{conversationId}/compact
Content-Type: application/json
```

The request body is not required. The operation is safe to call at any time
during a conversation.

### How Compaction Works

When you call the compact endpoint, ChatBotKit performs the following steps:

1. **Checkpoint Detection**: Checks whether a previous checkpoint message
   exists. If one exists, only the messages created after that checkpoint
   are included in the next compaction, avoiding redundant summarization.

2. **Message Summarization**: Sends the accumulated messages to the AI to
   produce a concise summary that captures the key points, decisions, and
   context from the conversation so far.

3. **Checkpoint Creation**: Stores the generated summary as a new checkpoint
   message in the conversation. Future completions and compactions will
   reference this checkpoint as the condensed history.

### Response

A successful response returns the ID of the newly created checkpoint message.
If there are no messages to compact (empty conversation or nothing since the
last checkpoint), the response returns the conversation ID instead and no
checkpoint is written:

```javascript
// When a checkpoint was created:
{ "id": "msg_xxxxxxxxxxxxxxxx" }

// When there was nothing to compact:
{ "id": "conv_xxxxxxxxxxxxxxxx" }
```

### When to Compact

Compaction is most useful in these scenarios:

- **Long-running conversations**: When a conversation has accumulated many
  turns and you want to reduce the context window used for subsequent
  completions.

- **Before archiving**: Compact before storing a conversation to preserve
  its key points in a space-efficient form.

- **Periodic maintenance**: Schedule periodic compaction for always-on
  assistant bots that handle very long sessions.

- **Cost optimization**: Reducing message history lowers the number of
  tokens processed in future completions, which directly reduces API usage
  costs.

### Idempotency and Safety

Compaction is safe to call multiple times. If there are no new messages
since the last checkpoint, the operation is a no-op and returns immediately.
The existing conversation history and any previously created checkpoints
are never deleted or modified by this operation.

## Complete Conversation Interaction

The complete endpoint provides a full round-trip conversation interaction,
sending a user message and receiving the AI's complete response through a
streaming connection. Unlike the send endpoint which only sends the message,
complete handles both sending and receiving in a single operation, making it
ideal for traditional request-response chat patterns.

To complete a conversation interaction, send a POST request. The API supports
both streaming and non-streaming responses. For streaming, include the
`Accept: application/jsonl` header; otherwise, the response defaults to
non-streaming JSON:

```http
POST /api/v1/conversation/{conversationId}/complete
Content-Type: application/json
Accept: application/jsonl

{
  "text": "Can you explain how your pricing works?"
}
```

Replace `{conversationId}` with the actual conversation ID. The text field
contains the user's message when you want to send a new turn. Omit it when
you want to continue receiving from the existing conversation state.

### How Complete Works

The complete endpoint orchestrates a conversation turn and can optionally
continue an existing one:

1. **Optional Send Phase**: Your message is added to the conversation when
   `text` is provided
2. **Processing**: The AI analyzes the conversation with full context
3. **Receive Phase**: The AI generates and streams its response
4. **Result**: The response is saved to the conversation history

When `text` is provided, this two-phase approach ensures that both the user's
message and the AI's response are properly recorded and contribute to the
ongoing conversation context. When `text` is omitted, the endpoint skips the
send phase and resumes from the current conversation state.

### Streaming Response Events

The complete endpoint delivers a stream of events as JSONL (JSON Lines), with
three main event types:

**send_result Event:**

Emitted after the user's message is processed, when `text` is provided,
containing:
- **id**: The ID of the user's message
- **text**: The user's message text
- **entities**: Extracted entities from the user's message
- **usage**: Token usage for processing the user's message

**receive_result Event:**

Emitted after the AI's response is complete, containing:
- **id**: The ID of the AI's response message
- **text**: The AI's complete response text
- **usage**: Cumulative token usage for the entire interaction

**Streaming Tokens:**

Between send_result and receive_result, the AI's response is streamed as
individual tokens (word pieces), allowing you to display the response
incrementally as it's generated.

### Advanced Features

The complete endpoint supports advanced features for enhanced functionality:

**Function Calling:**

Enable the AI to call functions during the interaction:

```http
POST /api/v1/conversation/{conversationId}/complete
Content-Type: application/json

{
  "text": "What's my account balance?",
  "functions": [
    {
      "name": "get_account_balance",
      "description": "Retrieve current account balance",
      "parameters": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string",
            "description": "Account identifier"
          }
        }
      }
    }
  ]
}
```

**Extensions (Trusted Sessions Only):**

For API sessions with trusted status, you can extend conversation capabilities
for a single interaction:

- **extensions.backstory**: Additional instructions for this specific
  interaction
- **extensions.datasets**: Inline dataset records to provide context
- **extensions.skillsets**: Temporary abilities for this message
- **extensions.features**: Enable specific features for this interaction

### When to Use Complete vs Send

**Use Complete When:**
- You want a traditional request-response chat pattern
- You need both messages saved in a single operation
- You want separated send and receive events in the stream
- Your application requires explicit confirmation of both phases

**Use Send When:**
- You only need to send a message without waiting for a response
- You're implementing a fire-and-forget pattern
- You have a different mechanism for receiving responses

### Error Handling

The complete endpoint includes comprehensive error handling. If an error occurs
during either the send or receive phase, an error event will be included in
the stream with details about what went wrong. Your client should handle these
error events gracefully and provide appropriate feedback to users.

### Performance Considerations

- The complete operation can take up to 800 seconds for long-running
  generations
- Token streaming provides immediate feedback while generation continues
- Both send and receive phases count toward token usage limits
- Rate limits apply to both message count and token usage

**Best Practices:**

- Implement proper JSONL streaming parsing in your client
- Handle all three event types (send_result, receive_result, and tokens)
- Display tokens incrementally for better user experience
- Watch for error events and handle them appropriately
- Store message IDs for reference and conversation management
- Monitor usage data to track conversation costs

## Execution Limits

For agentic conversations that involve function calling or iterative
reasoning, you can control execution bounds using the `limits` parameter.
This prevents runaway conversations and helps manage resource consumption.

The limits object accepts three optional properties:

- **iterations**: Maximum number of agentic iterations (tool call cycles)
- **continuations**: Maximum number of model continuations after stop
  conditions
- **calls**: Maximum total function/tool calls allowed

```http
POST /api/v1/conversation/{conversationId}/complete
Content-Type: application/json

{
  "text": "Research competitors and create a comparison table",
  "limits": {
    "iterations": 5,
    "calls": 10
  }
}
```

When a limit is reached, the response's `end.reason` will be `iteration`,
allowing your application to detect bounded processing.

## Completion End Reasons

Every completion returns an `end` object explaining why processing finished.
The `end.reason` field contains one of:

- **stop**: Normal completion - the model finished its response naturally
- **length**: Response truncated due to token limits
- **activity**: The model invoked a function or tool during processing
- **error**: An error occurred during processing
- **iteration**: Hit configured execution limits

**Example Response:**

```json
{
  "id": "msg_xyz789",
  "text": "Based on your order history...",
  "usage": {
    "token": 850
  },
  "end": {
    "reason": "stop"
  }
}
```

**Best Practices:**

- Always check `end.reason` for programmatic response handling
- Handle `length` truncation for long-form content generation
- Monitor `iteration` to tune your limits appropriately
- Use `stop` as the expected success case in your logic

## Initiating Bot Messages

The conversation initiate endpoint allows you to programmatically generate
bot responses based on provided text, enabling advanced automation scenarios
where the AI needs to respond to extracted information, processed data, or
system-generated content rather than direct user input. This functionality
is particularly useful for integrations where you're processing messages
through external systems before presenting them to the AI, or when you want
the bot to respond to structured data that's been formatted into natural
language.

Unlike the standard send endpoint which expects user messages, the initiate
endpoint treats the provided text as context that should trigger a bot
response. This allows you to create sophisticated workflows where data from
various sources (forms, APIs, databases, sensors) is transformed into
conversational context that the bot can meaningfully respond to, maintaining
the natural dialogue flow while working with programmatically generated
content.

The endpoint supports entity extraction, allowing you to annotate specific
portions of the input text with entity information that the AI can leverage
for more accurate and contextually appropriate responses. This is especially
valuable when dealing with structured data that contains important entities
like dates, names, locations, or custom business-specific entities that
should be preserved and understood by the conversational AI.

```http
POST /api/v1/conversation/{conversationId}/initiate
Content-Type: application/json

{
  "text": "The customer's order #12345 shipped yesterday to New York and is expected to arrive on Friday",
  "entities": [
    {
      "begin": 18,
      "end": 23
    },
    {
      "begin": 50,
      "end": 58
    }
  ]
}
```

The response streams back the bot's generated reply in real-time, maintaining
the same streaming format as other conversation endpoints. The bot will
process the provided text as context and generate an appropriate response
based on its configuration, backstory, and any connected knowledge sources
or tools.

**Use Cases**:

- Processing form submissions through AI before presenting to users
- Converting structured data into conversational responses
- Integrating with external systems that generate context for bot responses
- Creating automated customer service workflows with data enrichment
- Building intelligent notification systems with contextual AI responses

**Important Notes**:

- The provided text is treated as contextual information for bot response generation
- Entity annotations help the AI understand and preserve important information
- The endpoint maintains conversation context and history like standard message endpoints
- Responses are streamed in real-time for optimal user experience
- This endpoint is designed for integration scenarios, not direct user messaging

## Batch Creating Messages

The batch message creation endpoint enables efficient addition of multiple
messages to a conversation in a single atomic operation, providing significant
performance advantages and transactional guarantees when working with
conversation history imports, data migrations, chat transcript ingestion, or
programmatic conversation initialization scenarios. This functionality is
essential for building robust integrations that need to efficiently populate
conversations with historical context, migrate chat data from other platforms,
or initialize conversations with pre-existing dialogue history.

Unlike creating messages individually through repeated single-message API
calls, the batch endpoint processes all messages together, reducing network
overhead, minimizing database round trips, and ensuring consistent ordering
of messages within the conversation. This approach is particularly valuable
when dealing with data import scenarios where maintaining message sequence
and timestamp accuracy is critical for conversation coherence and historical
accuracy.

The batch creation process supports up to 100 messages per request, allowing
you to efficiently populate conversations with substantial dialogue history
while maintaining system performance and reliability. Each message in the
batch can have its own type (user, bot, context, system), text content,
entities, metadata, and optional identifiers for maintaining references to
source systems during migration or import operations.

```http
POST /api/v1/conversation/{conversationId}/message/batch/create
Content-Type: application/json

{
  "items": [
    {
      "type": "user",
      "text": "Hello, I need help with my order",
      "meta": {
        "originalTimestamp": "2024-01-15T10:30:00Z",
        "sourceSystem": "zendesk"
      }
    },
    {
      "type": "bot",
      "text": "I'd be happy to help you with your order. Can you provide your order number?",
      "meta": {
        "originalTimestamp": "2024-01-15T10:30:15Z",
        "sourceSystem": "zendesk"
      }
    },
    {
      "type": "user",
      "text": "Sure, it's order #12345",
      "meta": {
        "originalTimestamp": "2024-01-15T10:30:45Z",
        "sourceSystem": "zendesk"
      }
    }
  ]
}
```

### Message Structure

Each message in the batch must include:

- **type**: Message type (user, bot, context, system, instruction, tool_request, tool_response)
- **text**: The message content (required, supports markdown and rich text)
- **entities**: Optional array of detected entities (names, dates, locations, etc.)
- **meta**: Custom metadata for storing additional context or source system references
- **id**: Optional external identifier for maintaining references during migrations

### Use Cases

**Chat History Import**: Migrate existing chat transcripts from legacy
systems, customer support platforms, or other conversational AI solutions
into ChatBotKit conversations while preserving message order, timestamps,
and contextual information.

**Conversation Initialization**: Set up conversations with pre-existing
context by adding historical messages that provide the AI with necessary
background information before the user's current inquiry, enabling more
contextually aware and relevant responses.

**Testing and Development**: Quickly create test conversations with specific
dialogue patterns for testing bot behavior, training conversational flows,
or demonstrating capabilities in development and staging environments.

**Data Migration**: Transfer conversation data between systems, accounts, or
organizational units while maintaining message integrity, sequence, and
associated metadata for compliance and historical accuracy.

**Bulk Operations**: Process large volumes of messages efficiently when
importing transcripts, synchronizing external systems, or performing data
transformations that generate multiple related messages.

### Performance and Limitations

- Maximum of 100 messages per batch request
- Messages are processed atomically - all succeed or all fail
- Message ordering within the batch is preserved in the conversation
- Each message counts toward account usage limits
- PII detection and content moderation apply to all messages in the batch
- Timestamps are automatically assigned based on creation time unless preserved in metadata

**Best Practices**:

- Use batch creation for 10+ messages to realize performance benefits
- Include source system identifiers in metadata for traceability
- Preserve original timestamps in metadata when importing historical data
- Order messages chronologically in the batch array for natural conversation flow
- Consider breaking very large imports into multiple batch requests
- Validate message content and structure before batch submission to avoid rollback

**Important Notes**:

- Batch creation is a write operation that cannot be undone
- Messages appear immediately in the conversation after successful creation
- The endpoint does not trigger automated bot responses (use send endpoint for that)
- Entity detection runs on all message text during batch processing
- Messages are subject to content moderation if enabled on the conversation