Send an agent a notification
/v1/whatsapp/agents/notifications// The agent decides whether and how to tell the contact. The answer reads
// accepted; read it back to see whether the agent acted on it.
const notification = await bird.whatsapp.agents.notifications.create({
from: "+13124495648",
to: "+14155551234",
name: "order_shipped",
description: "Order 88213 left the warehouse and arrives on Thursday.",
payload: JSON.stringify({ order_id: "88213", carrier: "ACME Courier" }),
});
console.log(notification.id, notification.status);# The agent decides whether and how to tell the contact. The answer reads
# accepted; read it back to see whether the agent acted on it.
notification = client.whatsapp.agents.notifications.create(
from_="+13124495648",
to="+14155551234",
name="order_shipped",
description="Order 88213 left the warehouse and arrives on Thursday.",
payload='{"order_id":"88213","carrier":"ACME Courier"}',
)
print(notification.id, notification.status)notification, err := client.Whatsapp.Agents.Notifications.Create(context.Background(), bird.WhatsappAgentsNotificationsCreateParams{
From: "+13124495648",
To: "+14155551234",
Name: "order_shipped",
Description: "Order 88213 left the warehouse and arrives on Thursday.",
Payload: `{"order_id":"88213","carrier":"ACME Courier"}`,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(*notification.Id, *notification.Status)// The agent decides whether and how to tell the contact. The answer reads
// accepted; read it back to see whether the agent acted on it.
$notification = $bird->whatsapp->agents->notifications->create(
(new WhatsAppAgentNotificationCreate())
->setFrom('+13124495648')
->setTo('+14155551234')
->setName('order_shipped')
->setDescription('Order 88213 left the warehouse and arrives on Thursday.')
->setPayload('{"order_id":"88213","carrier":"ACME Courier"}'),
);
echo $notification->getId(), ' ', $notification->getStatus();bird whatsapp agents notifications create \
--description 'Order 88213 left the warehouse and arrives on Thursday.' \
--from +13124495648 \
--name order_shipped \
--payload '{"order_id":"88213","carrier":"ACME Courier","eta":"2026-10-02"}' \
--to +14155551234curl -X POST "https://us1.platform.bird.com/v1/whatsapp/agents/notifications" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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\"}"
}'{
"id": "waan_01krdgeqcxet5s7t44vh8rt9m7",
"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\"}",
"status": "accepted",
"created_at": "2026-10-01T08:00:00Z"
}
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.
Corps de la requête
fromThe 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.
toThe 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.
nameYour 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.
descriptionWhat happened, in a sentence the agent can tell the contact.
payloadDetails 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.
Contenu de la réponse
idUnique identifier for the notification.
fromThe business number whose agent the notification was sent to, in E.164 format.
toThe contact the notification was about, as you addressed it: a phone number in E.164 format, or a business-scoped user ID.
nameYour own name for what happened, as you sent it.
descriptionWhat happened, as you sent it.
payloadThe data you attached, as you sent it.
statusWhere the notification stands. accepted from the moment Bird takes it, then one of the three final states once WhatsApp has answered.
skipped_reasonWhatsApp'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.
errorWhy the notification failed. Present only when status is failed.
Afficher les attributs enfants
error.descriptionWhatsApp'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.
error.meta_error_codeWhatsApp'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_atWhen Bird accepted the notification.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet.