Vobiz Messaging API - Conversations

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`	List your conversations, most recently active first.
`GET`	`/conversations/{id}`	Retrieve one conversation with its counters.
`GET`	`/conversations/{id}/messages`	List the messages in one thread, newest first.
`POST`	`/conversations/{id}/read`	Reset `unreadCount` to `0` and set `lastReadAt`.
`GET`	`/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

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"

200 OK

[
  {
    "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), or open the WebSocket, then refresh the affected conversation with GET /conversations/{id}.

Getting Started

API Reference

Guides

Vobiz Messaging API - Conversations

The conversation object

Endpoints

Unread counts

Example

Real-time updates

​The conversation object

​Endpoints

​Unread counts

​Pagination

​Example

​Real-time updates

​Related

The conversation object

Endpoints

Unread counts

Pagination

Example

Real-time updates

Related