GET

List Conversations

Returns a paginated list of conversations in your sub-account.

GEThttps://api.vantaxai.com/v1/conversations

Conversations are returned newest-activity-first (ordered by `last_message_at`). Filter by `channel` and `status`, and use the `limit` and `starting_after` cursor parameters to page through large collections.

Channels

A conversation belongs to exactly one channel. To follow up the same contact on a different channel, look for (or start) a separate conversation on that channel.

Unread filtering

Combine `status=open` with the `unread_count` field on each record to surface threads that still need a human reply.

Headers

Authorizationstringrequired
Bearer authentication with your secret API key.
example: Bearer vx_live_3fa9c2…

Query Parameters

sub_account_idstringrequired
The sub-account to list conversations for.
example: sub_8a1f4c2e
channelstringoptional
Filter to a single messaging channel.
smswhatsappfacebookinstagramemail
example: whatsapp
statusstringoptional
Filter by conversation status.
openpendingclosed
example: open
limitintegeroptional
Number of records to return (1–100). Defaults to 20.
example: 20
starting_afterstringoptional
Cursor for pagination — a conversation id to start after.
example: conv_7b2e9a

Request

curl "https://api.vantaxai.com/v1/conversations?sub_account_id=sub_8a1f4c2e&channel=whatsapp&status=open" \
  -H "Authorization: Bearer vx_live_3fa9c2..."

const params = new URLSearchParams({
  sub_account_id: "sub_8a1f4c2e",
  channel: "whatsapp",
  status: "open",
  limit: "20",
});
const res = await fetch(
  `https://api.vantaxai.com/v1/conversations?${params}`,
  { headers: { Authorization: "Bearer vx_live_3fa9c2..." } }
);
const { data: conversations } = await res.json();

import { Vantax } from "@vantax/sdk";

const vantax = new Vantax({ apiKey: process.env.VANTAX_API_KEY! });
const conversations = await vantax.conversations.list({
  subAccountId: "sub_8a1f4c2e",
  channel: "whatsapp",
  status: "open",
  limit: 20,
});

from vantax import Vantax

vantax = Vantax(api_key=os.environ["VANTAX_API_KEY"])
conversations = vantax.conversations.list(
    sub_account_id="sub_8a1f4c2e",
    channel="whatsapp",
    status="open",
    limit=20,
)

Response

{
  "success": true,
  "data": [
    {
      "id": "conv_7b2e9a",
      "sub_account_id": "sub_8a1f4c2e",
      "channel": "whatsapp",
      "contact_id": "ct_19f3a0",
      "status": "open",
      "tags": ["vip", "billing"],
      "metadata": {
        "source": "campaign_spring_2026"
      },
      "unread_count": 2,
      "last_message_at": "2026-06-10T11:42:00Z",
      "created_at": "2026-06-08T09:15:00Z"
    },
    {
      "id": "conv_3c8d11",
      "sub_account_id": "sub_8a1f4c2e",
      "channel": "sms",
      "contact_id": "ct_44ba72",
      "status": "pending",
      "tags": [],
      "metadata": {},
      "unread_count": 0,
      "last_message_at": "2026-06-09T17:03:00Z",
      "created_at": "2026-06-09T16:58:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 20,
    "has_more": false
  }
}

{
  "success": false,
  "message": "Invalid or revoked API key"
}