> ## 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 Conversations and Inbox

> Read two-way SMS, MMS and RCS threads on Vobiz - how inbound messages create conversations, the conversation object, listing threads and their messages, marking as read, unread counts, and the console Inbox.

A conversation is the thread between one of your numbers (or RCS senders) and one contact on one channel. Every message you send and every reply you receive is attached to a conversation, so your team can read an exchange in order, see what is unanswered, and reply - from the API or from the console Inbox.

## How conversations are created

You never create a conversation yourself. Vobiz finds or creates one for each unique combination of **your number**, **the contact's number** and **channel**:

* When you call [Send a message](/docs/sms/api/messages/send-message), the message is attached to the conversation for that `from`, `to` and `channel`, creating it on first contact. The message object carries the thread's `conversationId`.
* When a contact sends a message to one of your numbers, Vobiz stores it with `direction: "in"` and `status: "received"` in the same thread, increments the thread's `unreadCount`, and bumps `lastMessageAt`.
* An RCS button tap is stored as an inbound message in the thread, carrying the button's `postbackData`. See [RCS](/docs/sms/channels/rcs#receive-button-taps-and-replies).
* STOP and other keyword replies are stored in the thread like any other inbound message, and additionally recorded as [opt-outs](/docs/sms/opt-outs).

Because the key includes the channel, an SMS exchange and an RCS exchange with the same contact are two conversations.

## The conversation object

```json theme={null}
{
  "id": "3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34",
  "accountId": "MA_XXXXXXXX",
  "participantA": "+14155550100",
  "participantB": "+14155550123",
  "channel": "sms",
  "lastMessageAt": "2026-10-16T21:23:51.143002Z",
  "messageCount": 3,
  "unreadCount": 1,
  "lastReadAt": "2026-10-16T21:23:05.068717Z",
  "createdAt": "2026-10-16T21:23:02.193386Z"
}
```

| Field | Meaning |
| - | - |
| `id` | Conversation UUID. Matches `conversationId` on each message. |
| `accountId` | Your account. |
| `participantA` | Your messaging number or RCS sender. |
| `participantB` | The contact's number in E.164 format. |
| `channel` | `sms`, `mms` or `rcs`. |
| `lastMessageAt` | Timestamp of the latest message in either direction. Threads are listed by this, newest first. |
| `messageCount` | Messages in the thread, both directions. |
| `unreadCount` | Inbound messages received since you last marked the thread read. |
| `lastReadAt` | When you last called mark as read. Omitted until the first call. |
| `createdAt` | When the first message in the thread was created. |

## List conversations

[List conversations](/docs/sms/api/conversations/list-conversations) returns a JSON array of conversation objects ordered by `lastMessageAt`, newest first. `limit` defaults to 20 (maximum 100) and `offset` pages through older threads.

```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 Response - 200 OK theme={null}
[
  {
    "id": "3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34",
    "accountId": "MA_XXXXXXXX",
    "participantA": "+14155550100",
    "participantB": "+14155550123",
    "channel": "sms",
    "lastMessageAt": "2026-10-16T21:23:51.143002Z",
    "messageCount": 3,
    "unreadCount": 1,
    "createdAt": "2026-10-16T21:23:02.193386Z"
  },
  {
    "id": "7d6b2e8f-4a01-4c5e-9b2e-1c408a3d4f5e",
    "accountId": "MA_XXXXXXXX",
    "participantA": "+14155550100",
    "participantB": "+14155550124",
    "channel": "sms",
    "lastMessageAt": "2026-10-16T13:25:41.656088Z",
    "messageCount": 2,
    "unreadCount": 0,
    "lastReadAt": "2026-10-16T21:24:15.529550Z",
    "createdAt": "2026-10-16T13:25:41.167760Z"
  }
]
```

An account with no conversations receives `[]`.

## Get one conversation

[Get a conversation](/docs/sms/api/conversations/get-conversation) returns a single object. An unknown id, a malformed id, or a thread that belongs to another account returns `404 {"error":"conversation not found"}`.

```bash cURL theme={null}
curl "https://api.vobiz.ai/api/v1/sms/conversations/3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"
```

## Read the messages in a thread

