> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reachedapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List SMS Conversations

> Returns a paginated list of SMS conversations (thread view per contact).

# List SMS Conversations

Returns a paginated list of SMS conversations (thread view per contact). Each conversation summarizes the latest message exchanged with a contact phone number. Default sort: `last_message_at` DESC.

## Request

`GET /v1/sms-conversations`

### Query Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `page` | integer | No | Page number (default: 1) |
| `per_page` | integer | No | Results per page, max 100 (default: 25) |
| `lead_id` | uuid | No | Filter by lead ID |
| `phone` | string | No | Filter by phone number (matches `contact_phone` or `company_phone`) in E.164 format |
| `unread` | boolean | No | Set to `"true"` to return only conversations with unread messages (`unread_count > 0`) |
| `workspace_id` | uuid | No | Filter by workspace ID. Use the [List Workspaces](/rest-api/workspaces/list-workspaces) endpoint to get available IDs. Omit to return conversations from all workspaces. |

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/sms-conversations?unread=true&per_page=25" \
    -H "Authorization: Bearer rchd_live_xxxxxxxxxxxx"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    unread: "true",
    per_page: "25"
  });

  const response = await fetch(
    `https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/sms-conversations?${params}`,
    { headers: { "Authorization": "Bearer rchd_live_xxxxxxxxxxxx" } }
  );
  const { data, meta } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/sms-conversations",
      headers={"Authorization": "Bearer rchd_live_xxxxxxxxxxxx"},
      params={"unread": "true", "per_page": 25}
  )
  result = response.json()
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "data": [
    {
      "id": "conv-uuid-1",
      "lead_id": "a1b2c3d4-...",
      "contact_phone": "+33612345678",
      "company_phone": "+33140000000",
      "contact_name": "John Doe",
      "last_message_body": "Sounds good, let's talk tomorrow at 2pm.",
      "last_message_at": "2026-09-14T11:30:00.000Z",
      "last_message_direction": "inbound",
      "unread_count": 2,
      "created_at": "2026-09-14T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `id` | uuid | Conversation unique identifier |
| `lead_id` | uuid | Associated lead ID (if linked) |
| `contact_phone` | string | The contact's phone number |
| `company_phone` | string | Your company phone number used in the conversation |
| `contact_name` | string | Name of the contact (if known) |
| `last_message_body` | string | Content of the most recent message |
| `last_message_at` | datetime | Timestamp of the most recent message |
| `last_message_direction` | string | Direction of the most recent message: `inbound` or `outbound` |
| `unread_count` | integer | Number of unread inbound messages in this conversation |
| `created_at` | datetime | Conversation creation timestamp |
| `workspace_id` | uuid | Workspace ID the conversation belongs to (null = default workspace) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.