---
title: "List the notifications sent to your agents"
method: GET
path: "/v1/whatsapp/agents/notifications"
tags: ["whatsapp-agent-notifications"]
---

# List the notifications sent to your agents

`GET /v1/whatsapp/agents/notifications`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/whatsapp/agents/notifications`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Returns the notifications you have sent your agents, newest first, each with what came of it. Filter by `from` for the agent on one business number, by `status` to find the ones the agent skipped or WhatsApp refused, or by `to` to follow one contact. A notification still in flight to WhatsApp is not listed yet.

Page through the full set with the response cursors.

## Query parameters

- `status` 'accepted' | 'success' | 'skipped' | 'failed': Where a notification you sent the agent stands. One state is transient and three are final. - `accepted` means Bird holds the notification: it is on its way to WhatsApp, or WhatsApp is still working on it. Nothing is charged for a notification, unlike a message that reads `accepted`. - `success` means the agent acted on it. - `skipped` means the agent read it and chose to say nothing; `skipped_reason` says why. - `failed` means WhatsApp refused it or reported a failure, or no outcome arrived within a day; `error` says why.
- `from` string
- `to` string
- `limit` integer
- `starting_after` string
- `ending_before` string

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

A page of the notifications sent to your agents.

- WhatsAppAgentNotificationList
  - `data` WhatsAppAgentNotification[], required: A page of the notifications sent to the agent.
    - `id` string, required
    - `from` string, required: The business number whose agent the notification was sent to, in E.164 format.
    - `to` string, required: The contact the notification was about, as you addressed it: a phone number in E.164 format, or a business-scoped user ID.
    - `name` string, required: Your own name for what happened, as you sent it.
    - `description` string, required: What happened, as you sent it.
    - `payload` string, required: The data you attached, as you sent it.
    - `status` 'accepted' | 'success' | 'skipped' | 'failed', required: Where a notification you sent the agent stands. One state is transient and three are final. - `accepted` means Bird holds the notification: it is on its way to WhatsApp, or WhatsApp is still working on it. Nothing is charged for a notification, unlike a message that reads `accepted`. - `success` means the agent acted on it. - `skipped` means the agent read it and chose to say nothing; `skipped_reason` says why. - `failed` means WhatsApp refused it or reported a failure, or no outcome arrived within a day; `error` says why.
    - `skipped_reason` string: WhatsApp's own account of why the agent chose to say nothing, passed through. Present only when `status` is `skipped`. Show it to the person who sent the notification; never match on its text.
    - `error` WhatsAppAgentNotificationError: Why a notification sent to the agent failed.
      - `description` string, required: WhatsApp's own explanation, passed through: what it said when it refused the notification, or its failure summary once it had worked on it. Show it to the person who sent the notification; never match on its text. Carries Bird's own words instead when the failure was Bird's verdict, such as no outcome arriving within a day.
      - `meta_error_code` string, nullable, required: WhatsApp's most specific code when it refused the notification outright: its error subcode where it sent one, otherwise its top-level code. Treat it as an opaque string. Null when WhatsApp took the notification and reported the failure later, which carries no code, and when the failure was Bird's own verdict.
    - `created_at` string, date-time, required: When Bird accepted the notification.
  - `next_cursor` string, nullable, required: Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
  - `prev_cursor` string, nullable, required: Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
  - `refresh_cursor` string, nullable, 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`.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)