> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crescendo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send an Assistant message

> Send a customer message and receive an assistant reply, tags and handoff result.

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.

```json theme={null}
{
  "conversationId": "customer-chat-42",
  "message": "Where is my order?",
  "messageId": "customer-message-8",
  "orderNumber": "ORDER-123",
  "context": {
    "locale": "en",
    "customer": { "loyaltyTier": "gold" }
  }
}
```

| Field | Required | Meaning |
| - | - | - |
| `conversationId` | Yes | Stable caller-supplied conversation ID; nonempty string. |
| `message` | Yes | Customer message; nonempty string. |
| `messageId` | No | Nonempty caller message ID; omitted/null generates an ID. |
| `context` | No | JSON object containing arbitrary business input; null/arrays are invalid. |
| Other root fields | No | Arbitrary business input passed to configured input mapping. |

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:

```json theme={null}
{
  "conversationId": "customer-chat-42",
  "messageId": "customer-message-8",
  "state": "active",
  "handoff": false,
  "message": "I can help you check your order.",
  "tags": ["c7o"]
}
```

`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:

```json theme={null}
{
  "conversationId": "customer-chat-42",
  "messageId": "customer-message-8",
  "state": "handed_off",
  "handoff": true,
  "message": "A human will help.",
  "tags": [
    "c7o",
    "help",
    "c7o_handoff"
  ],
  "screenPopComment": "Summary",
  "scriptResult": {
    "destination": "external",
    "messages": [
      {
        "id": "user",
        "role": "user",
        "content": "Question"
      }
    ],
    "enabled": false,
    "count": 0,
    "empty": null
  }
}
```

`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.

| HTTP | Code | Meaning |
| - | - | - |
| 400 | `BadRequest` | Malformed JSON, invalid decoded path IDs or invalid parsed request envelope. |
| 400 | `invalid_request` | Assistant processing arguments are invalid. |
| 401 | `Unauthenticated` | Missing, invalid, expired or wrong-tenant API key. |
| 403 | `PermissionDenied` | The key does not authorize this operation. |
| 404 | `assistant_not_found` | No current bot specification exists. |
| 409 | `conversation_expired` | Retained transcript exists but live context has expired; use a new conversation ID. |
| 409 | `conversation_conflict` | Reserved conversation-conflict error. |
| 415 | `UnsupportedMediaType` | The handler receives a Content-Type other than application/json. |
| 422 | `unsupported_assistant` | Assistant version/model does not support synchronous text processing. |
| 500 | No code | Oversized JSON, unsupported charset/content encoding or unexpected host failure; message is `Internal Server Error`. |
| 502 | `assistant_error` | Initialization, processing or scoped work failed. |
| 502 | `script_result_error` | Handoff Ticket Fields Script failed or returned invalid JSON. |
| 503 | `service_unavailable` | Assistant storage/configuration work failed. |
| 504 | `assistant_timeout` | The response deadline elapsed; work may still continue. |

Assistant processing errors with HTTP status 500 or above include `action: "handoff"` for your
application's human-routing fallback, for example:

```json theme={null}
{
  "code": "assistant_timeout",
  "message": "The assistant did not complete within the response deadline.",
  "conversationId": "customer-chat-42",
  "messageId": "customer-message-8",
  "action": "handoff"
}
```

Machine-readable contract: [Platform API OpenAPI](../openapi.json).


## OpenAPI

````yaml POST /api/v1/assistant/tenants/{tenantId}/bots/{botId}/messages
openapi: 3.1.0
info:
  title: Crescendo Platform API
  version: 1.6.0
  description: Public HTTP API for the Crescendo platform.
servers:
  - url: https://platform.crescendo.ai
security:
  - bearerAuth: []
  - bearerTokenQuery: []
tags:
  - name: Service
    description: Service metadata and health.
  - name: Provisioning
    description: Tenant-scoped provisioning resources.
  - name: Assistants
    description: Customer messages and assistant handoff results.
  - name: Reporting
    description: Reporting-friendly exports (cursor pagination).
  - name: VOC
    description: Upload recordings for VOC processing.
  - name: MCP
    description: Model Context Protocol (MCP) endpoints.
