Chat
Send a query
Send a message to an API channel and receive JSON or an SSE stream.
POST
/v2/chatAuthenticate with the channel API key and send query text or uploaded attachments. The channel determines which agent receives the message.
Conversation and retry behavior
To continue a conversation, include the returned data.metadata.conversation_id in your next request.
external_message_id makes retries safe: resend the same ID and body to retrieve the original result. Only stream may change. The channel chooses the agent; no agent_id is needed. A platform API key cannot authenticate this request.
Streaming explains events and reconnection. The integration guide covers contact fields, file uploads, per-request instructions and knowledge selection.
Authentication
AuthorizationstringheaderrequiredChannel API key from Deploy → API in your agent dashboard. The channel determines the agent. Platform API keys are not accepted for query.
Authenticate with a Bearer token in this format: Bearer <token>
Header Parameters
last-event-idstring | nullRequest bodyrequired
Additional properties
falsequerystringMessage text to send to the agent. Provide text or at least one uploaded attachment.
Default:
attachmentsobject[]Previously uploaded attachments. Include at most 5 files.
Maximum items:
5Show child attributes
blob_idintegerrequiredExclusive minimum:
0Additional properties
falseconversation_idstring | nullConversation ID from an earlier response. Omit it to start a new conversation.
Format:
uuidexternal_message_idstring | nullYour unique message ID. Reuse the same ID and body when retrying a request.
Maximum length:
255Minimum length:
1contactobject | nullContact details to associate with this conversation.
Show child attributes
identifierstring | nullMaximum length:
255namestring | nullMaximum length:
255first_namestring | nullMaximum length:
255last_namestring | nullMaximum length:
255emailstring | nullFormat:
emailphone_numberstring | nullMaximum length:
64localestring | nullMaximum length:
32custom_attributesobjectAdditional properties
Additional properties
falsesystem_promptstring | nullAdditional instructions for this request.
knowledge_base_idsstring[] | nullLimit this request to the selected knowledge bases.
Maximum items:
100streambooleanUse true to receive Server-Sent Events. The default is false for a JSON response.
Default:
falseResponse
Successful Response
dataobjectrequiredShow child attributes
messageobject | nullrequiredShow child attributes
idstringrequiredFormat:
uuidroleenum<string>requiredAvailable options:
userassistantoperatorpartsobject[]requiredanyOf
Show child attributes
idstringrequiredFormat:
uuidtypeenum<string>Default:
texttextstringrequiredShow child attributes
idstringrequiredFormat:
uuidclient_idstringDefault:
positionintegerrequiredtypeenum<string>requiredAvailable options:
attachmentvoiceupdated_atstringrequiredFormat:
date-timecontent_attributesobjectrequiredShow child attributes
schema_versionenum<integer>Default:
1kindenum<string>requiredAvailable options:
imagevoicefilefilenamestringrequiredstatusenum<string>requiredAvailable options:
pendingprocessingreadyfailedrejectedcontent_typestring | nullbyte_sizeinteger | nullwidthinteger | nullheightinteger | nullduration_secondsnumber | nullerror_codestring | nulltranscriptionobject | nulldelivery_statusstring | nulldownload_urlstring | nullexpires_ininteger | nullAdditional properties
falsemetadataobjectrequiredShow child attributes
conversation_statusstringrequiredbot_activebooleanrequiredhandoff_statusenum<string>requiredAvailable options:
not_requestedpendingoperator_ownedconversation_idstringrequiredFormat:
uuiduser_message_idstringrequiredFormat:
uuidexternal_message_idstringrequiredcontact_idstringrequiredFormat:
uuidfinish_reasonenum<string>requiredAvailable options:
completedsuppressedfailedcancelledusageobjectShow child attributes
creditsintegerDefault:
0