Send Live Agent Message

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"
  }'

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"
  }'

{
  "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
}

{
  "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
}

POST

widget

{id}

threads

{thread_id}

webhook

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"
  }'

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"
  }'

{
  "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
}

{
  "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
}

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.

Headers

string

required

Your API key for authentication.

Path Parameters

string

required

The widget ID.

string

required

The thread ID from the INITIAL_CONVERSATION webhook payload.

Body

The request body accepts two payload types:

MESSAGE
END_CONVERSATION

Send a message to the user.

string

required

Must be "MESSAGE".

string

required

The message content to display to the user.

string

required

Identifier for the live agent sending the message. This can be used to distinguish between different agents in the conversation.

string

Optional ISO 8601 timestamp for the message. Defaults to the current time if not provided.

End the live agent session.

string

required

Must be "END_CONVERSATION".

string

Optional identifier for the agent ending the conversation.

Response

number

HTTP status code (200 for success).

object

For MESSAGE requests, returns the created message object. For END_CONVERSATION requests, returns the updated thread object with ended_at timestamp.

array | null

Array of error objects if the request failed, otherwise null.

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.

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"
  }'

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"
  }'

{
  "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
}

{
  "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
}

Docs for agents: llms.txt

Get Widget Threads List Custom Components

⌘I

Basic Tutorials

Calls

Voices & Text to Speech

Conversational Pathways

Knowledge Bases

Numbers

Blocked Numbers

Widgets

Tools

Contacts

Memory

Node tests

Agent Testing

Evals

Guard Rails

Web Agents

Live Translation

Custom Twilio Accounts

Batches

Prompts

Account

Organizations

Messaging

SIP Trunks

Custom Dialing Pools

Personas

Citation Schemas

Alarms

Triage

Send Live Agent Message

Headers

Path Parameters

Body

Response

Error Codes

​Headers

​Path Parameters

​Body

​Response

​Error Codes

Headers

Path Parameters

Body

Response

Error Codes