API
Conversations API
Resolve a Contact to a sendable conversation and page through recent conversations.
Find conversations for a Contact
GET /v1/contacts/{contact_id}/conversations
Authorization: Bearer <token>
Requires conversations:read.
{
"data": [
{
"id": "c23456789012345678901234",
"contact_id": "c12345678901234567890123",
"name": "Ada Lovelace",
"recipient_address": "ada@example.com",
"sender_identity_id": "s12345678901234567890123",
"sender_address": "owner@example.com",
"service": "imessage",
"active": true,
"last_message_at": "2026-09-24T01:00:00Z"
}
]
}
A Contact can have more than one conversation because the recipient address, sender identity, and service are part of the route. Use last_message_at to distinguish current and historical routes. Use an active row’s id and sender_identity_id when sending a message.
recipient_address is the Contact address for this route. sender_address is the local sender identity, not another Contact address. Both fields require contacts:addresses:read and are omitted without that scope.
An accessible Contact with no existing conversation returns an empty data array. The API does not create a conversation for an arbitrary phone number or email address.
Recent conversations
GET /v1/recent?limit=50&cursor=<opaque_cursor>
Authorization: Bearer <token>
Requires conversations:read. Results are ordered by latest activity.
{
"data": [
{
"id": "c23456789012345678901234",
"recipient_id": "c12345678901234567890123",
"name": "Ada Lovelace",
"last_message_at": "2026-09-24T01:00:00Z"
}
],
"page": {
"next_cursor": "opaque-value",
"has_more": true
}
}
id is the latest route-specific Conversation ID. recipient_id is the Contact, shared unknown-conversation, or group ID used by the team inbox. Hidden targets are omitted before pagination.