Conversations API

GET

api

messaging

conversations

Conversations API

curl --request GET \
  --url https://api.vobiz.ai/api/v1/messaging/conversations \
  --header 'X-Auth-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Auth-Token': '<api-key>'}};

fetch('https://api.vobiz.ai/api/v1/messaging/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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

string

Unique conversation identifier (UUID).

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 (e.g. service, marketing, utility, authentication).

boolean

Whether the conversation is billable under WhatsApp pricing.

string

Conversation start timestamp (RFC3339 UTC).

string

When the conversation window expires (RFC3339 UTC).

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.

integer

default:"50"

Max messages per page. Default 50, maximum 100.

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}"

curl -X GET \
  "https://api.vobiz.ai/api/v1/messaging/conversations/c7a1b2d3-4e5f-4a6b-8c9d-0e1f2a3b4c5d/messages?limit=50&cursor=eyJpZCI6Im1zZzAwMSJ9" \
  -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

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

UUID of the parent conversation. May be omitted for messages not yet tied to a conversation.

string

Message direction: inbound or outbound.

string

Message type, e.g. text, image, document, template.

string

Delivery status: pending, sent, delivered, read, or failed.

string

Message payload as a JSON-encoded string (parse it to read the body and media fields).

string

Meta WhatsApp message ID (wamid…), when available.

string

Message timestamp (RFC3339 UTC).

Conversations API

curl --request GET \
  --url https://api.vobiz.ai/api/v1/messaging/conversations \
  --header 'X-Auth-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Auth-Token': '<api-key>'}};

fetch('https://api.vobiz.ai/api/v1/messaging/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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>"
}

​List conversations

​Conversation object

​List messages in a conversation

​Message object

List conversations

Conversation object

List messages in a conversation

Message object