Skip to main content
GET
List conversations
Base URL: https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp Authentication: every request needs the X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: YOUR_AUTH_TOKEN headers, and the {auth_id} in the path must be the account those credentials belong to. Get your credentials from console.vobiz.ai.
A conversation is a thread between one of your WhatsApp channels and one customer contact. Each conversation window lasts 24 hours from when it starts, with a customer message or a template you send. Messages are cursor-paginated - pass the next_cursor from the previous response to fetch the next page of older messages.

List conversations

Returns your inbox threads across all channels, one per channel and contact (the latest conversation of each), most recently active first. Each row carries the contact’s name and number and a preview of the latest message.
cURL
200 OK

Conversation object

string
Unique conversation identifier (UUID). Use it with List messages in a conversation.
string
Your Vobiz account ID (MA_XXXXXXXX).
string
UUID of the channel the conversation belongs to.
string
UUID of the contact on the other side of the conversation.
string
WhatsApp conversation category: service, marketing, utility, or authentication.
boolean
true for a conversation you opened by sending, false for one opened by an inbound message.
string
Conversation start timestamp (RFC3339 UTC).
string
When the conversation window closes (RFC3339 UTC).
string
Conversation state, for example open.
string
The contact’s name. Omitted when unknown.
string
The contact’s phone number.
string
Short preview of the latest message in the thread.
string
When the latest message was sent or received (RFC3339 UTC).

List messages in a conversation

Returns the message history between the conversation’s channel and contact, across all of their conversation windows. The first page holds the newest messages, and each page lists its messages oldest first. To load older messages, pass next_cursor as cursor until has_more is false.
integer
default:"50"
Messages per page, from 1 to 100. Default 50.
string
The next_cursor from the previous page. Returns messages older than it.
200 OK

Message object

string
Unique message identifier (UUID).
string
Your Vobiz account ID (MA_XXXXXXXX).
string
UUID of the channel the message was sent or received on.
string
UUID of the contact the message is with.
string | null
UUID of the conversation the message belongs to.
string
Message direction: inbound or outbound.
string
Message type, e.g. text, template, image, document. Inbound messages can be any WhatsApp message type.
string
Delivery status: pending, sent, delivered, read, or failed. Outbound messages start as pending; inbound messages are delivered.
string
The message as a JSON-encoded string. For outbound messages it is the send request you made; for inbound messages it is the WhatsApp message object. Parse it to read the body and media fields.
string
WhatsApp message ID (wamid…). Status webhooks for this message carry it as statuses[].id.
string | null
Meta’s error code when the message failed, otherwise null.
string | null
Meta’s error detail when the message failed, otherwise null.
string
Message timestamp (RFC3339 UTC).

Authorizations

X-Auth-ID
string
header
required

Your Vobiz account Auth ID (MA_XXXXXXXX).

X-Auth-Token
string
header
required

Your Vobiz account Auth Token.

Path Parameters

auth_id
string
required

Your account Auth ID. It must match the X-Auth-ID header.

Example:

"MA_XXXXXXXX"

Query Parameters

page
integer
default:1

Page number, starting at 1. Defaults to 1.

Required range: x >= 1
limit
integer
default:20

Conversations per page, from 1 to 100. Defaults to 20; a value outside that range also returns 20 conversations.

Required range: 1 <= x <= 100

Return only threads whose contact name or phone number contains this text (case-insensitive).

Example:

"priya"

Response

A page of conversations.

items
object[]
required

Conversations, most recently active first. Empty array when none match.

total
integer
required

Number of conversations that match.

Example:

12

page
integer
required

The page number.

Example:

1

limit
integer
required

The page size.

Example:

20

has_more
boolean
required

Whether another page follows.

Example:

false