--- title: "List WhatsApp conversations" canonical: "https://bird.com/docs/api/reference/list-whatsapp-conversations" --- # List WhatsApp conversations `GET /v1/whatsapp/conversations` 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](/docs/api/reference/list-whatsapp-conversation-messages). 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. ## Servers - `https://{region}.platform.bird.com`: Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand. - `region`: `us1`, `eu1`. Default: `us1`. The region your organization's data is hosted in. - `https://platform.bird.com`: Region-independent endpoint for authentication and account administration. - `http://localhost:8080`: Local development. ## Authentication Use one authentication option: - `BearerAuth`: HTTP bearer authentication. Pass the API key as a bearer token in the `Authorization` header. Workspace keys use `bk_{region}_*`; organization master keys use `bm_{region}_*`. The prefix identifies the region and selects the API endpoint. Official Bird SDKs and the CLI derive the region from the key. - `CookieAuth`: Send `bird_session` in cookie. Session cookie set after signing in to the Bird dashboard. The cookie value is an opaque session token; no session data is stored in the cookie itself. ## Code samples **TypeScript** ```ts 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); } ``` Examples: [TypeScript](/docs/api/reference/list-whatsapp-conversations.ts.md) · [Python](/docs/api/reference/list-whatsapp-conversations.py.md) · [Go](/docs/api/reference/list-whatsapp-conversations.go.md) · [PHP](/docs/api/reference/list-whatsapp-conversations.php.md) · [CLI](/docs/api/reference/list-whatsapp-conversations.cli.md) · [MCP](/docs/api/reference/list-whatsapp-conversations.mcp.md) · [cURL](/docs/api/reference/list-whatsapp-conversations.curl.md) ## Example response `200` ```json { "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" } ``` ## Query parameters - `inbox_status` (string, optional) Filter by workspace inbox status. Omit to include open and resolved conversations. Possible values: `open`, `resolved` - `business_phone_number` (string, optional): Return only conversations on this WhatsApp business phone number, in E.164 format. Omit to cover every number in the workspace. - `control` (string, optional) 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_to` (string, optional): 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_status` (string, optional) Return only conversations whose customer-service window is `open` or `closed`. Possible values: `open`, `closed` - `label` (array, optional): Return conversations carrying this label. Repeat the parameter to require every supplied label. - `q` (string, optional): 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. - `limit` (integer, optional): Maximum number of items to return per page. - `starting_after` (string, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. - `ending_before` (string, optional): 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. ## Header parameters - `X-Workspace-Id` (string, optional): Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected. - `X-Organization-Id` (string, optional): Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected. ## Response body - `data` (array of object, required): A page of conversations, most recently active first. - `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. - `data.recipient.bsuid` (nullable string, required): Meta's business-scoped user ID for the contact, or null when unknown. - `data.recipient.phone_number` (nullable string, required): Contact phone number in E.164 format, or null when unknown. - `data.recipient.display_name` (nullable string, required): Display name from the contact's WhatsApp profile, or null when none has been recorded. - `data.recipient.username` (nullable string, required): Contact's WhatsApp username without a leading `@`, or null when none has been recorded. Messages cannot be addressed by username. - `data.recipient.group_id` (string): Group this conversation belongs to. Omitted for a conversation with one contact. - `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. - `data.service_window.status` (string, required) 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, required): 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, 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. - `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`. ## Related resources - [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer) - [Build your first integration](/learn/paths/integration) (course) - [Send your first email](/docs/get-started/send-your-first-email) (docs) [Get an implementation brief](/learn/workspace?topic=api-basics)