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);
}

conversations = client.whatsapp.conversations.list(
    inbox_status="open", control="bird", assigned_to="unassigned"
)
for conversation in conversations.data or []:
    print(conversation.id, conversation.unread_count)

for conversation, err := range client.Whatsapp.Conversations.List(context.Background(), bird.WhatsappConversationsListParams{
	InboxStatus: "open",
	Control:     "bird",
	AssignedTo:  "unassigned",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(conversation.Id, conversation.UnreadCount)
}

foreach ($bird->whatsapp->conversations->list(['inbox_status' => 'open', 'control' => 'bird', 'assigned_to' => 'unassigned']) as $conversation) {
    echo $conversation->getId(), ' ', $conversation->getUnreadCount(), PHP_EOL;
}

bird whatsapp conversations list

curl -X GET "https://us1.platform.bird.com/v1/whatsapp/conversations" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "assigned_to=unassigned" \
  --url-query "service_window_status=open" \
  --url-query "label=billing" \
  --url-query "limit=25"

प्रतिक्रिया200

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

Query पैरामीटर

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.

Response Payload

data

array of object

आवश्यक

A page of conversations, most recently active first.

चाइल्ड एट्रिब्यूट दिखाएँ

data.id

string

आवश्यक

Conversation ID.

data.business_phone_number

nullable string

आवश्यक

Your WhatsApp business phone number this conversation runs on, in E.164 format. It stays the same when you remove the number and connect it again. Null when Bird holds no phone number for it.

data.recipient

object

आवश्यक

The other side of the conversation: the contact, or the group it takes place in. A group conversation carries group_id and null contact identity fields.

चाइल्ड एट्रिब्यूट दिखाएँ

data.inbox_status

string

आवश्यक

Whether the conversation needs attention in the workspace inbox. Set it to resolved when the work is finished. A new inbound message reopens the same conversation. Changing inbox status preserves message history and does not change the channel's permission to send messages or mark messages read.

Possible values: open, resolved

data.control

string

आवश्यक

Who answers this conversation right now. You take and release control in the dashboard inbox.

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

data.assigned_to

nullable string

आवश्यक

The user this conversation is assigned to. Null when unassigned. Assignment is not rechecked against workspace membership on read, so it can still name a user whose access was removed.

data.service_window

nullable object

आवश्यक

Customer-service window for a contact. Null for group conversations.

चाइल्ड एट्रिब्यूट दिखाएँ

data.service_window.status

string

आवश्यक

Whether the customer-service window is open right now.

open: the contact wrote within the last 24 hours, so free-form messages are accepted.
closed: the window has passed, or the contact has never written, so only a template can be sent.

Possible values: open, closed

data.service_window.ends_at

nullable string

आवश्यक

When the window closes, or closed. Null when no inbound message has been recorded, in which case status is closed.

data.last_message

nullable object

आवश्यक

A pointer to the most recent message in this conversation. It names the message; read its content through the conversation's message list. Null when the conversation has no message yet.

चाइल्ड एट्रिब्यूट दिखाएँ

data.unread_count

integer

आवश्यक

Number of inbound messages the workspace has not acknowledged. Shared across the workspace. Sending a reply does not mark messages read.

data.labels

array of string

आवश्यक

Workspace labels on this conversation. Labels do not change read state or inbox status.

data.created_at

string

आवश्यक

When Bird opened this conversation.

data.updated_at

string

आवश्यक

When this conversation last changed.

next_cursor

nullable string

आवश्यक

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

prev_cursor

nullable string

आवश्यक

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

refresh_cursor

nullable string

आवश्यक

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.

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।

इम्प्लीमेंटेशन ब्रीफ़ पाएँ

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);
}

conversations = client.whatsapp.conversations.list(
    inbox_status="open", control="bird", assigned_to="unassigned"
)
for conversation in conversations.data or []:
    print(conversation.id, conversation.unread_count)

for conversation, err := range client.Whatsapp.Conversations.List(context.Background(), bird.WhatsappConversationsListParams{
	InboxStatus: "open",
	Control:     "bird",
	AssignedTo:  "unassigned",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(conversation.Id, conversation.UnreadCount)
}

foreach ($bird->whatsapp->conversations->list(['inbox_status' => 'open', 'control' => 'bird', 'assigned_to' => 'unassigned']) as $conversation) {
    echo $conversation->getId(), ' ', $conversation->getUnreadCount(), PHP_EOL;
}

bird whatsapp conversations list

curl -X GET "https://us1.platform.bird.com/v1/whatsapp/conversations" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "assigned_to=unassigned" \
  --url-query "service_window_status=open" \
  --url-query "label=billing" \
  --url-query "limit=25"

प्रतिक्रिया200

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

List WhatsApp conversations

Query पैरामीटर

Response Payload

संबंधित संसाधन