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

# Vobiz Messaging API - Conversations

> List and read two-way SMS, MMS and RCS threads with the Vobiz Messaging API, track unread counts and mark conversations read to build an inbox.

A conversation is the two-way thread between one of your numbers (or RCS senders) and one contact on one channel. Vobiz creates it with the first message in either direction and adds every later message between the same pair to it. You use the Conversations endpoints to build an inbox: list threads, read their messages, and keep unread counts in step with what your users have seen.

## The conversation object

| Field | Type | Description |
| - | - | - |
| `id` | string (UUID) | Unique identifier of the conversation. Messages carry it as `conversationId`. |
| `accountId` | string | Your Vobiz account ID, for example `MA_XXXXXXXX`. |
| `participantA` | string | Your side: your number in E.164 format, or your RCS sender's `senderName`. |
| `participantB` | string | The contact's number in E.164 format. |
| `channel` | string | `sms`, `mms` or `rcs`. The same two parties have a separate conversation per channel. |
| `lastMessageAt` | string (ISO 8601) | Time of the latest message, sent or received. |
| `messageCount` | integer | Total messages in the thread, both directions. |
| `unreadCount` | integer | Messages added since the thread was last marked read. |
| `lastReadAt` | string (ISO 8601) | When the thread was last marked read. Omitted until the first mark-read. |
| `createdAt` | string (ISO 8601) | When the conversation was created. |

## Endpoints

| Method | Endpoint | What it does |
| - | - | - |
| `GET` | [`/conversations`](/docs/sms/api/conversations/list-conversations) | List your conversations, most recently active first. |
| `GET` | [`/conversations/{id}`](/docs/sms/api/conversations/get-conversation) | Retrieve one conversation with its counters. |
| `GET` | [`/conversations/{id}/messages`](/docs/sms/api/conversations/list-conversation-messages) | List the messages in one thread, newest first. |
| `POST` | [`/conversations/{id}/read`](/docs/sms/api/conversations/mark-conversation-read) | Reset `unreadCount` to `0` and set `lastReadAt`. |
| `GET` | [`/conversations/unread-count`](/docs/sms/api/conversations/unread-count) | Get the unread total across all conversations. |

All paths are relative to `https://api.vobiz.ai/api/v1/sms`. Every request carries your `X-Auth-ID` and `X-Auth-Token` headers.

## Unread counts

Each new message in a thread raises its `unreadCount` by one. `GET /conversations/unread-count` returns the sum across all threads as `totalUnread`, which suits an inbox badge. When a user opens a thread, call `POST /conversations/{id}/read`: the thread's `unreadCount` returns to `0`, `lastReadAt` is set to the current time, and `totalUnread` drops accordingly. The call takes no body and is safe to repeat.

## Pagination

Both list endpoints return a bare JSON array and page with `limit` and `offset`.

| Endpoint | Order | `limit` default | `limit` range |
| - | - | - | - |
| `GET /conversations` | `lastMessageAt`, newest first | `20` | `1` to `100` |
| `GET /conversations/{id}/messages` | `createdAt`, newest first | `50` | `1` to `100` |

A page with fewer items than `limit` is the last page. To show a thread oldest to newest, reverse each page.

## Example

```bash cURL theme={null}
curl "https://api.vobiz.ai/api/v1/sms/conversations?limit=20&offset=0" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"
```

```json 200 OK theme={null}
[
  {
    "id": "c7d1e9a3-2b4f-4a6c-8d5e-1f3a9b7c2e04",
    "accountId": "MA_XXXXXXXX",
    "participantA": "+14155550100",
    "participantB": "+14155550123",
    "channel": "sms",
    "lastMessageAt": "2026-10-18T09:20:11.402118Z",
    "messageCount": 3,
    "unreadCount": 1,
    "lastReadAt": "2026-10-18T09:16:40.051932Z",
    "createdAt": "2026-10-18T09:15:02.119874Z"
  }
]
```

## Real-time updates

Polling works, but an inbox feels faster when it reacts to events. Subscribe to `message.received` with [webhooks (callbacks)](/docs/sms/webhooks), or open the [WebSocket](/docs/sms/websocket), then refresh the affected conversation with `GET /conversations/{id}`.

## Related

* [Conversations guide](/docs/sms/conversations)
* [Messages API](/docs/sms/api/messages)
* [Opt-outs](/docs/sms/opt-outs)
* [Webhooks](/docs/sms/webhooks)
* [WebSocket](/docs/sms/websocket)


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