paths:
  /api/v1/assistant/tenants/{tenantId}/bots/{botId}/messages:
    post:
      tags:
        - Assistants
      summary: Send a customer message to an assistant
      description: >-
        Send a customer message to an assistant using a tenant API key with
        assistant:write or an existing equivalent write scope. The complete JSON
        body is limited to 10 MiB. Each processing call has a default 55-second
        response budget; HTTP parsing and authentication occur before that
        budget starts. Timeout does not cancel conversation work. Retries can
        execute again, and concurrent calls may produce partial/empty replies.
      operationId: sendAssistantMessage
      parameters:
        - name: tenantId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
          description: >-
            Tenant-scoped path ID; must be nonempty, cannot contain slash, and
            cannot be . or .. .
        - name: botId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
          description: >-
            Tenant-scoped path ID; must be nonempty, cannot contain slash, and
            cannot be . or .. .
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantMessageRequest'
            example:
              conversationId: customer-chat-42
              message: Where is my order?
              messageId: customer-message-8
              orderNumber: ORDER-123
              context:
                locale: en
                customer:
                  loyaltyTier: gold
      responses:
        '200':
          description: >-
            Public assistant reply, tags and handoff outcome; partial/empty text
            and retained-handoff null text are valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantMessageResult'
              examples:
                active:
                  value:
                    conversationId: customer-chat-42
                    messageId: customer-message-8
                    state: active
                    handoff: false
                    message: I can help you check your order.
                    tags:
                      - c7o
                handoff:
                  value:
                    conversationId: customer-chat-42
                    messageId: customer-message-8
                    state: handed_off
                    handoff: true
                    message: A human will help.
                    tags:
                      - c7o
                      - help
                      - c7o_handoff
                    screenPopComment: Summary
                    scriptResult:
                      destination: external
                      messages:
                        - id: user
                          role: user
                          content: Question
                      enabled: false
                      count: 0
                      empty: null
        '400':
          description: >-
            BadRequest for malformed JSON, an invalid decoded path ID or invalid
            parsed request envelope, or invalid_request from assistant
            processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantError'
        '401':
          description: 'Unauthenticated: missing, invalid, expired or wrong-tenant API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantError'
        '403':
          description: 'PermissionDenied: insufficient write scope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantError'
        '404':
          description: 'assistant_not_found: no current bot specification.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantError'
        '409':
          description: conversation_expired or the reserved conversation_conflict mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantError'
        '415':
          description: >-
            UnsupportedMediaType: the handler receives a Content-Type other than
            application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantError'
        '422':
          description: >-
            unsupported_assistant: unsupported implementation version or
            synchronous-text model.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantError'
        '500':
          description: >-
            Oversized JSON, unsupported charset/content encoding, or an
            unexpected host failure; message-only response without a code.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                additionalProperties: false
                properties:
                  message:
                    type: string
                    enum:
                      - Internal Server Error
        '502':
          description: assistant_error or script_result_error; action is handoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantError'
        '503':
          description: >-
            service_unavailable: assistant storage or configuration is
            unavailable; action is handoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantError'
        '504':
          description: >-
            assistant_timeout: response deadline elapsed; underlying work is not
            canceled; action is handoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantError'
components:
  schemas:
    AssistantMessageRequest:
      type: object
      required:
        - conversationId
        - message
      additionalProperties: true
      properties:
        conversationId:
          type: string
          minLength: 1
          pattern: \S
          description: Must contain non-whitespace text; original value is preserved.
        message:
          type: string
          minLength: 1
          pattern: \S
          description: Must contain non-whitespace text; original value is preserved.
        messageId:
          type:
            - string
            - 'null'
          minLength: 1
          pattern: \S
          description: Nonempty caller message ID; omitted/null generates an ID.
        context:
          type: object
          additionalProperties: true
          description: >-
            Arbitrary business fields; context wins over duplicate business root
            keys. Null/arrays are invalid.
      description: >-
        All other root fields are arbitrary business input and are preserved. No
        business-key allowlist.
    AssistantMessageResult:
      type: object
      required:
        - conversationId
        - messageId
        - state
        - handoff
        - message
        - tags
      additionalProperties: true
      properties:
        conversationId:
          type: string
        messageId:
          type: string
        state:
          type: string
          enum:
            - active
            - handed_off
        handoff:
          type: boolean
        message:
          type:
            - string
            - 'null'
          description: >-
            Public plain text, possibly partial/empty; null for a retained
            completed handoff.
        tags:
          type: array
          items:
            type: string
          uniqueItems: true
          description: Includes c7o; completed handoff includes c7o_handoff.
        screenPopComment:
          type: string
          description: Present on a newly processed handoff.
        scriptResult:
          type: object
          additionalProperties: true
          description: Ticket Fields Script JSON result on a newly processed handoff.
    AssistantError:
      type: object
      required:
        - code
        - message
      additionalProperties: false
      properties:
        code:
          type: string
        message:
          type: string
          description: Sanitized public message.
        conversationId:
          type: string
        messageId:
          type: string
        action:
          type: string
          enum:
            - handoff
          description: Assistant fallback action on processing errors at HTTP 500 or above.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
    bearerTokenQuery:
      type: apiKey
      in: query
      name: bearer_token
      description: >-
        Alternative to the Authorization header. Prefer the Authorization header
        whenever possible.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.