> ## 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) |