Conversations
/v1/conversations/searchScope: conversations:read.
Find customer conversations about a topic. Filter by category or tag.
Authorization
bearerAuth In: header
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/conversations/search?query=string"{ "data": [ { "conversation_id": "string", "similarity": 0, "text_content": "string", "category": "string", "tag": "string", "customer": "string" } ], "next_cursor": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/conversationsScope: conversations:read.
View conversations, newest first. Pass contact_id to scope to one customer's conversations.
Authorization
bearerAuth In: header
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/conversations"{ "data": [ { "id": "string", "created_at": "string", "updated_at": "string", "last_engaged_at": "string", "last_received_at": "string", "awaiting_reply": true, "cart_value": "string", "cart_currency": "string", "customer": { "name": "string", "handle": "string" }, "workflow": { "name": "string", "type": "string" }, "checkout_state": "string", "last_message": { "body": "string", "direction": "string", "created_at": "string" } } ], "next_cursor": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/conversations/{id}Scope: conversations:read.
View a conversation by ID. Returns 404 if it cannot be found.
Authorization
bearerAuth In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/conversations/string"{ "id": "string", "created_at": "string", "updated_at": "string", "last_engaged_at": "string", "last_received_at": "string", "awaiting_reply": true, "cart_value": "string", "cart_currency": "string", "customer": { "name": "string", "handle": "string" }, "workflow": { "name": "string", "type": "string" }, "checkout_state": "string", "last_message": { "body": "string", "direction": "string", "created_at": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/conversations/{id}/messagesScope: conversations:read.
View messages in a conversation, oldest first. Returns 404 if the conversation cannot be found.
Authorization
bearerAuth In: header
Path Parameters
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/conversations/string/messages"{ "data": [ { "id": "string", "direction": "string", "body": "string", "status": "string", "created_at": "string", "updated_at": "string", "sent_at": "string", "scheduled_for": "string" } ], "next_cursor": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/conversations/{id}/messagesScope: conversations:write.
Send a reply on an existing conversation, addressed by its id. Requires conversations:write, the messaging-API beta, and an Idempotency-Key header (<= 255 chars). Returns the queued message id; final delivery status arrives by webhook. Repeating a key with the same content returns the original response; a different content returns 409.
Authorization
bearerAuth In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/conversations/string/messages" \ -H "Content-Type: application/json" \ -d '{ "text": "string" }'{ "message_id": "string", "status": "queued", "scheduled_for": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/conversations/messagesScope: conversations:write.
Send a reply addressed by contact_channel_id (or, with contacts:read-phone, by phone), resolving to that contact's existing conversation on the brand's number. Returns conversation_not_found when there is none; never starts a conversation. Same auth, idempotency and semantics as POST /conversations/{id}/messages.
Authorization
bearerAuth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/conversations/messages" \ -H "Content-Type: application/json" \ -d '{ "text": "string" }'{ "message_id": "string", "status": "queued", "scheduled_for": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/conversations/{id}/pauseScope: conversations:pause.
Whether the conversation's contact is paused, and until when. Requires conversations:pause and the messaging-API beta.
Authorization
bearerAuth In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/conversations/string/pause"{ "conversation_id": "string", "paused": true, "paused_until": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/conversations/{id}/pauseScope: conversations:pause.
Pause the brand's agent queue, assignment rules, reply flows and off-hours auto-replies for the conversation's contact while your help desk handles them. Blasts, marketing flows and API replies still go out. The pause lasts 7 days and each API reply pushes it forward; pausing again also pushes it forward. Requires conversations:pause and the messaging-API beta.
Authorization
bearerAuth In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/conversations/string/pause"{ "conversation_id": "string", "paused": true, "paused_until": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/conversations/{id}/resumeScope: conversations:pause.
End the pause on the conversation's contact so the brand's agents and automated replies act on it again. A customer text nobody answered goes back in the agent queue. Idempotent: resuming a conversation that is not paused returns paused: false. Requires conversations:pause and the messaging-API beta.
Authorization
bearerAuth In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/conversations/string/resume"{ "conversation_id": "string", "paused": true, "paused_until": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/contacts/{id}/phoneScope: contacts:read-phone.
The contact’s SMS phone number. Needs the contacts:read-phone permission, which exposes customer phone numbers; every call is recorded in the key’s audit log.
Authorization
bearerAuth In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/contacts/string/phone"{ "id": "string", "phone": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/contactsScope: contacts:read.
View contacts, oldest first.
Authorization
bearerAuth In: header
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/contacts"{ "data": [ { "id": "string", "given_name": "string", "family_name": "string", "name": "string", "source": "string", "accepts_sms_marketing": true, "created_at": "string", "updated_at": "string" } ], "next_cursor": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/contacts/{id}Scope: contacts:read.
View a contact by ID. Returns 404 if it cannot be found.
Authorization
bearerAuth In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/contacts/string"{ "id": "string", "given_name": "string", "family_name": "string", "name": "string", "source": "string", "accepts_sms_marketing": true, "created_at": "string", "updated_at": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/brand/insightsScope: insights:read.
See common themes in customer conversations, including checkout issues, post-purchase concerns and product questions. Filter by category, tag or date.
Authorization
bearerAuth In: header
Query Parameters
next_cursor from the previous page.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/brand/insights"{ "data": [ { "id": "string", "category": "string", "tag": "string", "topic": "string", "body": "string", "updated_at": "string" } ], "next_cursor": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/brand/insights/{insight_id}/conversationsScope: insights:read.
View the conversations behind an insight, with customer details and message previews. Use an ID from list_conversation_insights.
Authorization
bearerAuth In: header
Path Parameters
Query Parameters
next_cursor from the previous page.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/brand/insights/string/conversations"{ "data": [ { "conversation_id": "string", "created_at": "string", "customer": { "name": "string", "phone": "string" }, "checkout_state": "string", "message_preview": "string" } ], "next_cursor": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/checkouts/{checkout_id}/purchase-likelihoodScope: conversations:read. MCP tool: get_checkout_purchase_likelihood.
Read the cart and per-product purchase likelihood for a checkout of the calling brand.
Authorization
bearerAuth In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/checkouts/497f6eca-6276-4993-bfeb-53cbbbba6f08/purchase-likelihood"{ "checkout_id": "a0db819d-3316-4040-b9b7-2c905552650c", "purchase_likelihood": { "probability": 0, "band": "string", "has_score": true, "computed_at": "string" }, "items": [ { "product_key": "string", "title": "string", "probability": 0, "band": "string", "computed_at": "string" } ]}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/conversations/{conversation_id}/traceScope: conversations:read.
Trace a conversation back to what started it and forward to what it produced: the triggering event (checkout, cart, custom event, order, subscription event or signup list), the campaign and each step of its run (entered, skipped with the reason, sent, failed), the messages by status with the next scheduled send time (messages wait for quiet hours or a wait step), and whether it led to a recovered order. Use it to answer "why did this customer get this text?" or "did this conversation recover the sale?".
Authorization
bearerAuth In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/conversations/string/trace"{ "conversation_id": "string", "created_at": "string", "contact_id": "string", "campaign": { "id": "string", "name": "string", "type": "string" }, "trigger": { "kind": "checkout", "event_type": "string", "event_id": "string", "checkout": { "id": "string", "state": "string", "total": { "amount": 0, "currency": "string" }, "created_at": "string", "abandoned_at": "string", "completed_at": "string" }, "custom_event": { "id": "string", "type": "string", "name": "string", "source": "string", "external_event_id": "string", "received_at": "string" }, "order": { "id": "string", "number": "string", "total": { "amount": 0, "currency": "string" }, "created_at": "string" }, "subscription_event": { "id": "string", "type": "string", "triggered_at": "string" }, "list_id": "string" }, "run": [ { "at": "string", "state": "string", "step": "string", "step_id": "string", "event_type": "string", "event_id": "string", "campaign_id": "string", "campaign_name": "string", "conversation_id": "string", "contact_id": "string", "reason": { "code": "string", "label": "string", "level": "string", "rule": "string" }, "error": "string" } ], "messages": { "total": 0, "by_status": [ { "status": "string", "count": 0 } ], "next_scheduled_for": "string", "first_sent_at": "string", "last_sent_at": "string" }, "outcome": { "recovered": true, "recovered_amount": { "amount": 0, "currency": "string" }, "goals": [ { "at": "string", "conversation_id": "string", "campaign_id": "string", "order_id": "string", "order_number": "string", "amount": { "amount": 0, "currency": "string" }, "attribution": "string", "billing_status": "string", "recovered": true } ] }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}