---
title: "Send Conversation Message"
method: POST
path: "/v1/convai/conversations/{conversation_id}/messages"
tags: ["Agents Platform"]
---

# Send Conversation Message

`POST /v1/convai/conversations/{conversation_id}/messages`

## Request

- Base URL: `https://api.elevenlabs.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/messages`
- Auth: none declared
- TypeScript: <https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/docs/v1/convai/conversations/:conversation_id/messages/post.ts> (a function with typed inputs; its response is checked against the schema)

Send input to a conversation, and wait until the agent finishes or waits on client tool results. With `background` set to true, the endpoint returns 202 when the server admits the turn. Then stream the turn's events with `Last-Event-ID` set to the `stream_cursor`. This endpoint is in alpha and may change.

## Path parameters

- `conversation_id` string, required: The Conversation ID

## Headers

- `xi-api-key` string, nullable: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

## Request body

- SendConversationMessageRequest
  - `input` union[], required: Either one `user_message`, which starts a new turn, or `client_tool_result` items, which answer the `required_actions` of the waiting turn and continue it. Calls that they leave out stay pending. Client tools wait with no timeout. While calls are pending, a `user_message` is rejected. A `user_message` can come with `contextual_update` items, at most one per `context_id`. `client_tool_result` items that answer every pending call can come with `end` updates.
    - union
      - UserMessageInputItem
        - `type` 'user_message', required
        - `content` union[], required: The parts of the message: at most one text part and up to 5 file parts.
          - union
            - TextContentPart
              - …
            - FileContentPart
              - …
      - ClientToolResultItem: A `client_tool_result` whose `type` is required, so that it can share `input` with other items.
        - `type` 'client_tool_result', required
        - `tool_call_id` string, required: ID of the tool call this result corresponds to.
        - `result` string, required
        - `is_error` boolean, required
        - `error_type` 'user_rejected' | 'external_server' | 'external_client' | 'customer_auth' | 'client_timeout' | 'unknown', nullable: Optional category for the failure reason. When set, `is_error` is treated as true. `user_rejected` is special-cased to mark the tool as not having been called.
      - ContextualUpdateInputItem
        - `type` 'contextual_update', required
        - `text` string, required: Context for the agent that the user did not write, such as the client's current state.
        - `context_id` string, required: What the update describes. The agent sees only the latest update for each `context_id`.
        - `placement` 'in_place' | 'end': Where the LLM view renders a contextual update.
  - `background` boolean: If true, return a 202 handle after the turn is admitted instead of waiting for generation to finish.

## Response `200`

Successful Response

- ConversationTurn
  - `turn_id` string, required
  - `status` 'in_progress' | 'completed' | 'requires_action' | 'failed' | 'timed_out', required
  - `output` TextOutputItem[]
    - `type` 'text'
    - `role` 'agent', required
    - `id` string, nullable
    - `text` string, required
    - `created_at_unix_ms` integer, nullable
  - `error` AgentOutputError
    - `type` string, required
    - `code` string, required
    - `message` string, required
  - `required_actions` ClientToolCallRequiredAction[]: The actions the agent waits on. Answer each `client_tool_call` with a `client_tool_result` item in `input` to continue.
    - `type` 'client_tool_call'
    - `tool_call_id` string, required
    - `tool_name` string, required
    - `parameters` object, required
  - `stream_cursor` string, nullable: Resume token for this turn's event stream. Present while the turn is in progress; pass it as Last-Event-ID to stream the turn's events.

## Other responses

- `202`: The server admitted the turn in background mode.
- `422`: Validation Error

## Changes

- **2026-11-12** `f2fab82c4571`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/changes/v1/convai/conversations/:conversation_id/messages/post.md)

---

[API](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation.md) - [All operations](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/revisions/f2fab82c4571?raw)