Skip to main content
POST
Send a customer message to an assistant
Send a customer message to a configured assistant and receive its public reply, tags and handoff result. Your application delivers the reply and handles human routing when requested.

Requirements

  • Use a tenant API key with assistant:write or an equivalent write scope.
  • Configure your assistant for implementation version v7 or v8 and a model that supports synchronous text responses.
  • Send JSON and use a stable conversation ID for each customer conversation.

Request

POST /api/v1/assistant/tenants/{tenantId}/bots/{botId}/messages Use Authorization: Bearer <apiKey> for the path tenant and Content-Type: application/json. The intended permission is tenant-wide assistant:write; the existing assistant:*, assistant:bots.write and assistant:bots.* scope conventions also permit this operation.
The complete JSON body is limited to 10 MiB (10,485,760 bytes). Required strings and supplied message IDs cannot contain only whitespace; original values are preserved. Tenant and bot path IDs cannot be empty, contain /, or be . or ... Business fields have no accepted-key allowlist and are not stripped. When business root input and context contain the same key, context wins. Use the bot’s configured input mapping to make values prompt-visible.

Success response

HTTP 200 returns the assistant result:
state is active or handed_off. message is public plain text and can be partial or an empty string. Visible assistant text associated with tool calls is retained; raw tool metadata and empty stubs are excluded. Tags are deduplicated and include c7o. A newly completed handoff returns handoff: true, state: "handed_off", the c7o_handoff tag, screenPopComment and object scriptResult. A later call to a conversation whose handoff is already completed returns message: null without repeating customer-message or handoff-script processing. Configured CRM/external handoff behavior follows your assistant configuration. For example, a newly completed handoff can return:
screenPopComment is a plain-text conversation note without the transcript. scriptResult contains your configured Ticket Fields Script’s JSON result, so its business fields depend on your script. A missing script returns {}.

Response budget and retries

Each assistant processing call has a default 55-second response budget. HTTP body parsing and authentication happen before this budget starts. A timeout ends your response wait and returns HTTP 504; underlying work may continue, including provider effects and persistence. There is no later result through the timed-out response and no HTTP history/polling endpoint in this API phase. Retries may process a message again, even when messageId is repeated. Concurrent same-instance requests use native supersession and can yield partial/empty replies; separate instances can both process. Clients should choose their retry and fallback policy with these semantics in mind.

Errors

Authentication, validation and assistant processing errors use { "code": "...", "message": "..." }. Unexpected host failures return HTTP 500 with { "message": "Internal Server Error" } and no code. Malformed JSON returns 400 BadRequest with Request body must contain valid JSON, without echoing your input. Oversized JSON and unsupported charset/content encoding retain the generic 500 response. Assistant processing errors also preserve available conversationId, messageId and action. Messages are sanitized; provider exceptions, stack traces and internal descriptions are not exposed. Assistant processing errors with HTTP status 500 or above include action: "handoff" for your application’s human-routing fallback, for example:
Machine-readable contract: Platform API OpenAPI.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

tenantId
string
required

Tenant-scoped path ID; must be nonempty, cannot contain slash, and cannot be . or .. .

Minimum string length: 1
botId
string
required

Tenant-scoped path ID; must be nonempty, cannot contain slash, and cannot be . or .. .

Minimum string length: 1

Body

application/json

All other root fields are arbitrary business input and are preserved. No business-key allowlist.

conversationId
string
required

Must contain non-whitespace text; original value is preserved.

Minimum string length: 1
Pattern: \S
message
string
required

Must contain non-whitespace text; original value is preserved.

Minimum string length: 1
Pattern: \S
messageId
string | null

Nonempty caller message ID; omitted/null generates an ID.

Minimum string length: 1
Pattern: \S
context
object

Arbitrary business fields; context wins over duplicate business root keys. Null/arrays are invalid.

Response

Public assistant reply, tags and handoff outcome; partial/empty text and retained-handoff null text are valid.

conversationId
string
required
messageId
string
required
state
enum<string>
required
Available options:
active,
handed_off
handoff
boolean
required
message
string | null
required

Public plain text, possibly partial/empty; null for a retained completed handoff.

tags
string[]
required

Includes c7o; completed handoff includes c7o_handoff.

screenPopComment
string

Present on a newly processed handoff.

scriptResult
object

Ticket Fields Script JSON result on a newly processed handoff.