Widgets
Send Live Agent Message
Send a message from a live agent to the user, or end the conversation.
POST
/
v1
/
widget
/
{id}
/
threads
/
{thread_id}
/
webhook
curl -X POST "https://api.bland.ai/v1/widget/{widget_id}/threads/{thread_id}/webhook" \
-H "Authorization: Bearer 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: Bearer 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.
Docs for agents: llms.txt
Headers
Path Parameters
Body
The request body accepts two payload types:- MESSAGE
- END_CONVERSATION
Send a message to the user.
Identifier for the live agent sending the message. This can be used to distinguish between different agents in the conversation.
Response
For
MESSAGE requests, returns the created message object. For END_CONVERSATION requests, returns the updated thread object with ended_at timestamp.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: Bearer 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: Bearer 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
Was this page helpful?
⌘I
curl -X POST "https://api.bland.ai/v1/widget/{widget_id}/threads/{thread_id}/webhook" \
-H "Authorization: Bearer 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: Bearer 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
}