[List conversation messages](/docs/sms/api/conversations/list-conversation-messages) returns a JSON array of message objects for the thread, in both directions. `limit` defaults to 50 (maximum 100); use `offset` for older messages.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.vobiz.ai/api/v1/sms/conversations/3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34/messages?limit=50" \
    -H "X-Auth-ID: MA_XXXXXXXX" \
    -H "X-Auth-Token: YOUR_AUTH_TOKEN"
  ```

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

  conversation_id = "3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34"
  resp = requests.get(
      f"https://api.vobiz.ai/api/v1/sms/conversations/{conversation_id}/messages",
      headers={"X-Auth-ID": "MA_XXXXXXXX", "X-Auth-Token": "YOUR_AUTH_TOKEN"},
      params={"limit": 50},
  )
  resp.raise_for_status()
  for m in resp.json():
      arrow = "<-" if m["direction"] == "in" else "->"
      print(m["createdAt"], arrow, m["status"], m["text"])
  ```

  ```javascript Node theme={null}
  const conversationId = "3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34";
  const resp = await fetch(
    `https://api.vobiz.ai/api/v1/sms/conversations/${conversationId}/messages?limit=50`,
    { headers: { "X-Auth-ID": "MA_XXXXXXXX", "X-Auth-Token": "YOUR_AUTH_TOKEN" } }
  );
  for (const m of await resp.json()) {
    console.log(m.createdAt, m.direction === "in" ? "<-" : "->", m.status, m.text);
  }
  ```
</CodeGroup>

```json Response - 200 OK theme={null}
[
  {
    "id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
    "accountId": "MA_XXXXXXXX",
    "direction": "out",
    "channel": "sms",
    "from": "+14155550100",
    "to": "+14155550123",
    "text": "Your order #4821 is ready for pickup.",
    "mediaUrls": null,
    "status": "delivered",
    "conversationId": "3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34",
    "createdAt": "2026-10-16T21:23:02.676996Z",
    "updatedAt": "2026-10-16T21:23:05.740083Z"
  },
  {
    "id": "0e5f1a7c-9b34-4d2e-8f6b-3c1d7e526f4b",
    "accountId": "MA_XXXXXXXX",
    "direction": "in",
    "channel": "sms",
    "from": "+14155550123",
    "to": "+14155550100",
    "text": "Great, on my way",
    "mediaUrls": [],
    "status": "received",
    "conversationId": "3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34",
    "createdAt": "2026-10-16T21:23:51.143002Z",
    "updatedAt": "2026-10-16T21:23:51.143002Z"
  }
]
```

Inbound messages have `direction: "in"`, `status: "received"`, and `from` set to the contact. Outbound messages carry the statuses described in [SMS statuses](/docs/sms/channels/sms#message-statuses). To reply, call [Send a message](/docs/sms/api/messages/send-message) with `from` set to `participantA` and `to` set to `participantB`; the reply joins the same thread.

## Mark a conversation as read

[Mark a conversation read](/docs/sms/api/conversations/mark-conversation-read) resets `unreadCount` to `0` and sets `lastReadAt`. It takes no body.

```bash cURL theme={null}
curl -X POST "https://api.vobiz.ai/api/v1/sms/conversations/3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34/read" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"
```

```json Response - 200 OK theme={null}
{ "status": "ok" }
```

Call it when an agent opens the thread in your own UI. An unknown id returns `404 {"error":"conversation not found"}`.

## Unread count

[Unread count](/docs/sms/api/conversations/unread-count) returns the total unread inbound messages across all your conversations - the number for an inbox badge.

```bash cURL theme={null}
curl "https://api.vobiz.ai/api/v1/sms/conversations/unread-count" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"
```

```json Response - 200 OK theme={null}
{ "totalUnread": 4 }
```

## Get replies in real time

Polling the list works for low volumes. For a live inbox, use one of:

* The `message.received` [webhook](/docs/sms/webhooks) event, delivered to your server with the inbound message object (including its `conversationId`).
* The [WebSocket](/docs/sms/websocket), which pushes `message.received` for inbound messages and `message.status` for delivery updates to your outbound messages.

## The console Inbox

In the Vobiz Console, **SMS & RCS → Inbox** shows the same conversations without code. Use **SMS & RCS → Send** to message a contact who has not written to you yet.

## Before you go live

<CardGroup cols={2}>
  <Card title="Messaging numbers" icon="hashtag" href="/docs/sms/numbers">
    The numbers your threads run on.
  </Card>

  <Card title="Compliance overview" icon="shield-check" href="/docs/sms/compliance/overview">
    Register before two-way traffic goes live.
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="SMS" icon="message" href="/docs/sms/channels/sms">
    Two-way messaging and statuses.
  </Card>

  <Card title="Opt-outs" icon="ban" href="/docs/sms/opt-outs">
    Keyword replies that are also recorded as opt-outs.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/sms/webhooks">
    Push inbound messages to your server.
  </Card>

  <Card title="List messages" icon="list" href="/docs/sms/api/messages/list-messages">
    Query messages across all conversations by status, direction, tag or date.
  </Card>
</CardGroup>


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