Sign inGet Started
Mulai sekarang
Panduan
Referensi API
SDK
CLI
Basis Pengetahuan
Changelog

List WhatsApp conversations

GET
/v1/whatsapp/conversations
const conversations = await bird.whatsapp.conversations.list({
  inbox_status: "open",
  control: "bird",
  assigned_to: "unassigned",
});
for (const conversation of conversations.data ?? []) {
  console.log(conversation.id, conversation.unread_count, conversation.service_window?.status);
}
Respons200
{
  "data": [
    {
      "id": "wacv_01krdgeqcxet5s7t44vh8rt9mg",
      "business_phone_number": "+15550001234",
      "recipient": {
        "bsuid": "US.13491208655302741918",
        "phone_number": "+15550001111",
        "display_name": "Jamie Rivera",
        "username": "jamierivera"
      },
      "inbox_status": "open",
      "control": "bird",
      "assigned_to": "usr_01krdgeqcxet5s7t44vh8rt9mg",
      "service_window": {
        "status": "open",
        "ends_at": "2026-09-23T10:35:00Z"
      },
      "last_message": {
        "id": "wam_01krdgeqcxet5s7t44vh8rt9mg",
        "direction": "outbound"
      },
      "labels": [
        "billing",
        "vip"
      ]
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Returns the workspace's WhatsApp conversations as a cursor-paginated list, most recently active first. A conversation is one thread between a number you have connected and a single contact, or a group that number belongs to. It appears once the number has conversations enabled and a first message has been recorded.

Each conversation says who answers it right now, when its customer-service window closes, whether anything in it is unread, and what its most recent message was. Read the messages themselves through the conversation's message list.

Filter by inbox status, connected number, by who holds the conversation, by who it is assigned to, by whether its service window is open, or by label. Search with q to find a contact by any part of their phone number, BSUID, username or display name, or a conversation by part of a label. Callers with whatsapp_management read access also find a group by part of its name.

Resolving a conversation in the inbox preserves its ID and labels. A new inbound message reopens the same conversation. Inbox status is independent of the customer-service window. Messages are retained for 30 days. When a conversation's last message expires, the conversation is deleted and leaves this list. The contact's next message starts a new conversation with a new ID.

Parameter Kueri

inbox_statusstring

Filter by workspace inbox status. Omit to include open and resolved conversations.

Possible values: open, resolved

business_phone_numberstring

Return only conversations on this WhatsApp business phone number, in E.164 format. Omit to cover every number in the workspace.

controlstring

Return only conversations the agent holds (meta_business_agent) or that your workspace holds (bird).

Possible values (may grow over time): bird, meta_business_agent

assigned_tostring

Return conversations assigned to this workspace member. Pass me for the signed-in user or unassigned for conversations without an assignee. An API key cannot use me and receives a 422 response.

service_window_statusstring

Return only conversations whose customer-service window is open or closed.

Possible values: open, closed

labelarray

Return conversations carrying this label. Repeat the parameter to require every supplied label.

qstring

Return only conversations whose contact phone number, BSUID, username, display name, group name or one of its labels contains this text, ignoring case. A phone number matches with or without its +, spaces, dashes, dots or parentheses. A group matches the name it had when its conversation started, and only for callers with whatsapp_management read access. The text cannot contain control characters such as tabs or line breaks.

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

Payload Respons

data
array of object
wajib

A page of conversations, most recently active first.

Tampilkan atribut turunan
next_cursor
nullable string
wajib

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursor
nullable string
wajib

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursor
nullable string
wajib

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.

Dapatkan ringkasan implementasi