List WhatsApp conversations
/v1/whatsapp/conversationsconst 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 listcurl -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"{
"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_statusstringFilter by workspace inbox status. Omit to include open and resolved conversations.
Possible values: open, resolved
business_phone_numberstringReturn only conversations on this WhatsApp business phone number, in E.164 format. Omit to cover every number in the workspace.
controlstringReturn 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_tostringReturn 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_statusstringReturn only conversations whose customer-service window is open or closed.
Possible values: open, closed
labelarrayReturn conversations carrying this label. Repeat the parameter to require every supplied label.
qstringReturn 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.
limitintegerMaximum number of items to return per page.
starting_afterstringCursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_beforestringCursor 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
dataA page of conversations, most recently active first.
चाइल्ड एट्रिब्यूट दिखाएँ
data.idConversation ID.
data.business_phone_numberYour 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.recipientThe 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_statusWhether 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.controlWho 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_toThe 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_windowCustomer-service window for a contact. Null for group conversations.
data.last_messageA 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_countNumber of inbound messages the workspace has not acknowledged. Shared across the workspace. Sending a reply does not mark messages read.
data.labelsWorkspace labels on this conversation. Labels do not change read state or inbox status.
data.created_atWhen Bird opened this conversation.
data.updated_atWhen this conversation last changed.
next_cursorCursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.
prev_cursorCursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.
refresh_cursorRefresh 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.
संबंधित संसाधन
इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।