whatsapp-agent-notifications

Get a notification sent to an agent

Returns one notification you sent the agent, with what came of it: accepted while WhatsApp is still working on it, then success, skipped with WhatsApp's reason, or failed with what went wrong. A notification still in flight to WhatsApp is not readable yet, and an id this workspace does not hold returns 404. A notification stays readable after its agent is deleted.

get/v1/whatsapp/agents/notifications/{notification_id}

Request

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

Headers

X-Workspace-Idstring

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

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

The notification.

idstring required
fromstring required

The business number whose agent the notification was sent to, in E.164 format.

tostring required

The contact the notification was about, as you addressed it: a phone number in E.164 format, or a business-scoped user ID.

namestring required

Your own name for what happened, as you sent it.

descriptionstring required

What happened, as you sent it.

payloadstring 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_reasonstring

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.

created_atstring date-time required

When Bird accepted the notification.

Example response

{
  "id": "waan_01krdgeqcxet5s7t44vh8rt9mg",
  "from": "+13124495648",
  "to": "+14155551234",
  "name": "order_shipped",
  "description": "Order 88213 left the warehouse and arrives on Thursday.",
  "payload": "{\"order_id\":\"88213\",\"carrier\":\"ACME Courier\"}",
  "status": "success",
  "skipped_reason": "The contact's conversation is currently held by the business.",
  "error": {
    "description": "Event payload exceeds the maximum size.",
    "meta_error_code": "100"
  },
  "created_at": "2026-10-02T08:00:00Z"
}

Changes

No recorded changes to this operation across all 3 revisions of this API.