Skip to main content
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: 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"
  }'

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

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.

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

​
authorization
string
required
Your API key for authentication.

​
Path Parameters

​
id
string
required
The widget ID.
​
thread_id
string
required
The thread ID from the INITIAL_CONVERSATION webhook payload.

​
Body

The request body accepts two payload types:
Send a message to the user.
​
type
string
required
Must be "MESSAGE".
​
content
string
required
The message content to display to the user.
​
sender_id
string
required
Identifier for the live agent sending the message. This can be used to distinguish between different agents in the conversation.
​
created_at
string
Optional ISO 8601 timestamp for the message. Defaults to the current time if not provided.

​
Response

​
status
number
HTTP status code (200 for success).
​
data
object
For MESSAGE requests, returns the created message object. For END_CONVERSATION requests, returns the updated thread object with ended_at timestamp.
​
errors
array | null
Array of error objects if the request failed, otherwise null.

​
Error Codes

StatusErrorDescription
400INVALID_PARAMETERRequest body validation failed.
400THREAD_ENDEDThe thread has already been ended.
404NOT_FOUNDThread 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"
  }'

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