--- title: "List WhatsApp conversation events" canonical: "https://bird.com/docs/api/reference/list-whatsapp-conversation-events" --- # List WhatsApp conversation events `GET /v1/whatsapp/conversations/{conversation_id}/events` Returns the conversation's activity history, newest first: - A move of control between the Meta Business Agent and your application. - An assignment, reassignment or unassignment. - A notification sent to the agent about this contact. Messages are listed separately, by [listing the conversation's messages](/docs/api/reference/list-whatsapp-conversation-messages). Pass `type` to keep only events of one type. Events are retained for **30 days** from when they were recorded, so a long-running conversation lists only its recent history. When the conversation's last message passes its own 30-day retention, the conversation is deleted with its remaining events, 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 events = await bird.whatsapp.conversations.listEvents("wacv_01krdgeqcxet5s7t44vh8rt9mg"); for (const event of events.data ?? []) { console.log(event.created_at, event.type, event.summary); } ``` Examples: [TypeScript](/docs/api/reference/list-whatsapp-conversation-events.ts.md) · [Python](/docs/api/reference/list-whatsapp-conversation-events.py.md) · [Go](/docs/api/reference/list-whatsapp-conversation-events.go.md) · [PHP](/docs/api/reference/list-whatsapp-conversation-events.php.md) · [CLI](/docs/api/reference/list-whatsapp-conversation-events.cli.md) · [MCP](/docs/api/reference/list-whatsapp-conversation-events.mcp.md) · [cURL](/docs/api/reference/list-whatsapp-conversation-events.curl.md) ## Example response `200` ```json { "data": [ { "id": "wace_01krdgeqcxet5s7t44vh8rt9mg", "type": "whatsapp_conversation.control_changed", "summary": "Handed to your application by the agent.", "metadata": { "from": "meta_business_agent", "to": "bird", "initiator": "meta_business_agent", "reason": "Customer asked for a person" } } ], "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9", "prev_cursor": null, "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9" } ``` ## Path parameters - `conversation_id` (string, required): Conversation identifier. Starts with `wacv_`. ## Query parameters - `type` (string, optional) Keep only events of this exact type (for example `whatsapp_conversation.control_changed`). Omit for every type. Possible values (may grow over time): `whatsapp_conversation.control_changed`, `whatsapp_conversation.assigned`, `whatsapp_conversation.agent_notified` - `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): Page of conversation events, newest first. - `data.id` (string, required): Event ID. - `data.type` (string, required) Type of conversation event. `whatsapp_conversation.control_changed` records the conversation moving between the Meta Business Agent and your application, `whatsapp_conversation.assigned` records it being assigned, reassigned or unassigned, and `whatsapp_conversation.agent_notified` records a notification sent to the agent about this contact. Open enum: new event types may be added over time, so treat any unrecognized value as a future event rather than an error. The values below are the types known at this version. Possible values (may grow over time): `whatsapp_conversation.control_changed`, `whatsapp_conversation.assigned`, `whatsapp_conversation.agent_notified` - `data.summary` (string, required): Human-readable summary of what happened. - `data.metadata` (object, required): Structured details for the event. `from` and `to` carry the values that changed: the holder (`meta_business_agent` or `bird`) for a control change, the assigned user ID for an assignment, null for no assignee. A control change also carries the `initiator` and, when one was left, the `reason`. An assignment carries `assigned_by`, the actor who made it. An agent notification carries the `agent_notification_id` and its `name`. - `data.created_at` (string, required): When the event happened. - `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)