---
title: "Complete the next message in a conversation"
method: POST
path: "/conversation/complete"
tags: ["Conversation"]
---

# Complete the next message in a conversation

`POST /conversation/complete`

## Request

- Base URL: `https://api.chatbotkit.com/api/v1`
- URL: `https://api.chatbotkit.com/api/v1/conversation/complete`
- Auth: HTTP bearer

## Headers

- `X-Timezone` string

## Request body

- union
  - object: A bot configuration that can be applied without a dedicated bot instance.
    - `botId` string, nullable: The ID of the bot this configuration is using
    - `messages` Message[], required: An array of messages to be added to the conversation
      - `type` 'user' | 'bot' | 'reasoning' | 'context' | 'instruction' | 'backstory' | 'activity' | 'checkpoint', required: The type of the message
      - `text` string, required: The text of the message
      - `meta` Meta: Meta data information
    - `attachments` object[]: An array of attachments to be added to the conversation
      - `url` string: The URL of the attachment
    - `contactId` union: The contact ID to associate with this conversation
      - string: An existing contact ID
      - object: A contact object to create or retrieve a trusted contact
        - `fingerprint` string, required: A unique fingerprint to identify the contact
        - `name` string: The name of the contact
        - `description` string: A description of the contact
        - `email` string: The email address of the contact
        - `phone` string: The phone number of the contact
        - `nick` string: A nickname for the contact
        - `meta` object: Additional metadata for the contact
    - `functions` object[]: An array of functions to be added to the conversation
      - `name` string, required: The name of the function (must be a valid JS identifier, max 64 chars)
      - `description` string, required: The description of the function
      - `parameters` object, required: JSON Schema definition for the function parameters
        - `type` 'object', required: The schema type, must be "object"
        - `properties` object, required: Object property definitions
        - `required` string[]: Required property names
      - `result` union: The result of the function execution
        - object
          - `data` unknown, required
        - object
          - `channel` string, required: The channel for streaming function results
      - `call` object: Configuration for when this function should be automatically called
        - `start` boolean: If true, this function will be force-called at the start of the conversation
        - `end` boolean: If true, this function will be force-called at the end of the conversation
    - `extensions` ExtensionsDefinition: Extensions to enhance the bot's capabilities
      - `backstory` string: Additional backstory for the bot
      - `datasets` object[]: Inline datasets to provide additional context
        - `name` string, nullable: The name of the dataset
        - `description` string, nullable: The description of the dataset
        - `records` object[], required: The records in the dataset
          - `text` string, required: The text content of the record
          - `meta` object: Additional metadata for the record
      - `skillsets` object[]: Inline skillsets to provide additional abilities
        - `name` string, nullable: The name of the skillset
        - `description` string, nullable: The description of the skillset
        - `abilities` object[], required: The abilities in the skillset
          - `name` string, required: The name of the ability
          - `description` string, required: The description of the ability
          - `instruction` string, required: The instruction for the ability
          - `linkedSecretId` string: Optional secret ID for the ability
          - `linkedSpaceId` string: Optional space ID for the ability
          - `meta` object: Additional metadata for the ability
      - `features` object[]: Feature flags to enable specific bot capabilities
        - `name` string, required: The name of the feature to enable
        - `options` object: Optional configuration options for the feature
    - `limits` ExecutionLimits: Execution limits to control conversation processing bounds
      - `iterations` integer: Maximum number of agentic iterations. Controls how many times the model can iterate through tool calls and responses.
      - `continuations` integer: Maximum number of model continuations. Controls how many times the model can continue generating after reaching a stop condition.
      - `calls` integer: Maximum number of function/tool calls. Controls how many total function calls can be made during the conversation.
  - object: A bot configuration that can be applied without a dedicated bot instance.
    - `model` string: A model definition
    - `backstory` string, nullable: The backstory this configuration is using
    - `datasetId` string, nullable: The id of the dataset this configuration is using
    - `skillsetId` string, nullable: The id of the skillset this configuration is using
    - `privacy` boolean: The privacy flag for this configuration
    - `moderation` boolean: The moderation flag for this configuration
    - `messages` Message[], required: An array of messages to be added to the conversation
      - `type` 'user' | 'bot' | 'reasoning' | 'context' | 'instruction' | 'backstory' | 'activity' | 'checkpoint', required: The type of the message
      - `text` string, required: The text of the message
      - `meta` Meta: Meta data information
    - `attachments` object[]: An array of attachments to be added to the conversation
      - `url` string: The URL of the attachment
    - `contactId` union: The contact ID to associate with this conversation
      - string: An existing contact ID
      - object: A contact object to create or retrieve a trusted contact
        - `fingerprint` string, required: A unique fingerprint to identify the contact
        - `name` string: The name of the contact
        - `description` string: A description of the contact
        - `email` string: The email address of the contact
        - `phone` string: The phone number of the contact
        - `nick` string: A nickname for the contact
        - `meta` object: Additional metadata for the contact
    - `functions` object[]: An array of functions to be added to the conversation
      - `name` string, required: The name of the function (must be a valid JS identifier, max 64 chars)
      - `description` string, required: The description of the function
      - `parameters` object, required: JSON Schema definition for the function parameters
        - `type` 'object', required: The schema type, must be "object"
        - `properties` object, required: Object property definitions
        - `required` string[]: Required property names
      - `result` union: The result of the function execution
        - object
          - `data` unknown, required
        - object
          - `channel` string, required: The channel for streaming function results
      - `call` object: Configuration for when this function should be automatically called
        - `start` boolean: If true, this function will be force-called at the start of the conversation
        - `end` boolean: If true, this function will be force-called at the end of the conversation
    - `extensions` ExtensionsDefinition: Extensions to enhance the bot's capabilities
      - `backstory` string: Additional backstory for the bot
      - `datasets` object[]: Inline datasets to provide additional context
        - `name` string, nullable: The name of the dataset
        - `description` string, nullable: The description of the dataset
        - `records` object[], required: The records in the dataset
          - `text` string, required: The text content of the record
          - `meta` object: Additional metadata for the record
      - `skillsets` object[]: Inline skillsets to provide additional abilities
        - `name` string, nullable: The name of the skillset
        - `description` string, nullable: The description of the skillset
        - `abilities` object[], required: The abilities in the skillset
          - `name` string, required: The name of the ability
          - `description` string, required: The description of the ability
          - `instruction` string, required: The instruction for the ability
          - `linkedSecretId` string: Optional secret ID for the ability
          - `linkedSpaceId` string: Optional space ID for the ability
          - `meta` object: Additional metadata for the ability
      - `features` object[]: Feature flags to enable specific bot capabilities
        - `name` string, required: The name of the feature to enable
        - `options` object: Optional configuration options for the feature
    - `limits` ExecutionLimits: Execution limits to control conversation processing bounds
      - `iterations` integer: Maximum number of agentic iterations. Controls how many times the model can iterate through tool calls and responses.
      - `continuations` integer: Maximum number of model continuations. Controls how many times the model can continue generating after reaching a stop condition.
      - `calls` integer: Maximum number of function/tool calls. Controls how many total function calls can be made during the conversation.

## Response `200`

The next message in the conversation completed successfully

- object
  - `text` string, required: The text of the message received
  - `usage` Usage, required: Usage information
    - `token` number, required: The tokens used in this exchange
  - `end` CompleteEnd, required: Information about why the completion ended
    - `reason` 'length' | 'stop' | 'activity' | 'abort' | 'error' | 'iteration', required: The reason why the completion ended

## Other responses

- `default`: An error response

---

[API](https://skmtc.dev/chatbotkit/apis/cbk-api.md) · [All operations](https://skmtc.dev/chatbotkit/apis/cbk-api/llms.txt) · [OpenAPI document](https://skmtc.dev/chatbotkit/apis/cbk-api/revisions/13d250576136?raw)