Vobiz Messaging Conversations and 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, 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.
STOP and other keyword replies are stored in the thread like any other inbound message, and additionally recorded as 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

{
  "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 returns a JSON array of conversation objects ordered by lastMessageAt, newest first. limit defaults to 20 (maximum 100) and offset pages through older threads.

cURL

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"

Response - 200 OK

[
  {
    "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 returns a single object. An unknown id, a malformed id, or a thread that belongs to another account returns 404 {"error":"conversation not found"}.

cURL

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 returns a JSON array of message objects for the thread, in both directions. limit defaults to 50 (maximum 100); use offset for older messages.

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"

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"])

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);
}

Response - 200 OK

[
  {
    "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. To reply, call Send a 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 resets unreadCount to 0 and sets lastReadAt. It takes no body.

cURL

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"

Response - 200 OK

{ "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 returns the total unread inbound messages across all your conversations - the number for an inbox badge.

cURL

curl "https://api.vobiz.ai/api/v1/sms/conversations/unread-count" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"

Response - 200 OK

{ "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 event, delivered to your server with the inbound message object (including its conversationId).
The 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

Messaging numbers

The numbers your threads run on.

Compliance overview

SMS

Two-way messaging and statuses.

Opt-outs

Keyword replies that are also recorded as opt-outs.

Webhooks

Push inbound messages to your server.

List messages

Query messages across all conversations by status, direction, tag or date.

Getting Started

API Reference

Guides

Vobiz Messaging Conversations and Inbox

How conversations are created

The conversation object

List conversations

Get one conversation

Read the messages in a thread

Mark a conversation as read

Unread count

Get replies in real time

The console Inbox

Before you go live

Messaging numbers

Compliance overview

SMS

Opt-outs

Webhooks

List messages

​How conversations are created

​The conversation object

​List conversations

​Get one conversation

​Read the messages in a thread

​Mark a conversation as read

​Unread count

​Get replies in real time

​The console Inbox

​Before you go live

Messaging numbers

Compliance overview

​Related

SMS

Opt-outs

Webhooks

List messages

How conversations are created

The conversation object

List conversations

Get one conversation

Read the messages in a thread

Mark a conversation as read

Unread count

Get replies in real time

The console Inbox

Before you go live

Related