List conversations
Returns a paginated list of conversations between your phone numbers and external contacts, newest first. Each conversation groups the inbound and outbound messages exchanged with a single contact on one of your numbers and surfaces the latest activity.
The conversation id is stable and can be passed unmodified to
GET /v1/conversations/{id}/messages. Cursor pagination uses
meta.next_cursor, which is null on the last page.
Conversation metadata is retained indefinitely, but message content is
subject to your retention window. Once the most recent message body has
been removed, last_message_preview renders as the literal string
"[redacted]" and last_message_body_redacted_at carries the
timestamp; the conversation itself does not disappear.
Requires the conversations:read scope.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Query Parameters
501 <= value <= 200uuiddate-timeResponse Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/conversations"{
"success": true,
"data": [
{
"id": "AQID...base64url",
"phone_number_id": "7c1f0a2d-9e8b-4c3a-9d2e-1f0a2b3c4d5e",
"phone_number": "+15551112222",
"contact_number": "+15554443333",
"last_message_at": "2026-04-28T12:00:01Z",
"last_message_direction": "inbound",
"last_message_preview": "Cancel my appointment please",
"last_message_body_redacted_at": null,
"message_count": 14,
"consent": {
"opted_in": true,
"opted_in_at": "2026-04-01T09:00:00Z"
}
},
{
"id": "BQYH...base64url",
"phone_number_id": "7c1f0a2d-9e8b-4c3a-9d2e-1f0a2b3c4d5e",
"phone_number": "+15551112222",
"contact_number": "+15558889999",
"last_message_at": "2026-01-10T08:00:00Z",
"last_message_direction": "outbound",
"last_message_preview": "[redacted]",
"last_message_body_redacted_at": "2026-04-10T03:11:42Z",
"message_count": 6,
"consent": null
}
],
"meta": {
"total": 0,
"limit": 50,
"offset": 0,
"next_cursor": null
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}