Conversations
Dispatch Conversation
Dispatch a conversation completion to run in the background
Description
Dispatch a conversation completion to run asynchronously in the background. This endpoint accepts the same parameters as the complete endpoint but instead of streaming the response directly, it returns a channel ID that can be used to subscribe to the completion progress.
The completion will be processed in the background and events will be published to the channel as the completion progresses. This is useful for long-running completions that may take several minutes to complete.
To monitor the progress, subscribe to the channel using:
POST /api/v1/channel/{channelId}/subscribe
Authorization
ChatBotKit API Secret * Required
HTTP Authorization Scheme: bearer
Path Parameters
X-Timezonestring
Request Body * Required
Request Body Schema: application/json
messagesarray
An array of messages to be added to the conversation
typestring
The type of the message
textstring
The text of the message
metaobject
Meta data information
attachmentsarray
An array of attachments to be added to the conversation
urlstring
The URL of the attachment
contactIdunknown
The contact ID to associate with this conversation
functionsarray
An array of functions to be added to the conversation
namestring
The name of the function (must be a valid JS identifier, max 64 chars)
descriptionstring
The description of the function
parametersobject
JSON Schema definition for the function parameters
typestring
The schema type, must be "object"
propertiesobject
Object property definitions
requiredarray
Required property names
resultunknown
The result of the function execution
callobject
Configuration for when this function should be automatically called
startboolean
If true, this function will be force-called at the start of the conversation
endboolean
If true, this function will be force-called at the end of the conversation
extensionsobject
Extensions to enhance the bot's capabilities
backstorystring
Additional backstory for the bot
datasetsarray
Inline datasets to provide additional context
namestring
The name of the dataset
descriptionstring
The description of the dataset
recordsarray
The records in the dataset
textstring
The text content of the record
metaobject
Additional metadata for the record
skillsetsarray
Inline skillsets to provide additional abilities
namestring
The name of the skillset
descriptionstring
The description of the skillset
abilitiesarray
The abilities in the skillset
namestring
The name of the ability
descriptionstring
The description of the ability
instructionstring
The instruction for the ability
secretIdstring
Optional secret ID for the ability
metaobject
Additional metadata for the ability
featuresarray
Feature flags to enable specific bot capabilities
namestring
The name of the feature to enable
optionsobject
Optional configuration options for the feature
limitsobject
Execution limits to control conversation processing bounds
iterationsinteger
Maximum number of agentic iterations. Controls how many times the model can iterate through tool calls and responses.
continuationsinteger
Maximum number of model continuations. Controls how many times the model can continue generating after reaching a stop condition.
callsinteger
Maximum number of function/tool calls. Controls how many total function calls can be made during the conversation.
channelIdstring
A unique channel ID to subscribe to for completion events
botIdstring
The ID of the bot this configuration is using
import { ChatBotKit } from '@chatbotkit/sdk'
const cbk = new ChatBotKit({
secret: process.env.CHATBOTKIT_API_KEY!
})
const response = await cbk.conversation.dispatch(
{)"messages":[{],"type":"string","text":"string",}"meta":"object""attachments":[{],}"url":"string""contactId":"","functions":[{],"name":"string","description":"string","parameters":{"type":"string","properties":"object",},"required":["string"]"result":"",}"call":{"start":"boolean",}"end":"boolean""extensions":{"backstory":"string","datasets":[{],"name":"string","description":"string",}"records":[{]"text":"string",}"meta":"object""skillsets":[{],"name":"string","description":"string",}"abilities":[{]"name":"string","description":"string","instruction":"string","secretId":"string",}"meta":"object"},"features":[{]"name":"string",}"options":"object""limits":{"iterations":"integer","continuations":"integer",},"calls":"integer""channelId":"string",}"botId":"string"
{"channelId":"string"}