whatsapp-agent-notifications

Send an agent a notification

Tells the agent on the from business number that something happened in your systems for one contact, such as a payment landing, an order shipping or an identity check passing. The agent decides whether and how to tell the contact, drawing on description and payload, and may write to them without waiting for their next message.

Bird takes the notification, hands it to WhatsApp in the background and keeps asking WhatsApp what became of it, so this answers 202 with the notification as you sent it at status: accepted. A read in the first moments after the 202 can answer 404 while the hand-off is still in flight. Read it back, or list the notifications, to see it settle: success when the agent acted on it, skipped with WhatsApp's reason when the agent chose to say nothing, or failed with what went wrong. The notification records whether the agent acted on it, not what the agent said to the contact. A from number this workspace has not connected returns 422, one without an agent returns 404, and one whose agent WhatsApp is still preparing returns 409.

post/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

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

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.

Request body

fromstring required

The business phone number whose agent should act on the notification, in E.164 format (for example +13124495648), the same form a message's from takes. It must be a number this workspace has connected and that runs an agent.

tostring required

The contact the notification is about: a phone number in E.164 format (for example +14155551234), or the contact's business-scoped user ID (for example US.13491208655302741918), the same forms a message's to accepts. A phone number is normalized before the call reaches WhatsApp, so spacing does not matter. WhatsApp documents a phone number for this call; a business-scoped user ID is passed through as given.

namestring required

Your own name for what happened, such as payment_received or order_shipped. The agent reads it as the kind of thing that happened, so keep one name per kind. WhatsApp calls this the event type.

descriptionstring required

What happened, in a sentence the agent can tell the contact.

payloadstring required

Details the agent may draw on when it writes to the contact, as one JSON string. WhatsApp passes it to the agent unchanged and does not read it itself.

Example request

{
  "from": "+13124495648",
  "to": "+14155551234",
  "name": "order_shipped",
  "description": "Order 88213 left the warehouse and arrives on Thursday.",
  "payload": "{\"order_id\":\"88213\",\"carrier\":\"ACME Courier\",\"eta\":\"2026-10-02\"}"
}

Response

Bird accepted the notification and will hand it to WhatsApp. The notification reads accepted until WhatsApp has worked on it.

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 2 revisions of this API.