--- title: "Send an agent a notification" method: POST path: "/v1/whatsapp/agents/notifications" tags: ["whatsapp-agent-notifications"] --- # Send an agent a notification `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` 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`. ## Headers - `Idempotency-Key` string - `X-Workspace-Id` string - `X-Organization-Id` string ## Request body - WhatsAppAgentNotificationCreate: Something that happened in your systems that the agent should tell the contact about, such as a payment landing or an order shipping. WhatsApp processes it in the background, so read the notification back for what came of it. - `from` string, 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. - `to` string, 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. - `name` string, 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. - `description` string, required: What happened, in a sentence the agent can tell the contact. - `payload` string, 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. ## Response `202` Bird accepted the notification and will hand it to WhatsApp. The notification reads `accepted` until WhatsApp has worked on it. - WhatsAppAgentNotification: A notification you sent the agent about one contact, and what came of it. The agent decides whether to write to the contact about it; that message, if any, shows up on the contact's conversation. - `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. ## Other responses - `400`: Bad request - `401`: Authentication required - `403`: Insufficient permissions - `404`: Resource not found - `409`: Resource conflict - `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 - `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation. --- [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/3e2a50466454?raw)