Skip to main content
GET
/
api
/
v1
/
messaging
/
conversations
Conversations API
curl --request GET \
  --url https://api.vobiz.ai/api/v1/messaging/conversations
{
  "id": "<string>",
  "account_id": "<string>",
  "channel_id": "<string>",
  "contact_id": "<string>",
  "category": "<string>",
  "is_billable": true,
  "started_at": "<string>",
  "expires_at": "<string>",
  "status": "<string>",
  "conversation_id": "<string>",
  "direction": "<string>",
  "type": "<string>",
  "content": "<string>",
  "meta_message_id": "<string>",
  "created_at": "<string>"
}
Base URL: https://api.vobiz.ai/api/v1/messaging Authentication: every request requires X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: <token> headers (a Authorization: Bearer <JWT> header is also accepted). Send Content-Type: application/json on requests with a body. Get your credentials from console.vobiz.ai.
A conversation is a thread between one of your WhatsApp channels and one customer contact. Messages within a conversation are cursor-paginated - pass the next_cursor from the previous response to fetch the next page of older messages.

​
List conversations

GET https://api.vobiz.ai/api/v1/messaging/conversations
Returns all WhatsApp conversations for your account across all channels.
cURL
curl -X GET \
  "https://api.vobiz.ai/api/v1/messaging/conversations" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}"
200 OK
{
  "items": [
    {
      "id": "c7a1b2d3-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "account_id": "MA_XXXXXXXX",
      "channel_id": "2f8892e1-59b7-40a2-b518-e7a7c31a754d",
      "contact_id": "9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "category": "service",
      "is_billable": true,
      "started_at": "2026-03-17T14:00:00Z",
      "expires_at": "2026-03-18T14:00:00Z",
      "status": "open"
    }
  ]
}

​
Conversation object

​
id
string
Unique conversation identifier (UUID).
​
account_id
string
Your Vobiz account ID (MA_XXXXXXXX).
​
channel_id
string
UUID of the channel the conversation belongs to.
​
contact_id
string
UUID of the contact on the other side of the conversation.
​
category
string
WhatsApp conversation category (e.g. service, marketing, utility, authentication).
​
is_billable
boolean
Whether the conversation is billable under WhatsApp pricing.
​
started_at
string
Conversation start timestamp (RFC3339 UTC).
​
expires_at
string
When the conversation window expires (RFC3339 UTC).
​
status
string
Conversation status: open or closed.

​
List messages in a conversation

GET https://api.vobiz.ai/api/v1/messaging/conversations/{id}/messages
Returns cursor-paginated messages for a specific conversation.
​
limit
integer
default:"50"
Max messages per page. Default 50, maximum 100.
​
cursor
string
Cursor from the previous response (next_cursor) to fetch the next page.
curl -X GET \
  "https://api.vobiz.ai/api/v1/messaging/conversations/c7a1b2d3-4e5f-4a6b-8c9d-0e1f2a3b4c5d/messages?limit=50" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}"
200 OK
{
  "items": [
    {
      "id": "e1d2c3b4-a5f6-4789-90ab-cdef01234567",
      "account_id": "MA_XXXXXXXX",
      "channel_id": "2f8892e1-59b7-40a2-b518-e7a7c31a754d",
      "contact_id": "9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "conversation_id": "c7a1b2d3-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "direction": "outbound",
      "type": "text",
      "status": "read",
      "content": "{\"body\":\"How can I help?\"}",
      "meta_message_id": "wamid.HBgL...",
      "created_at": "2026-03-17T14:20:00Z"
    },
    {
      "id": "f2e3d4c5-b6a7-4890-91bc-def012345678",
      "account_id": "MA_XXXXXXXX",
      "channel_id": "2f8892e1-59b7-40a2-b518-e7a7c31a754d",
      "contact_id": "9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "conversation_id": "c7a1b2d3-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "direction": "inbound",
      "type": "text",
      "status": "delivered",
      "content": "{\"body\":\"Yes, I'd like to proceed.\"}",
      "meta_message_id": "wamid.HBgM...",
      "created_at": "2026-03-17T14:22:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6Im1zZzAwMSJ9"
}

​
Message object

​
id
string
Unique message identifier (UUID).
​
account_id
string
Your Vobiz account ID (MA_XXXXXXXX).
​
channel_id
string
UUID of the channel the message was sent or received on.
​
contact_id
string
UUID of the contact the message is with.
​
conversation_id
string
UUID of the parent conversation. May be omitted for messages not yet tied to a conversation.
​
direction
string
Message direction: inbound or outbound.
​
type
string
Message type, e.g. text, image, document, template.
​
status
string
Delivery status: pending, sent, delivered, read, or failed.
​
content
string
Message payload as a JSON-encoded string (parse it to read the body and media fields).
​
meta_message_id
string
Meta WhatsApp message ID (wamid…), when available.
​
created_at
string
Message timestamp (RFC3339 UTC).