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.