Conversations
List and inspect WhatsApp conversations, and route them to the right agents with assignment and transfer operations.
/v1/conversations List conversations
Retrieve a paginated list of conversations, optionally filtered by inbox, contact, or status.
Parameters
inbox_id string Filter by inbox ID.
contact_id string Filter by contact ID.
team_id string Filter by assigned team ID.
status string Filter by status. One of: open, pending, closed, snoozed, spam.
filter string Named filter, e.g. "assigned_to_me" or "unassigned".
page integer Page number. Defaults to 1.
per_page integer Results per page. Defaults to 25, max 100.
Request
curl https://api.boltly.online/v1/conversations?status=open \
-H "X-API-Key: $API_KEY"Response
{
"data": [
{
"id": "conv_01H...",
"contact_id": "c1a2b3c4-...",
"contact_name": "Jane Doe",
"phone_number": "+1234567890",
"platform": "whatsapp",
"status": "open",
"last_message_at": "2026-04-03T12:00:00Z",
"is_within_24h_window": true,
"assigned_to": "u_01H...",
"created_at": "2026-04-01T08:00:00Z",
"updated_at": "2026-04-03T12:00:00Z"
}
],
"meta": { "page": 1, "per_page": 25, "total": 34 }
}/v1/conversations/{id} Get conversation
Retrieve a single conversation by its ID, including assignment and 24-hour window state.
Parameters
id string required Conversation ID.
Request
curl https://api.boltly.online/v1/conversations/conv_01H... \
-H "X-API-Key: $API_KEY"Response
{
"data": {
"id": "conv_01H...",
"organization_id": "org_01H...",
"inbox_id": "inb_01H...",
"contact_id": "c1a2b3c4-...",
"contact_name": "Jane Doe",
"phone_number": "+1234567890",
"platform": "whatsapp",
"status": "open",
"last_message_at": "2026-04-03T12:00:00Z",
"last_user_message_at": "2026-04-03T11:45:00Z",
"is_within_24h_window": true,
"is_expired": false,
"is_favorite": false,
"assigned_to": "u_01H...",
"assigned_to_name": "Sam Agent",
"team_id": "team_01H...",
"created_at": "2026-04-01T08:00:00Z",
"updated_at": "2026-04-03T12:00:00Z"
}
}/v1/conversations/{id}/assign Assign agent
Assign a conversation to an agent, a team, or both.
Parameters
id string required Conversation ID.
assigned_to string User ID of the agent to assign.
team_id string Team ID to assign the conversation to.
reason string Optional note recorded in the assignment history.
Request
curl -X POST https://api.boltly.online/v1/conversations/conv_01H.../assign \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assigned_to": "u_01H...",
"reason": "Escalated billing question"
}'Response
{
"data": {
"id": "asg_01H...",
"conversation_id": "conv_01H...",
"assigned_to": "u_01H...",
"assigned_by": "u_02H...",
"assignment_type": "manual",
"reason": "Escalated billing question",
"created_at": "2026-04-03T12:05:00Z"
}
}/v1/conversations/{id}/transfer Transfer
Transfer a conversation from one agent to another.
Parameters
id string required Conversation ID.
from_agent string required User ID of the agent currently handling the conversation.
to_agent string required User ID of the agent to transfer the conversation to.
reason string Optional note recorded in the assignment history.
Request
curl -X POST https://api.boltly.online/v1/conversations/conv_01H.../transfer \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_agent": "u_01H...",
"to_agent": "u_03H...",
"reason": "Shift handover"
}'Response
{
"data": {
"id": "asg_02H...",
"conversation_id": "conv_01H...",
"assigned_to": "u_03H...",
"assigned_by": "u_01H...",
"assignment_type": "transfer",
"reason": "Shift handover",
"created_at": "2026-04-03T18:00:00Z"
}
}