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"

Response200

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

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

required

A page of conversations, most recently active first.

Show child attributes

data.id

string

required

Conversation ID.

data.business_phone_number

nullable string

required

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

required

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.

Show child attributes

data.inbox_status

string

required

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

required

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

required

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

required

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

Show child attributes

data.last_message

nullable object

required

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.

Show child attributes

data.last_message.id

string

required

ID of the message.

data.last_message.direction

string

required

inbound for a message received from the contact, outbound for one your workspace or the agent sent.

Possible values: outbound, inbound

data.last_message.created_at

string

required

The message's created_at: when it was accepted (outbound) or received (inbound). The conversation list is ordered by it. It only moves forward: a message that arrives late and belongs earlier in the conversation does not pull it back.

data.unread_count

integer

required

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

required

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

data.created_at

string

required

When Bird opened this conversation.

data.updated_at

string

required

When this conversation last changed.

next_cursor

nullable string

required

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

prev_cursor

nullable string

required

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

refresh_cursor

nullable string

required

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.

Continue with the documentation, guides and examples for this topic.

Get an implementation brief

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"

Response200

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

Response Payload

Related resources