---
title: "Get a WhatsApp conversation"
canonical: "https://bird.com/docs/api/reference/get-whatsapp-conversation"
---

# Get a WhatsApp conversation

`GET /v1/whatsapp/conversations/{conversation_id}`

Returns one conversation's current state: who answers it right now, when its customer-service window closes, how many messages are unread, its labels, and its most recent message.

Resolving inbox work preserves the conversation. New inbound messages reopen it with the same ID. Messages are retained for 30 days. When the last one expires, the conversation and its events are deleted, and this returns `404`.

## 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 conversation = await bird.whatsapp.conversations.get("wacv_01krdgeqcxet5s7t44vh8rt9mg");
console.log(conversation.control, conversation.assigned_to, conversation.labels);
```

Examples: [TypeScript](/docs/api/reference/get-whatsapp-conversation.ts.md) · [Python](/docs/api/reference/get-whatsapp-conversation.py.md) · [Go](/docs/api/reference/get-whatsapp-conversation.go.md) · [PHP](/docs/api/reference/get-whatsapp-conversation.php.md) · [CLI](/docs/api/reference/get-whatsapp-conversation.cli.md) · [MCP](/docs/api/reference/get-whatsapp-conversation.mcp.md) · [cURL](/docs/api/reference/get-whatsapp-conversation.curl.md)

## Example response `200`

```json
{
  "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"
  ]
}
```

## Path parameters

- `conversation_id` (string, required): Conversation identifier. Starts with `wacv_`.

## 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

- `id` (string, required): Conversation ID.
- `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.
- `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.
- `recipient.bsuid` (nullable string, required): Meta's business-scoped user ID for the contact, or null when unknown.
- `recipient.phone_number` (nullable string, required): Contact phone number in E.164 format, or null when unknown.
- `recipient.display_name` (nullable string, required): Display name from the contact's WhatsApp profile, or null when none has been recorded.
- `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.
- `recipient.group_id` (string): Group this conversation belongs to. Omitted for a conversation with one contact.
- `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`
- `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`
- `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.
- `service_window` (nullable object, required): Customer-service window for a contact. Null for group conversations.
- `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`
- `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`.
- `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.
- `last_message.id` (string, required): ID of the message.
- `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`
- `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.
- `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.
- `labels` (array of string, required): Workspace labels on this conversation. Labels do not change read state or inbox status.
- `created_at` (string, required): When Bird opened this conversation.
- `updated_at` (string, required): When this conversation last changed.

## 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)