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.
Request Payload
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.
Response Payload
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.
created_atWhen Bird accepted the notification.
संबंधित संसाधन
इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।