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

# Send Live Agent Message

> Send a message from a live agent to the user, or end the conversation.

Use this endpoint to send messages from your live agent platform back to the user in the widget. This is the counterpart to the webhooks Bland sends to your system during a [live agent escalation](/tutorials/chat-widget#escalate-to-live-agents).

### Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The widget ID.
</ParamField>

<ParamField path="thread_id" type="string" required>
  The thread ID from the `INITIAL_CONVERSATION` webhook payload.
</ParamField>

### Body

The request body accepts two payload types:

<Tabs>
  <Tab title="MESSAGE">
    Send a message to the user.

    <ParamField body="type" type="string" required>
      Must be `"MESSAGE"`.
    </ParamField>

    <ParamField body="content" type="string" required>
      The message content to display to the user.
    </ParamField>

    <ParamField body="sender_id" type="string" required>
      Identifier for the live agent sending the message. This can be used to distinguish between different agents in the conversation.
    </ParamField>

    <ParamField body="created_at" type="string">
      Optional ISO 8601 timestamp for the message. Defaults to the current time if not provided.
    </ParamField>
  </Tab>

  <Tab title="END_CONVERSATION">
    End the live agent session.

    <ParamField body="type" type="string" required>
      Must be `"END_CONVERSATION"`.
    </ParamField>

    <ParamField body="sender_id" type="string">
      Optional identifier for the agent ending the conversation.
    </ParamField>
  </Tab>
</Tabs>

### Response

<ResponseField name="status" type="number">
  HTTP status code (200 for success).
</ResponseField>

<ResponseField name="data" type="object">
  For `MESSAGE` requests, returns the created message object. For `END_CONVERSATION` requests, returns the updated thread object with `ended_at` timestamp.
</ResponseField>

<ResponseField name="errors" type="array | null">
  Array of error objects if the request failed, otherwise null.
</ResponseField>

### Error Codes

| Status | Error               | Description                         |
| ------ | ------------------- | ----------------------------------- |
| 400    | `INVALID_PARAMETER` | Request body validation failed.     |
| 400    | `THREAD_ENDED`      | The thread has already been ended.  |
| 404    | `NOT_FOUND`         | Thread not found with the given ID. |

<RequestExample>
  ```bash Send Message theme={null}
  curl -X POST "https://api.bland.ai/v1/widget/{widget_id}/threads/{thread_id}/webhook" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "MESSAGE",
      "content": "Hi! I am a live agent. How can I help you today?",
      "sender_id": "agent_123"
    }'
  ```

  ```bash End Conversation theme={null}
  curl -X POST "https://api.bland.ai/v1/widget/{widget_id}/threads/{thread_id}/webhook" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "END_CONVERSATION",
      "sender_id": "agent_123"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Message Response theme={null}
  {
    "data": {
      "created_at": "2025-12-10T19:27:02.941Z",
      "updated_at": "2025-12-10T19:27:02.941Z",
      "id": "30a3e35d-9ffb-4810-aef7-2600346107e6",
      "org_id": "99a0d526-6910-4f31-92b8-72834d0827fb",
      "widget_id": "b5f3fb6b-2285-4c73-95be-6609eca09986",
      "thread_id": "f5ff280b-b0d8-4261-a1ed-b74003e733a2",
      "pathway_session_id": null,
      "sender_type": "LIVE_AGENT",
      "sender_id": "49e6e820-f5b7-4fb1-8aa8-7fb162fbcf91",
      "content": "You have a great day too!"
    },
    "errors": null
  }
  ```

  ```json End Conversation Response theme={null}
  {
    "data": {
      "created_at": "2025-12-10T19:25:00.809Z",
      "updated_at": "2025-12-10T20:26:41.180Z",
      "ended_at": "2025-12-10T20:26:41.179Z",
      "live_agent_handoff_at": "2025-12-10T19:25:04.745Z",
      "id": "f5ff280b-b0d8-4261-a1ed-b74003e733a2",
      "org_id": "99a0d526-6910-4f31-92b8-72834d0827fb",
      "widget_id": "b5f3fb6b-2285-4c73-95be-6609eca09986",
      "visitor_id": "ec14ee83-fa2b-493a-b009-0e29414a1e97",
      "live_agent_endpoint_url": "https://webhook.site/32d53101-7d67-4879-b350-6aa2d1e12ada",
      "language": "en"
    },
    "errors": null
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)