Test a webhook with a sample event
POST
/v1/webhooks/{webhook_id}/test
const result = await bird.webhooks.test("whk_01krdgeqcxet5s7t44vh8rt9mg", {
event_type: "email.delivered",
});
console.log(result.status);result = client.webhooks.test(
"whk_01krdgeqcxet5s7t44vh8rt9mg",
event_type="email.delivered",
)
print(result.status)result, err := client.Webhooks.Test(context.Background(), "whk_123", bird.WebhooksTestParams{
EventType: bird.Ptr("email.delivered"),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(result.Status)$result = $bird->webhooks->test(
'whk_01krdgeqcxet5s7t44vh8rt9mg',
(new WebhookTestRequest())->setEventType('email.delivered'),
);
echo $result->getStatus();bird webhooks test <webhook-id> --event-type email.deliveredcurl -X POST "https://us1.platform.bird.com/v1/webhooks/{webhook_id}/test" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"event_type": "email.delivered"
}'Réponse200
{
"status": "delivered",
"response_status_code": 200,
"response_body": "OK",
"response_duration_ms": 142,
"event_payload": {
"type": "domain.failed",
"timestamp": "2026-05-21T12:00:00Z",
"data": {
"domain_id": "dom_01krdgeqcxet5s7t44vh8rt9mg",
"domain": "mail.example.com",
"workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
"failure_reason": "DKIM record not found at the expected selector."
}
},
"error": "connection refused"
}
Sends a signed synthetic event and returns whether your endpoint accepted it, its HTTP status, and the round-trip latency. An unreachable endpoint returns status: failed in the response body. The endpoint has 10 seconds to respond.
The body is a minimal JSON object with the event type, signed like a real delivery. It does not mirror that event's payload. Tests work on paused endpoints and do not appear in List delivery attempts.
The operation returns 412 if the endpoint lacks a valid signing secret or, when event_type is omitted, has no subscribed event type to use.
Paramètres
webhook_id
string
ID of the webhook endpoint (whk_ prefix), as returned when it was created.
Corps de la requête
event_type
string
Event type to simulate. Any type from the event catalog is accepted, whether or not the endpoint subscribes to it; an unknown type returns a 422. When omitted, the endpoint's first subscribed event type is used.
Contenu de la réponse
status
string
obligatoire
Whether your endpoint accepted the test event. delivered means it returned a 2xx status; failed means it returned a non-2xx status or could not be reached (see error for the latter).
Possible values: delivered, failed
response_status_code
nullable integer
obligatoire
HTTP status returned by your endpoint. Null when no response was received (timeout, connection error, DNS failure).
response_body
string
Response body returned by your endpoint, truncated to the first 1024 bytes. Omitted when your endpoint returned no body or could not be reached.
response_duration_ms
integer
obligatoire
Round-trip delivery latency in milliseconds.
event_payload
object
The full event body delivered to your endpoint. Test sends use a minimal synthetic body rather than a full event payload, so this field is omitted.
Afficher les attributs enfants
A sending domain failed DNS verification.
event_payload.type
string
obligatoire
Event type.
Possible values: domain.failed
event_payload.timestamp
string
obligatoire
When the event occurred.
event_payload.data
object
obligatoire
Payload of the domain.failed event.
Afficher les attributs enfants
event_payload.data.domain_id
string
obligatoire
The sending domain resource whose verification failed.
event_payload.data.domain
string
obligatoire
The sending domain hostname.
event_payload.data.workspace_id
string
obligatoire
The workspace the domain is assigned to.
event_payload.data.failure_reason
nullable string
Why verification failed, when a specific reason is available (for example, the DKIM record was not found at the expected selector).
A sending domain completed DNS verification successfully.
event_payload.type
string
obligatoire
Event type.
Possible values: domain.verified
event_payload.timestamp
string
obligatoire
When the event occurred.
event_payload.data
object
obligatoire
Payload of the domain.verified event.
Afficher les attributs enfants
event_payload.data.domain_id
string
obligatoire
The sending domain resource that verified.
event_payload.data.domain
string
obligatoire
The sending domain hostname.
event_payload.data.workspace_id
string
obligatoire
The workspace the domain is assigned to.
The API accepted the email send and is preparing it for delivery. Fires once per requested recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.accepted
event_payload.timestamp
string
obligatoire
Time the API accepted the send.
event_payload.data
object
obligatoire
Payload of the email.accepted event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
An outbound email permanently failed at the recipient's mail server. Fires once per recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.bounced
event_payload.timestamp
string
obligatoire
Time the bounce was recorded.
event_payload.data
object
obligatoire
Payload of the email.bounced event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
event_payload.data.bounce_type
string
obligatoire
Bounce classification.
- hard: A permanent failure, such as an invalid address or a domain that does not exist.
- soft: A transient failure, such as a full mailbox or a server that is temporarily unavailable.
- block: The receiving mail server refused the sending IP on reputation grounds.
- admin: An administrative refusal, such as relaying denied or a blocklisted domain.
- undetermined: The receiving server's response was ambiguous.
Possible values: hard, soft, undetermined, admin, block
event_payload.data.bounce_class
nullable integer
obligatoire
Numeric bounce classification for fine-grained deliverability triage, or null when the receiving server's response could not be classified. Lets you distinguish, for example, a DNS failure from a spam block when both would be bounce_type: soft or bounce_type: block.
event_payload.data.bounce_code
nullable string
obligatoire
SMTP reply code returned by the receiving mail server, or null when none was provided.
event_payload.data.bounce_description
nullable string
obligatoire
Human-readable reason the receiving mail server gave for the bounce, or null when none was provided.
event_payload.data.sending_ip
nullable string
obligatoire
The IP address used to send this message, or null when it is not known.
A scheduled send was canceled before it fired. Fires once for each message regardless of its recipient count.
event_payload.type
string
obligatoire
Event type.
Possible values: email.canceled
event_payload.timestamp
string
obligatoire
Time the scheduled send was canceled.
event_payload.data
object
obligatoire
Payload of the email.canceled event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on the event so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on the event so you can correlate events with your own records. Null when the send carried no metadata.
The recipient clicked a tracked link in the email. May fire more than once per recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.clicked
event_payload.timestamp
string
obligatoire
Time the click was recorded.
event_payload.data
object
obligatoire
Payload of the email.clicked event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
event_payload.data.url
string
obligatoire
The URL the recipient clicked.
event_payload.data.ip_address
nullable string
obligatoire
IP address of the client that clicked the link, or null when it is not known.
event_payload.data.user_agent
nullable string
obligatoire
User-agent string of the client that clicked the link, or null when it is not known.
The recipient marked the email as spam through their mailbox provider's feedback loop. Fires once per recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.complained
event_payload.timestamp
string
obligatoire
Time the complaint was recorded.
event_payload.data
object
obligatoire
Payload of the email.complained event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
event_payload.data.feedback_type
nullable string
obligatoire
The kind of feedback the mailbox provider reported (such as abuse or fraud), or null when the provider did not specify one.
The recipient's mail server temporarily refused the email. Delivery remains pending and is retried. May fire more than once per recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.deferred
event_payload.timestamp
string
obligatoire
Time the deferral was recorded.
event_payload.data
object
obligatoire
Payload of the email.deferred event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
event_payload.data.bounce_type
string
obligatoire
Bounce classification.
- hard: A permanent failure, such as an invalid address or a domain that does not exist.
- soft: A transient failure, such as a full mailbox or a server that is temporarily unavailable.
- block: The receiving mail server refused the sending IP on reputation grounds.
- admin: An administrative refusal, such as relaying denied or a blocklisted domain.
- undetermined: The receiving server's response was ambiguous.
Possible values: hard, soft, undetermined, admin, block
event_payload.data.bounce_class
nullable integer
obligatoire
Numeric bounce classification for fine-grained deliverability triage, or null when the receiving server's response could not be classified. Distinguishes, for example, a greylisting deferral from a full mailbox.
event_payload.data.defer_reason
nullable string
obligatoire
Human-readable reason the receiving mail server gave for the deferral, or null when none was provided.
event_payload.data.sending_ip
nullable string
obligatoire
The IP address used to send this message, or null when it is not known.
An outbound email reached the recipient's mail server and was accepted.
event_payload.type
string
obligatoire
Event type.
Possible values: email.delivered
event_payload.timestamp
string
obligatoire
Time the recipient's mail server accepted the message.
event_payload.data
object
obligatoire
Payload of the email.delivered event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
Recipient unsubscribed via the RFC 8058 one-click List-Unsubscribe mechanism. Fires once per recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.list_unsubscribed
event_payload.timestamp
string
obligatoire
Time the unsubscribe was recorded.
event_payload.data
object
obligatoire
Payload of the email.list_unsubscribed event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
The recipient opened the email (the tracking pixel was loaded). May fire more than once per recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.opened
event_payload.timestamp
string
obligatoire
Time the open was recorded.
event_payload.data
object
obligatoire
Payload of the email.opened event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
event_payload.data.ip_address
nullable string
obligatoire
IP address of the client that opened the email, or null when it is not known.
event_payload.data.user_agent
nullable string
obligatoire
User-agent string of the client that opened the email, or null when it is not known.
A bounce notification arrived after the message had already been accepted for delivery. Fires once per recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.out_of_band_bounce
event_payload.timestamp
string
obligatoire
Time the bounce notification was recorded.
event_payload.data
object
obligatoire
Payload of the email.out_of_band_bounce event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
event_payload.data.bounce_type
string
obligatoire
Bounce classification.
- hard: A permanent failure, such as an invalid address or a domain that does not exist.
- soft: A transient failure, such as a full mailbox or a server that is temporarily unavailable.
- block: The receiving mail server refused the sending IP on reputation grounds.
- admin: An administrative refusal, such as relaying denied or a blocklisted domain.
- undetermined: The receiving server's response was ambiguous.
Possible values: hard, soft, undetermined, admin, block
event_payload.data.bounce_class
nullable integer
obligatoire
Numeric bounce classification for fine-grained deliverability triage, or null when the receiving server's response could not be classified.
event_payload.data.bounce_code
nullable string
obligatoire
SMTP reply code returned by the receiving mail server, or null when none was provided.
event_payload.data.bounce_description
nullable string
obligatoire
Human-readable reason the receiving mail server gave for the bounce, or null when none was provided.
event_payload.data.sending_ip
nullable string
obligatoire
The IP address used to send this message, or null when it is not known.
The API prepared the message for delivery to the recipient's mail server. Fires once per recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.processed
event_payload.timestamp
string
obligatoire
Time the message was prepared for delivery.
event_payload.data
object
obligatoire
Payload of the email.processed event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
The API received and parsed an inbound email. The payload carries the message's identifiers, sender and recipients, subject, threading reference, and authentication results, which is enough to route and triage without a fetch. Fetch content separately. Get the parsed body with GET /v1/email/inbound-messages/{id}/body. Get the original MIME with GET /v1/email/inbound-messages/{id}/raw. Get attachment bytes with GET /v1/email/inbound-messages/{id}/attachments/{attachment_id}.
event_payload.type
string
obligatoire
Event type.
Possible values: email.received
event_payload.timestamp
string
obligatoire
When the API received the message.
event_payload.data
object
obligatoire
Payload of the email.received event.
Afficher les attributs enfants
event_payload.data.inbound_message_id
string
obligatoire
ID of the received email. Fetch its parsed metadata with GET /v1/email/inbound-messages/{id}, and its content from that message's /body, /raw, and /attachments sub-resources.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.message_id
nullable string
obligatoire
RFC 5322 Message-ID header from the sender, or null when the sender did not include one.
event_payload.data.from
string
obligatoire
Address from the message's From header, with the relay's parsed sender and then the SMTP envelope sender as fallbacks when that header cannot be read. This field alone does not authenticate the sender.
event_payload.data.to
array of string
obligatoire
Parsed recipient addresses from the message headers, not the envelope recipient used to route this delivery.
event_payload.data.subject
nullable string
obligatoire
Subject line as received, or null when the message had no subject.
event_payload.data.in_reply_to
nullable string
In-Reply-To header containing the Message-ID this message replies to, or null when it is not a reply.
event_payload.data.authentication
nullable string
DMARC result for the domain in the received message's From header.
- pass: SPF or DKIM passed and aligned with that domain.
- fail: DMARC was evaluated and did not pass.
- unknown: no trustworthy verdict is available.
This follows dmarc_pass and does not verify a particular person. The receiving provider currently supplies no DMARC result, so received messages report unknown.
Possible values: pass, fail, unknown, null
event_payload.data.spf_pass
nullable boolean
Whether the receiving provider reports that SPF authorized the envelope sender for the sending server. A soft failure is false. Missing, neutral and inconclusive results are null.
event_payload.data.dkim_pass
nullable boolean
Whether the receiving provider verified a DKIM signature. A passing signature makes this true even when another signature fails. Missing signatures and inconclusive verification results are null.
event_payload.data.dmarc_pass
nullable boolean
Whether SPF or DKIM passed and aligned with the domain in the message's From header. The receiving provider currently supplies no DMARC result, so this is null.
event_payload.data.spam_score
nullable number
Content spam score when available. The receiving provider currently supplies no score, so this is null.
The API rejected the email before delivery because of suppression, transmission failure, content, or policy. Fires once per recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.rejected
event_payload.timestamp
string
obligatoire
Time the rejection was recorded.
event_payload.data
object
obligatoire
Payload of the email.rejected event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
event_payload.data.rejection_reason
string
obligatoire
Why an email was rejected before delivery.
- recipient_suppressed: The recipient is on the workspace suppression list, so delivery was never attempted.
- transmission_failed: The message could not be transmitted for delivery.
- generation_failure: The message could not be built for delivery (template or content issue).
- policy_rejection: The message was refused by sending policy.
- domain_unverified: The sending domain was not verified.
- quota_exceeded: The organization's send quota was reached.
- recipient_not_allowed: A recipient was not permitted for this send (for shared onboarding-domain sends, recipients must be verified workspace members).
Possible values: recipient_suppressed, transmission_failed, generation_failure, policy_rejection, domain_unverified, quota_exceeded, recipient_not_allowed
The API accepted an email scheduled for a future time. Fires once per message when the schedule is created.
event_payload.type
string
obligatoire
Event type.
Possible values: email.scheduled
event_payload.timestamp
string
obligatoire
Time the send was scheduled.
event_payload.data
object
obligatoire
Payload of the email.scheduled event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on the event so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on the event so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.scheduled_at
string
obligatoire
When the message is scheduled to send.
Recipient unsubscribed by clicking a tracked unsubscribe link in the email. Fires once per recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: email.unsubscribed
event_payload.timestamp
string
obligatoire
Time the unsubscribe was recorded.
event_payload.data
object
obligatoire
Payload of the email.unsubscribed event.
Afficher les attributs enfants
event_payload.data.email_id
string
obligatoire
ID of the email send.
event_payload.data.recipient_id
string
obligatoire
ID of the recipient.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.recipient
string
obligatoire
Recipient address as it appeared on the envelope.
event_payload.data.recipient_role
string
obligatoire
Envelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the send so you can route and correlate without an extra lookup. Null when the send carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the send so you can correlate events with your own records. Null when the send carried no metadata.
event_payload.data.broadcast_id
nullable string
obligatoire
The broadcast this send went out as part of, echoed on every per-recipient event for the send so you can attribute engagement to the broadcast without an extra lookup. Null when the send was not part of a broadcast. On email.unsubscribed and email.list_unsubscribed, null can also mean the recipient used an unsubscribe link that names no broadcast, so on those two events null does not rule a broadcast out.
Every recipient of a mailbox message reached a delivered state. This event fires once per message. The same send also emits one email.delivered event for each recipient. Choose one event family for each automation and deduplicate mailbox events by message_id.
event_payload.type
string
obligatoire
Event type.
Possible values: email_mailbox.message_delivered
event_payload.timestamp
string
obligatoire
When the event occurred.
event_payload.data
object
obligatoire
Payload of the email_mailbox.message_delivered event.
Afficher les attributs enfants
event_payload.data.message_id
string
obligatoire
ID of the delivered message. Per-recipient email.* events use this value as email_id. Use it to deduplicate events when you subscribe to both event families.
event_payload.data.mailbox_id
string
obligatoire
ID of the mailbox the message was sent from.
event_payload.data.thread_id
string
obligatoire
ID of the thread the message belongs to.
A mailbox message reached a terminal delivery failure. This event fires once per message. The same send also emits per-recipient email.* events. Choose one event family for each automation and deduplicate mailbox events by message_id.
event_payload.type
string
obligatoire
Event type.
Possible values: email_mailbox.message_failed
event_payload.timestamp
string
obligatoire
When the event occurred.
event_payload.data
object
obligatoire
Payload of the email_mailbox.message_failed event.
Afficher les attributs enfants
event_payload.data.message_id
string
obligatoire
ID of the failed message. Per-recipient email.* events use this value as email_id. Use it to deduplicate events when you subscribe to both event families.
event_payload.data.mailbox_id
string
obligatoire
ID of the mailbox the message was sent from.
event_payload.data.thread_id
string
obligatoire
ID of the thread the message belongs to.
event_payload.data.reason
string
obligatoire
Why the message reached a terminal delivery failure.
An email arrived in a mailbox. The same message also emits an email.received event. The two events can arrive in either order. Choose one event family for each automation and deduplicate mailbox events by message_id.
event_payload.type
string
obligatoire
Event type.
Possible values: email_mailbox.message_received
event_payload.timestamp
string
obligatoire
When the event occurred.
event_payload.data
object
obligatoire
Identifiers, threading details, authentication results, and extracted text for a received mailbox message. The thread-message endpoints provide the original source during its 30-day retention window.
Afficher les attributs enfants
event_payload.data.message_id
string
obligatoire
ID of the received message. The corresponding email.received event uses this value as inbound_message_id. Use it to deduplicate events when you subscribe to both event families.
event_payload.data.mailbox_id
string
obligatoire
ID of the mailbox that received the message.
event_payload.data.thread_id
string
obligatoire
ID of the thread the message was filed into.
event_payload.data.route_id
nullable string
ID (ein_…) of the explicit inbound route that matched, or null when the message was delivered by the virtual exact-address route.
event_payload.data.from
string
obligatoire
Envelope-from address.
event_payload.data.to
array of string
obligatoire
Recipient addresses the message was sent to.
event_payload.data.subject
nullable string
obligatoire
Subject line as received, or null when the message had no subject.
event_payload.data.extracted_text
nullable string
Plain-text body with quoted history removed, capped at 64 KB. See truncated_text to check whether the value was truncated. Null when extraction produces no text.
event_payload.data.truncated_text
boolean
True when extracted_text was truncated to the 64 KB cap. Fetch the full text through the thread-member endpoint.
event_payload.data.attachment_count
integer
obligatoire
Number of attachments on the message. Attachment content remains available for the mailbox's retention tier.
event_payload.data.authentication
nullable string
DMARC result for the domain in the received message's From header.
- pass: SPF or DKIM passed and aligned with that domain.
- fail: DMARC was evaluated and did not pass.
- unknown: no trustworthy verdict is available.
This follows dmarc_pass and does not verify a particular person. The receiving provider currently supplies no DMARC result, so received messages report unknown.
Possible values: pass, fail, unknown, null
event_payload.data.spf_pass
nullable boolean
Whether the receiving provider reports that SPF authorized the envelope sender for the sending server. A soft failure is false. Missing, neutral and inconclusive results are null.
event_payload.data.dkim_pass
nullable boolean
Whether the receiving provider verified a DKIM signature. A passing signature makes this true even when another signature fails. Missing signatures and inconclusive verification results are null.
event_payload.data.dmarc_pass
nullable boolean
Whether SPF or DKIM passed and aligned with the domain in the message's From header. The receiving provider currently supplies no DMARC result, so this is null.
A mailbox message was handed off for delivery. This event fires once per message. The same send also emits per-recipient email.* events. Choose one event family for each automation and deduplicate mailbox events by message_id.
event_payload.type
string
obligatoire
Event type.
Possible values: email_mailbox.message_sent
event_payload.timestamp
string
obligatoire
When the event occurred.
event_payload.data
object
obligatoire
Payload of the email_mailbox.message_sent event.
Afficher les attributs enfants
event_payload.data.message_id
string
obligatoire
ID of the sent message. Per-recipient email.* events use this value as email_id. Use it to deduplicate events when you subscribe to both event families.
event_payload.data.mailbox_id
string
obligatoire
ID of the mailbox the message was sent from.
event_payload.data.thread_id
string
obligatoire
ID of the thread the message belongs to.
This mailbox-suspension event is reserved and is not currently emitted.
event_payload.type
string
obligatoire
Event type.
Possible values: email_mailbox.suspended
event_payload.timestamp
string
obligatoire
When the event occurred.
event_payload.data
object
obligatoire
Payload of the email_mailbox.suspended event.
Afficher les attributs enfants
event_payload.data.mailbox_id
string
obligatoire
ID of the suspended mailbox.
event_payload.data.reason
string
obligatoire
Why the mailbox was suspended.
A new thread was created in a mailbox, from either direction.
event_payload.type
string
obligatoire
Event type.
Possible values: email_mailbox.thread_created
event_payload.timestamp
string
obligatoire
When the event occurred.
event_payload.data
object
obligatoire
Payload of the email_mailbox.thread_created event.
Afficher les attributs enfants
event_payload.data.thread_id
string
obligatoire
ID of the thread.
event_payload.data.mailbox_id
string
obligatoire
ID of the mailbox the thread was created in.
event_payload.data.subject
nullable string
obligatoire
Subject of the first message in the thread, or null when it had none.
event_payload.data.initiated_by
string
obligatoire
Which direction created the thread.
Possible values: inbound, outbound
An email address was added to the workspace's suppression list (manually, via complaint, or via hard bounce).
event_payload.type
string
obligatoire
Event type.
Possible values: email_suppression.created
event_payload.timestamp
string
obligatoire
When the event occurred.
event_payload.data
object
obligatoire
Payload of the email_suppression.created event.
Afficher les attributs enfants
event_payload.data.suppression_id
string
obligatoire
The suppression entry that was created.
event_payload.data.email
string
obligatoire
The recipient address that was added to the suppression list.
event_payload.data.reason
string
obligatoire
Why the address was suppressed. New values may be added over time; treat unknown values as informational.
Possible values (may grow over time): hard_bounce, complaint, unsubscribe, manual
event_payload.data.workspace_id
string
obligatoire
The workspace the suppression belongs to.
A stated preference was deleted, superseding it in the ledger without erasing its history.
event_payload.type
string
obligatoire
Always preference.deleted for this event.
Possible values: preference.deleted
event_payload.timestamp
string
obligatoire
When the delete took effect (effective_at), not when it was recorded.
event_payload.data
object
obligatoire
Payload of the preference.deleted event.
Afficher les attributs enfants
event_payload.data.preference_id
string
obligatoire
The preference key this write applied to.
event_payload.data.transition_id
string
obligatoire
The ledger entry this write appended.
event_payload.data.channel
string
obligatoire
event_payload.data.handle
string
obligatoire
Who the statement is about: an email address on the email channel, a phone number in E.164 format on SMS and WhatsApp.
event_payload.data.sender_scope
nullable string
obligatoire
The sender the statement is limited to, or null when it covers the whole channel. Present-with-null on every payload of this type: it is part of the key alongside topic_id, and pinning its presence keeps a subscriber from ever learning (handle, channel) as the unique key.
event_payload.data.topic_id
nullable string
obligatoire
The topic the statement is limited to, or null when it covers every topic. Reserved: always null in v1. Present-with-null for the same reason as sender_scope.
event_payload.data.coverage
string
obligatoire
event_payload.data.contact_id
nullable string
obligatoire
The contact whose handle matched when the statement was recorded. Null when no contact matched at that moment.
A stated preference was granted (a person consented, or a customer wrote a grant) and became the key's live statement.
event_payload.type
string
obligatoire
Always preference.granted for this event.
Possible values: preference.granted
event_payload.timestamp
string
obligatoire
When the statement took effect (effective_at), not when it was recorded.
event_payload.data
object
obligatoire
Payload of the preference.granted event.
Afficher les attributs enfants
event_payload.data.preference_id
string
obligatoire
The preference key this write applied to.
event_payload.data.transition_id
string
obligatoire
The ledger entry this write appended.
event_payload.data.channel
string
obligatoire
event_payload.data.handle
string
obligatoire
Who the statement is about: an email address on the email channel, a phone number in E.164 format on SMS and WhatsApp.
event_payload.data.sender_scope
nullable string
obligatoire
The sender the statement is limited to, or null when it covers the whole channel. Present-with-null on every payload of this type: it is part of the key alongside topic_id, and pinning its presence keeps a subscriber from ever learning (handle, channel) as the unique key.
event_payload.data.topic_id
nullable string
obligatoire
The topic the statement is limited to, or null when it covers every topic. Reserved: always null in v1. Present-with-null for the same reason as sender_scope.
event_payload.data.coverage
string
obligatoire
event_payload.data.contact_id
nullable string
obligatoire
The contact whose handle matched when the statement was recorded. Null when no contact matched at that moment.
A stated preference was revoked (a person opted out, or a customer wrote a revoke) and became the key's live statement.
event_payload.type
string
obligatoire
Always preference.revoked for this event.
Possible values: preference.revoked
event_payload.timestamp
string
obligatoire
When the statement took effect (effective_at), not when it was recorded.
event_payload.data
object
obligatoire
Payload of the preference.revoked event.
Afficher les attributs enfants
event_payload.data.preference_id
string
obligatoire
The preference key this write applied to.
event_payload.data.transition_id
string
obligatoire
The ledger entry this write appended.
event_payload.data.channel
string
obligatoire
event_payload.data.handle
string
obligatoire
Who the statement is about: an email address on the email channel, a phone number in E.164 format on SMS and WhatsApp.
event_payload.data.sender_scope
nullable string
obligatoire
The sender the statement is limited to, or null when it covers the whole channel. Present-with-null on every payload of this type: it is part of the key alongside topic_id, and pinning its presence keeps a subscriber from ever learning (handle, channel) as the unique key.
event_payload.data.topic_id
nullable string
obligatoire
The topic the statement is limited to, or null when it covers every topic. Reserved: always null in v1. Present-with-null for the same reason as sender_scope.
event_payload.data.coverage
string
obligatoire
event_payload.data.contact_id
nullable string
obligatoire
The contact whose handle matched when the statement was recorded. Null when no contact matched at that moment.
The API accepted the SMS send request and queued it for processing.
event_payload.type
string
obligatoire
Event type.
Possible values: sms.accepted
event_payload.timestamp
string
obligatoire
Time the API accepted the request.
event_payload.data
object
obligatoire
Payload of the sms.accepted event.
Afficher les attributs enfants
event_payload.data.sms_id
string
obligatoire
ID of the SMS message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
string
obligatoire
Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.
event_payload.data.from
string
obligatoire
Where the message came from. On an outbound message this is the sender you sent it from: an E.164 number, an alphanumeric sender ID, or a short code. On an inbound one it is the phone number that sent it to you.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
event_payload.data.requested_language
nullable string
obligatoire
The template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_language
nullable string
obligatoire
The template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_id
nullable string
obligatoire
The template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_id
nullable string
obligatoire
The workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.
event_payload.data.template_content_hash
nullable string
obligatoire
The rendered language's source fingerprint, or null for a free-text message.
event_payload.data.cost
nullable object
Message cost as of this event, split into the platform charge and any
third-party fees passed through. Null on an event that priced nothing.
Components are named so you can merge them per component rather than replacing the
object: webhook delivery is not ordered, so an older event arriving late would
otherwise overwrite a newer figure. Take the latest occurred_at you have seen for
each component. amount is the sum of the components in this payload and does not
represent a settled total.
Afficher les attributs enfants
event_payload.data.cost.amount
string
obligatoire
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
event_payload.data.cost.currency_code
string
obligatoire
ISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amount
nullable string
obligatoire
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.cost.passthrough_amount
nullable string
obligatoire
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.segments
object
obligatoire
Segment breakdown used to calculate the message charge.
Afficher les attributs enfants
event_payload.data.segments.count
integer
obligatoire
Number of segments the body is split into. Each segment is a billable unit.
event_payload.data.segments.encoding
string
obligatoire
Encoding used for the body. The GSM_7BIT encoding fits 160 septets
(seven-bit units) in one segment, or 153 per part in a multi-segment
message. The UCS2 encoding applies when the body contains a character
outside the GSM 03.38 alphabet, including emoji, CJK, and some accented
characters. It fits 70 UTF-16 code units in one segment, or 67 per part.
Neither limit counts characters, and both alphabets have characters that
cost two units. Under GSM_7BIT there are ten such entries, and they are
the whole set: ^, {, }, \, [, ], ~, |, €, and the form
feed control. Eighty of those fill a single segment. Under UCS2 an emoji
outside the Basic Multilingual Plane is a surrogate pair costing two code
units, so 35 of those fill a single segment.
Possible values: GSM_7BIT, UCS2
event_payload.data.segments.characters
integer
obligatoire
Character count of the body, counted in Unicode code points under either encoding. This is not the segment measure: a GSM_7BIT extended-table character counts once here but costs two septets, and a UCS2 emoji outside the Basic Multilingual Plane counts once here but costs two of the segment's 70 code units.
The carrier confirmed delivery of the message to the recipient handset.
event_payload.type
string
obligatoire
Event type.
Possible values: sms.delivered
event_payload.timestamp
string
obligatoire
Time the carrier confirmed delivery.
event_payload.data
object
obligatoire
Payload of the sms.delivered event.
Afficher les attributs enfants
event_payload.data.sms_id
string
obligatoire
ID of the SMS message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
string
obligatoire
Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.
event_payload.data.from
string
obligatoire
Where the message came from. On an outbound message this is the sender you sent it from: an E.164 number, an alphanumeric sender ID, or a short code. On an inbound one it is the phone number that sent it to you.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
event_payload.data.requested_language
nullable string
obligatoire
The template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_language
nullable string
obligatoire
The template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_id
nullable string
obligatoire
The template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_id
nullable string
obligatoire
The workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.
event_payload.data.template_content_hash
nullable string
obligatoire
The rendered language's source fingerprint, or null for a free-text message.
event_payload.data.cost
nullable object
Message cost as of this event, split into the platform charge and any
third-party fees passed through. Null on an event that priced nothing.
Components are named so you can merge them per component rather than replacing the
object: webhook delivery is not ordered, so an older event arriving late would
otherwise overwrite a newer figure. Take the latest occurred_at you have seen for
each component. amount is the sum of the components in this payload and does not
represent a settled total.
Afficher les attributs enfants
event_payload.data.cost.amount
string
obligatoire
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
event_payload.data.cost.currency_code
string
obligatoire
ISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amount
nullable string
obligatoire
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.cost.passthrough_amount
nullable string
obligatoire
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.carrier
string
Carrier that delivered the message. Absent when the carrier does not report one.
event_payload.data.mcc_mnc
string
Mobile country code and mobile network code of the carrier. Absent when the carrier does not report one.
The message's validity period elapsed before it could be delivered.
event_payload.type
string
obligatoire
Event type.
Possible values: sms.expired
event_payload.timestamp
string
obligatoire
Time the message expired.
event_payload.data
object
obligatoire
Payload of the sms.expired event.
Afficher les attributs enfants
event_payload.data.sms_id
string
obligatoire
ID of the SMS message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
string
obligatoire
Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.
event_payload.data.from
string
obligatoire
Where the message came from. On an outbound message this is the sender you sent it from: an E.164 number, an alphanumeric sender ID, or a short code. On an inbound one it is the phone number that sent it to you.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
event_payload.data.requested_language
nullable string
obligatoire
The template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_language
nullable string
obligatoire
The template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_id
nullable string
obligatoire
The template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_id
nullable string
obligatoire
The workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.
event_payload.data.template_content_hash
nullable string
obligatoire
The rendered language's source fingerprint, or null for a free-text message.
event_payload.data.cost
nullable object
Message cost as of this event, split into the platform charge and any
third-party fees passed through. Null on an event that priced nothing.
Components are named so you can merge them per component rather than replacing the
object: webhook delivery is not ordered, so an older event arriving late would
otherwise overwrite a newer figure. Take the latest occurred_at you have seen for
each component. amount is the sum of the components in this payload and does not
represent a settled total.
Afficher les attributs enfants
event_payload.data.cost.amount
string
obligatoire
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
event_payload.data.cost.currency_code
string
obligatoire
ISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amount
nullable string
obligatoire
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.cost.passthrough_amount
nullable string
obligatoire
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.error
nullable object
obligatoire
Why the message was still undelivered when its validity period elapsed. Typically unreachable, the handset having stayed off or out of coverage for the whole window.
Afficher les attributs enfants
event_payload.data.error.code
string
obligatoire
Standardized failure reason:
- invalid_destination: The number is unassigned, ported out, or malformed.
- unreachable: The handset is off or outside coverage.
- blocked_by_carrier: The carrier filtered the message.
- blocked_by_recipient: The recipient device blocked the sender.
- landline_unreachable: The destination is a landline that does not accept SMS.
- content_rejected: The carrier rejected the content.
- sender_unregistered: The sender is not registered for the destination.
- recipient_opted_out: The recipient is on a suppression list.
- provider_unavailable: The provider remained unavailable after retries.
- insufficient_balance: The workspace wallet could not fund the send.
- unknown: The failure could not be classified.
This is an open enum. Accept unrecognized values.
Possible values (may grow over time): invalid_destination, unreachable, blocked_by_carrier, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, insufficient_balance, unknown
event_payload.data.error.description
string
obligatoire
The failure in words, from whatever refused the message: the carrier's own reason text on a delivery receipt, or ours on a message stopped before a carrier saw it. Free-form, so branch on code and show this to a human.
event_payload.data.error.carrier_error_code
nullable string
Raw provider-supplied error code, finer-grained than the code that normalizes it. Not a Bird-defined value, so quote it to support when asking why a message failed. Null when the provider sent none, including any failure decided before one was reached.
event_payload.data.error.occurred_at
string
obligatoire
When the failure occurred.
Message delivery failed permanently.
event_payload.type
string
obligatoire
Event type.
Possible values: sms.failed
event_payload.timestamp
string
obligatoire
Time the failure was recorded.
event_payload.data
object
obligatoire
Payload of the sms.failed event.
Afficher les attributs enfants
event_payload.data.sms_id
string
obligatoire
ID of the SMS message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
string
obligatoire
Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.
event_payload.data.from
string
obligatoire
Where the message came from. On an outbound message this is the sender you sent it from: an E.164 number, an alphanumeric sender ID, or a short code. On an inbound one it is the phone number that sent it to you.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
event_payload.data.requested_language
nullable string
obligatoire
The template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_language
nullable string
obligatoire
The template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_id
nullable string
obligatoire
The template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_id
nullable string
obligatoire
The workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.
event_payload.data.template_content_hash
nullable string
obligatoire
The rendered language's source fingerprint, or null for a free-text message.
event_payload.data.cost
nullable object
Message cost as of this event, split into the platform charge and any
third-party fees passed through. Null on an event that priced nothing.
Components are named so you can merge them per component rather than replacing the
object: webhook delivery is not ordered, so an older event arriving late would
otherwise overwrite a newer figure. Take the latest occurred_at you have seen for
each component. amount is the sum of the components in this payload and does not
represent a settled total.
Afficher les attributs enfants
event_payload.data.cost.amount
string
obligatoire
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
event_payload.data.cost.currency_code
string
obligatoire
ISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amount
nullable string
obligatoire
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.cost.passthrough_amount
nullable string
obligatoire
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.error
nullable object
obligatoire
Why the message terminally failed.
Afficher les attributs enfants
event_payload.data.error.code
string
obligatoire
Standardized failure reason:
- invalid_destination: The number is unassigned, ported out, or malformed.
- unreachable: The handset is off or outside coverage.
- blocked_by_carrier: The carrier filtered the message.
- blocked_by_recipient: The recipient device blocked the sender.
- landline_unreachable: The destination is a landline that does not accept SMS.
- content_rejected: The carrier rejected the content.
- sender_unregistered: The sender is not registered for the destination.
- recipient_opted_out: The recipient is on a suppression list.
- provider_unavailable: The provider remained unavailable after retries.
- insufficient_balance: The workspace wallet could not fund the send.
- unknown: The failure could not be classified.
This is an open enum. Accept unrecognized values.
Possible values (may grow over time): invalid_destination, unreachable, blocked_by_carrier, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, insufficient_balance, unknown
event_payload.data.error.description
string
obligatoire
The failure in words, from whatever refused the message: the carrier's own reason text on a delivery receipt, or ours on a message stopped before a carrier saw it. Free-form, so branch on code and show this to a human.
event_payload.data.error.carrier_error_code
nullable string
Raw provider-supplied error code, finer-grained than the code that normalizes it. Not a Bird-defined value, so quote it to support when asking why a message failed. Null when the provider sent none, including any failure decided before one was reached.
event_payload.data.error.occurred_at
string
obligatoire
When the failure occurred.
A message was received on one of your numbers.
event_payload.type
string
obligatoire
Always sms.received for this event.
Possible values: sms.received
event_payload.timestamp
string
obligatoire
Time the sender sent the message.
event_payload.data
object
obligatoire
Payload of the sms.received event.
Afficher les attributs enfants
event_payload.data.sms_id
string
obligatoire
ID of the SMS message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
string
obligatoire
Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.
event_payload.data.from
string
obligatoire
Where the message came from. On an outbound message this is the sender you sent it from: an E.164 number, an alphanumeric sender ID, or a short code. On an inbound one it is the phone number that sent it to you.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
event_payload.data.requested_language
nullable string
obligatoire
The template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_language
nullable string
obligatoire
The template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_id
nullable string
obligatoire
The template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_id
nullable string
obligatoire
The workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.
event_payload.data.template_content_hash
nullable string
obligatoire
The rendered language's source fingerprint, or null for a free-text message.
event_payload.data.cost
nullable object
Message cost as of this event, split into the platform charge and any
third-party fees passed through. Null on an event that priced nothing.
Components are named so you can merge them per component rather than replacing the
object: webhook delivery is not ordered, so an older event arriving late would
otherwise overwrite a newer figure. Take the latest occurred_at you have seen for
each component. amount is the sum of the components in this payload and does not
represent a settled total.
Afficher les attributs enfants
event_payload.data.cost.amount
string
obligatoire
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
event_payload.data.cost.currency_code
string
obligatoire
ISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amount
nullable string
obligatoire
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.cost.passthrough_amount
nullable string
obligatoire
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.text
string
obligatoire
The message body, so you can act on it without a follow-up read. Absent when the message carried only attachments and no text of its own.
event_payload.data.segments
object
obligatoire
Segment breakdown of the received body.
Afficher les attributs enfants
event_payload.data.segments.count
integer
obligatoire
Number of segments the body is split into. Each segment is a billable unit.
event_payload.data.segments.encoding
string
obligatoire
Encoding used for the body. The GSM_7BIT encoding fits 160 septets
(seven-bit units) in one segment, or 153 per part in a multi-segment
message. The UCS2 encoding applies when the body contains a character
outside the GSM 03.38 alphabet, including emoji, CJK, and some accented
characters. It fits 70 UTF-16 code units in one segment, or 67 per part.
Neither limit counts characters, and both alphabets have characters that
cost two units. Under GSM_7BIT there are ten such entries, and they are
the whole set: ^, {, }, \, [, ], ~, |, €, and the form
feed control. Eighty of those fill a single segment. Under UCS2 an emoji
outside the Basic Multilingual Plane is a surrogate pair costing two code
units, so 35 of those fill a single segment.
Possible values: GSM_7BIT, UCS2
event_payload.data.segments.characters
integer
obligatoire
Character count of the body, counted in Unicode code points under either encoding. This is not the segment measure: a GSM_7BIT extended-table character counts once here but costs two septets, and a UCS2 emoji outside the Basic Multilingual Plane counts once here but costs two of the segment's 70 code units.
event_payload.data.carrier
string
Carrier the message came in over. Absent where the carrier does not report one.
event_payload.data.mcc_mnc
string
Mobile country code and mobile network code of the carrier. Absent when not known.
event_payload.data.subject
string
Subject line. Absent when the message carried none.
event_payload.data.sms_id
string
obligatoire
ID of the SMS message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
string
obligatoire
Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.
event_payload.data.from
string
obligatoire
Where the message came from. On an outbound message this is the sender you sent it from: an E.164 number, an alphanumeric sender ID, or a short code. On an inbound one it is the phone number that sent it to you.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
event_payload.data.requested_language
nullable string
obligatoire
The template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_language
nullable string
obligatoire
The template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_id
nullable string
obligatoire
The template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_id
nullable string
obligatoire
The workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.
event_payload.data.template_content_hash
nullable string
obligatoire
The rendered language's source fingerprint, or null for a free-text message.
event_payload.data.cost
nullable object
Message cost as of this event, split into the platform charge and any
third-party fees passed through. Null on an event that priced nothing.
Components are named so you can merge them per component rather than replacing the
object: webhook delivery is not ordered, so an older event arriving late would
otherwise overwrite a newer figure. Take the latest occurred_at you have seen for
each component. amount is the sum of the components in this payload and does not
represent a settled total.
Afficher les attributs enfants
event_payload.data.cost.amount
string
obligatoire
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
event_payload.data.cost.currency_code
string
obligatoire
ISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amount
nullable string
obligatoire
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.cost.passthrough_amount
nullable string
obligatoire
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.segments
object
obligatoire
Segment breakdown of the received body.
Afficher les attributs enfants
event_payload.data.segments.count
integer
obligatoire
Number of segments the body is split into. Each segment is a billable unit.
event_payload.data.segments.encoding
string
obligatoire
Encoding used for the body. The GSM_7BIT encoding fits 160 septets
(seven-bit units) in one segment, or 153 per part in a multi-segment
message. The UCS2 encoding applies when the body contains a character
outside the GSM 03.38 alphabet, including emoji, CJK, and some accented
characters. It fits 70 UTF-16 code units in one segment, or 67 per part.
Neither limit counts characters, and both alphabets have characters that
cost two units. Under GSM_7BIT there are ten such entries, and they are
the whole set: ^, {, }, \, [, ], ~, |, €, and the form
feed control. Eighty of those fill a single segment. Under UCS2 an emoji
outside the Basic Multilingual Plane is a surrogate pair costing two code
units, so 35 of those fill a single segment.
Possible values: GSM_7BIT, UCS2
event_payload.data.segments.characters
integer
obligatoire
Character count of the body, counted in Unicode code points under either encoding. This is not the segment measure: a GSM_7BIT extended-table character counts once here but costs two septets, and a UCS2 emoji outside the Basic Multilingual Plane counts once here but costs two of the segment's 70 code units.
event_payload.data.carrier
string
Carrier the message came in over. Absent where the carrier does not report one.
event_payload.data.mcc_mnc
string
Mobile country code and mobile network code of the carrier. Absent when not known.
event_payload.data.subject
string
Subject line. Absent when the message carried none.
The API rejected the message before sending it to the carrier because of an invalid destination, suppression, or content or policy restriction.
event_payload.type
string
obligatoire
Event type.
Possible values: sms.rejected
event_payload.timestamp
string
obligatoire
Time the rejection was recorded.
event_payload.data
object
obligatoire
Payload of the sms.rejected event.
Afficher les attributs enfants
event_payload.data.sms_id
string
obligatoire
ID of the SMS message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
string
obligatoire
Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.
event_payload.data.from
string
obligatoire
Where the message came from. On an outbound message this is the sender you sent it from: an E.164 number, an alphanumeric sender ID, or a short code. On an inbound one it is the phone number that sent it to you.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
event_payload.data.requested_language
nullable string
obligatoire
The template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_language
nullable string
obligatoire
The template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_id
nullable string
obligatoire
The template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_id
nullable string
obligatoire
The workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.
event_payload.data.template_content_hash
nullable string
obligatoire
The rendered language's source fingerprint, or null for a free-text message.
event_payload.data.cost
nullable object
Message cost as of this event, split into the platform charge and any
third-party fees passed through. Null on an event that priced nothing.
Components are named so you can merge them per component rather than replacing the
object: webhook delivery is not ordered, so an older event arriving late would
otherwise overwrite a newer figure. Take the latest occurred_at you have seen for
each component. amount is the sum of the components in this payload and does not
represent a settled total.
Afficher les attributs enfants
event_payload.data.cost.amount
string
obligatoire
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
event_payload.data.cost.currency_code
string
obligatoire
ISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amount
nullable string
obligatoire
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.cost.passthrough_amount
nullable string
obligatoire
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.error
nullable object
obligatoire
Why the message was rejected before reaching the carrier.
Afficher les attributs enfants
event_payload.data.error.code
string
obligatoire
Standardized failure reason:
- invalid_destination: The number is unassigned, ported out, or malformed.
- unreachable: The handset is off or outside coverage.
- blocked_by_carrier: The carrier filtered the message.
- blocked_by_recipient: The recipient device blocked the sender.
- landline_unreachable: The destination is a landline that does not accept SMS.
- content_rejected: The carrier rejected the content.
- sender_unregistered: The sender is not registered for the destination.
- recipient_opted_out: The recipient is on a suppression list.
- provider_unavailable: The provider remained unavailable after retries.
- insufficient_balance: The workspace wallet could not fund the send.
- unknown: The failure could not be classified.
This is an open enum. Accept unrecognized values.
Possible values (may grow over time): invalid_destination, unreachable, blocked_by_carrier, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, insufficient_balance, unknown
event_payload.data.error.description
string
obligatoire
The failure in words, from whatever refused the message: the carrier's own reason text on a delivery receipt, or ours on a message stopped before a carrier saw it. Free-form, so branch on code and show this to a human.
event_payload.data.error.carrier_error_code
nullable string
Raw provider-supplied error code, finer-grained than the code that normalizes it. Not a Bird-defined value, so quote it to support when asking why a message failed. Null when the provider sent none, including any failure decided before one was reached.
event_payload.data.error.occurred_at
string
obligatoire
When the failure occurred.
The API handed the message to the carrier for delivery.
event_payload.type
string
obligatoire
Event type.
Possible values: sms.sent
event_payload.timestamp
string
obligatoire
Time the message was handed to the carrier.
event_payload.data
object
obligatoire
Payload of the sms.sent event.
Afficher les attributs enfants
event_payload.data.sms_id
string
obligatoire
ID of the SMS message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
string
obligatoire
Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.
event_payload.data.from
string
obligatoire
Where the message came from. On an outbound message this is the sender you sent it from: an E.164 number, an alphanumeric sender ID, or a short code. On an inbound one it is the phone number that sent it to you.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
event_payload.data.requested_language
nullable string
obligatoire
The template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_language
nullable string
obligatoire
The template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_id
nullable string
obligatoire
The template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_id
nullable string
obligatoire
The workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.
event_payload.data.template_content_hash
nullable string
obligatoire
The rendered language's source fingerprint, or null for a free-text message.
event_payload.data.cost
nullable object
Message cost as of this event, split into the platform charge and any
third-party fees passed through. Null on an event that priced nothing.
Components are named so you can merge them per component rather than replacing the
object: webhook delivery is not ordered, so an older event arriving late would
otherwise overwrite a newer figure. Take the latest occurred_at you have seen for
each component. amount is the sum of the components in this payload and does not
represent a settled total.
Afficher les attributs enfants
event_payload.data.cost.amount
string
obligatoire
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
event_payload.data.cost.currency_code
string
obligatoire
ISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amount
nullable string
obligatoire
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.cost.passthrough_amount
nullable string
obligatoire
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.carrier
string
Carrier that handled the message. Absent when the carrier does not report one.
event_payload.data.mcc_mnc
string
Mobile country code and mobile network code of the carrier. Absent when the carrier does not report one.
The carrier reported a non-permanent failure to deliver the message.
event_payload.type
string
obligatoire
Event type.
Possible values: sms.undelivered
event_payload.timestamp
string
obligatoire
Time the non-delivery was recorded.
event_payload.data
object
obligatoire
Payload of the sms.undelivered event.
Afficher les attributs enfants
event_payload.data.sms_id
string
obligatoire
ID of the SMS message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
string
obligatoire
Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.
event_payload.data.from
string
obligatoire
Where the message came from. On an outbound message this is the sender you sent it from: an E.164 number, an alphanumeric sender ID, or a short code. On an inbound one it is the phone number that sent it to you.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message so you can route and correlate without an extra lookup. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message so you can correlate events with your own records. Null when the message carried no metadata.
event_payload.data.requested_language
nullable string
obligatoire
The template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_language
nullable string
obligatoire
The template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_id
nullable string
obligatoire
The template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_id
nullable string
obligatoire
The workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.
event_payload.data.template_content_hash
nullable string
obligatoire
The rendered language's source fingerprint, or null for a free-text message.
event_payload.data.cost
nullable object
Message cost as of this event, split into the platform charge and any
third-party fees passed through. Null on an event that priced nothing.
Components are named so you can merge them per component rather than replacing the
object: webhook delivery is not ordered, so an older event arriving late would
otherwise overwrite a newer figure. Take the latest occurred_at you have seen for
each component. amount is the sum of the components in this payload and does not
represent a settled total.
Afficher les attributs enfants
event_payload.data.cost.amount
string
obligatoire
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
event_payload.data.cost.currency_code
string
obligatoire
ISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amount
nullable string
obligatoire
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.cost.passthrough_amount
nullable string
obligatoire
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.error
nullable object
obligatoire
Why the message was not delivered.
Afficher les attributs enfants
event_payload.data.error.code
string
obligatoire
Standardized failure reason:
- invalid_destination: The number is unassigned, ported out, or malformed.
- unreachable: The handset is off or outside coverage.
- blocked_by_carrier: The carrier filtered the message.
- blocked_by_recipient: The recipient device blocked the sender.
- landline_unreachable: The destination is a landline that does not accept SMS.
- content_rejected: The carrier rejected the content.
- sender_unregistered: The sender is not registered for the destination.
- recipient_opted_out: The recipient is on a suppression list.
- provider_unavailable: The provider remained unavailable after retries.
- insufficient_balance: The workspace wallet could not fund the send.
- unknown: The failure could not be classified.
This is an open enum. Accept unrecognized values.
Possible values (may grow over time): invalid_destination, unreachable, blocked_by_carrier, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, insufficient_balance, unknown
event_payload.data.error.description
string
obligatoire
The failure in words, from whatever refused the message: the carrier's own reason text on a delivery receipt, or ours on a message stopped before a carrier saw it. Free-form, so branch on code and show this to a human.
event_payload.data.error.carrier_error_code
nullable string
Raw provider-supplied error code, finer-grained than the code that normalizes it. Not a Bird-defined value, so quote it to support when asking why a message failed. Null when the provider sent none, including any failure decided before one was reached.
event_payload.data.error.occurred_at
string
obligatoire
When the failure occurred.
A destination was added to the workspace's SMS suppression ledger: a subscriber's STOP, a carrier opt-out, or a manual add.
event_payload.type
string
obligatoire
Always sms_suppression.created for this event.
Possible values: sms_suppression.created
event_payload.timestamp
string
obligatoire
When the episode's opening statement took effect (effective_at).
event_payload.data
object
obligatoire
Payload of the sms_suppression.created event.
Afficher les attributs enfants
event_payload.data.suppression_id
string
obligatoire
The suppression episode that was opened.
event_payload.data.destination
string
obligatoire
The subscriber, in E.164 format.
event_payload.data.originator
string
obligatoire
The sender this stops. An SMS suppression is the exact (sender, recipient) pair, so your other senders still reach this subscriber.
event_payload.data.reason
string
obligatoire
event_payload.data.workspace_id
string
obligatoire
The workspace the suppression belongs to.
The channel confirmed delivery of a one-time passcode to the recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: verify.attempt.delivered
event_payload.timestamp
string
obligatoire
Time delivery was confirmed.
event_payload.data
object
obligatoire
Payload of the verify.attempt.delivered event.
Afficher les attributs enfants
event_payload.data.verification_id
string
obligatoire
ID of the verification session.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
object
obligatoire
The recipient identity of the verification session (email address, phone number, or both), echoed on every event so you can correlate without an extra lookup. An individual attempt reports the single address it was dispatched to in its own address field.
Afficher les attributs enfants
event_payload.data.to.email
string
The recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_number
string
The recipient's phone number in E.164 format, with the leading + and country code (for example +15551234567). A number in any other format is rejected as an invalid recipient (422).
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided when the verification was created, echoed on every event for the session so you can correlate events with your own records. Null when the verification carried no metadata.
event_payload.data.channel
string
obligatoire
The channel this attempt was sent on.
Possible values (may grow over time): email, sms, whatsapp, telegram, voice
event_payload.data.address
string
obligatoire
The single address this attempt was dispatched to, an E.164 phone number or an email address.
event_payload.data.carrier
nullable string
obligatoire
Carrier that delivered the message, when the carrier network reports it. Always null for email, WhatsApp, and Telegram.
event_payload.data.mcc_mnc
nullable string
obligatoire
Mobile country code and mobile network code of the delivering carrier, when reported. Always null for email, WhatsApp, and Telegram.
event_payload.data.delivered_at
string
obligatoire
Time delivery was confirmed.
A one-time passcode was dispatched to the recipient on a channel.
event_payload.type
string
obligatoire
Event type.
Possible values: verify.attempt.sent
event_payload.timestamp
string
obligatoire
Time the passcode was dispatched.
event_payload.data
object
obligatoire
Payload of the verify.attempt.sent event.
Afficher les attributs enfants
event_payload.data.verification_id
string
obligatoire
ID of the verification session.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
object
obligatoire
The recipient identity of the verification session (email address, phone number, or both), echoed on every event so you can correlate without an extra lookup. An individual attempt reports the single address it was dispatched to in its own address field.
Afficher les attributs enfants
event_payload.data.to.email
string
The recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_number
string
The recipient's phone number in E.164 format, with the leading + and country code (for example +15551234567). A number in any other format is rejected as an invalid recipient (422).
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided when the verification was created, echoed on every event for the session so you can correlate events with your own records. Null when the verification carried no metadata.
event_payload.data.channel
string
obligatoire
The channel this attempt was sent on.
Possible values (may grow over time): email, sms, whatsapp, telegram, voice
event_payload.data.address
string
obligatoire
The single address this attempt was dispatched to, an E.164 phone number or an email address.
event_payload.data.from
nullable string
obligatoire
The sender the passcode was sent from: a phone number, alphanumeric sender ID, short code, or email address. Null when the channel exposes no sender.
event_payload.data.sent_at
string
obligatoire
Time the passcode was dispatched.
A one-time passcode failed to deliver to the recipient.
event_payload.type
string
obligatoire
Event type.
Possible values: verify.attempt.undelivered
event_payload.timestamp
string
obligatoire
Time the failure was recorded.
event_payload.data
object
obligatoire
Payload of the verify.attempt.undelivered event.
Afficher les attributs enfants
event_payload.data.verification_id
string
obligatoire
ID of the verification session.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
object
obligatoire
The recipient identity of the verification session (email address, phone number, or both), echoed on every event so you can correlate without an extra lookup. An individual attempt reports the single address it was dispatched to in its own address field.
Afficher les attributs enfants
event_payload.data.to.email
string
The recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_number
string
The recipient's phone number in E.164 format, with the leading + and country code (for example +15551234567). A number in any other format is rejected as an invalid recipient (422).
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided when the verification was created, echoed on every event for the session so you can correlate events with your own records. Null when the verification carried no metadata.
event_payload.data.channel
string
obligatoire
The channel this attempt was sent on.
Possible values (may grow over time): email, sms, whatsapp, telegram, voice
event_payload.data.address
string
obligatoire
The single address this attempt was dispatched to, an E.164 phone number or an email address.
event_payload.data.reason
string
obligatoire
Why the attempt failed to reach the recipient.
Possible values (may grow over time): carrier_rejected, hard_bounce, soft_bounce, undelivered, channel_unavailable, channel_disabled, channel_restricted, delivery_timeout, not_billable
event_payload.data.error
nullable string
obligatoire
Diagnostic text describing the failure, for display only. Null when none was reported.
event_payload.data.failed_at
string
obligatoire
Time the failure was recorded.
A verification session was created and its first one-time passcode is being sent.
event_payload.type
string
obligatoire
Event type.
Possible values: verify.verification.created
event_payload.timestamp
string
obligatoire
Time the verification session was created.
event_payload.data
object
obligatoire
Payload of the verify.verification.created event.
Afficher les attributs enfants
event_payload.data.verification_id
string
obligatoire
ID of the verification session.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
object
obligatoire
The recipient identity of the verification session (email address, phone number, or both), echoed on every event so you can correlate without an extra lookup. An individual attempt reports the single address it was dispatched to in its own address field.
Afficher les attributs enfants
event_payload.data.to.email
string
The recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_number
string
The recipient's phone number in E.164 format, with the leading + and country code (for example +15551234567). A number in any other format is rejected as an invalid recipient (422).
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided when the verification was created, echoed on every event for the session so you can correlate events with your own records. Null when the verification carried no metadata.
event_payload.data.channel
string
obligatoire
The first channel of the verification's resolved channel plan.
Possible values (may grow over time): email, sms, whatsapp, telegram, voice
event_payload.data.status
string
obligatoire
The verification's state at creation, always pending. Open enum for forward compatibility.
Possible values (may grow over time): pending
event_payload.data.created_at
string
obligatoire
Time the verification session was created.
The verification ended without the recipient receiving a passcode: every planned channel reported that its send would not arrive.
event_payload.type
string
obligatoire
Always verify.verification.failed for this event.
Possible values: verify.verification.failed
event_payload.timestamp
string
obligatoire
Time the verification was resolved.
event_payload.data
object
obligatoire
Payload of the verify.verification.failed event.
Afficher les attributs enfants
event_payload.data.verification_id
string
obligatoire
ID of the verification session.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
object
obligatoire
The recipient identity of the verification session (email address, phone number, or both), echoed on every event so you can correlate without an extra lookup. An individual attempt reports the single address it was dispatched to in its own address field.
Afficher les attributs enfants
event_payload.data.to.email
string
The recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_number
string
The recipient's phone number in E.164 format, with the leading + and country code (for example +15551234567). A number in any other format is rejected as an invalid recipient (422).
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided when the verification was created, echoed on every event for the session so you can correlate events with your own records. Null when the verification carried no metadata.
event_payload.data.status
string
obligatoire
The verification's state, always failed. Open enum for forward compatibility.
Possible values (may grow over time): failed
event_payload.data.reason
string
obligatoire
Why the verification ended. Always undeliverable on this event: no planned channel delivered a passcode.
Possible values (may grow over time): attempts_exhausted, ttl_elapsed, undeliverable
event_payload.data.channel
nullable string
obligatoire
The last channel the verification tried, the one whose failure left it with nowhere else to go. Null when no channel was attributed.
event_payload.data.last_attempt_reason
string
obligatoire
Why that last send did not deliver. This is the actionable half of the event: not_billable means the workspace balance could not cover the send, while the delivery reasons point at the recipient or the channel.
Possible values (may grow over time): carrier_rejected, hard_bounce, soft_bounce, undelivered, channel_unavailable, channel_disabled, channel_restricted, delivery_timeout, not_billable
event_payload.data.failed_at
string
obligatoire
Time the verification was resolved.
The verification was successfully resolved: the recipient confirmed the correct code.
event_payload.type
string
obligatoire
Event type.
Possible values: verify.verification.verified
event_payload.timestamp
string
obligatoire
Time the verification was verified.
event_payload.data
object
obligatoire
Payload of the verify.verification.verified event.
Afficher les attributs enfants
event_payload.data.verification_id
string
obligatoire
ID of the verification session.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.to
object
obligatoire
The recipient identity of the verification session (email address, phone number, or both), echoed on every event so you can correlate without an extra lookup. An individual attempt reports the single address it was dispatched to in its own address field.
Afficher les attributs enfants
event_payload.data.to.email
string
The recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_number
string
The recipient's phone number in E.164 format, with the leading + and country code (for example +15551234567). A number in any other format is rejected as an invalid recipient (422).
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided when the verification was created, echoed on every event for the session so you can correlate events with your own records. Null when the verification carried no metadata.
event_payload.data.status
string
obligatoire
The verification's state, always verified. Open enum for forward compatibility.
Possible values (may grow over time): verified
event_payload.data.channel
nullable string
obligatoire
The channel whose passcode the recipient confirmed, the channel that converted. Null when the verification was resolved without attributing a channel.
event_payload.data.verified_at
string
obligatoire
Time the verification was verified.
The called party answered and media began flowing.
event_payload.type
string
obligatoire
Event type.
Possible values: voice_call.answered
event_payload.timestamp
string
obligatoire
Time the call was answered.
event_payload.data
object
obligatoire
Payload of the voice_call.answered event.
Afficher les attributs enfants
event_payload.data.call_id
string
obligatoire
ID of the call record.
event_payload.data.session_id
nullable string
Session identifier shared across all legs of a multi-party or transferred call. Use this to correlate related call records. Null when session correlation is not available for the call.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.direction
string
obligatoire
Whether the call originated from your PBX (outbound) or arrived from a remote party (inbound).
Possible values: inbound, outbound
event_payload.data.from
string
obligatoire
Calling party number in E.164 format.
event_payload.data.to
string
obligatoire
Called party number in E.164 format.
The call ended after either party hung up or call setup failed.
event_payload.type
string
obligatoire
Event type.
Possible values: voice_call.ended
event_payload.timestamp
string
obligatoire
Time either party hung up or call setup failed.
event_payload.data
object
obligatoire
Payload of the voice_call.ended event.
Afficher les attributs enfants
event_payload.data.call_id
string
obligatoire
ID of the call record.
event_payload.data.session_id
nullable string
Session identifier shared across all legs of a multi-party or transferred call. Use this to correlate related call records. Null when session correlation is not available for the call.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.direction
string
obligatoire
Whether the call originated from your PBX (outbound) or arrived from a remote party (inbound).
Possible values: inbound, outbound
event_payload.data.from
string
obligatoire
Calling party number in E.164 format.
event_payload.data.to
string
obligatoire
Called party number in E.164 format.
event_payload.data.status
string
obligatoire
Call status.
A call that has ended carries one of:
- answered means it connected and the far end picked up.
- no_answer means nobody picked up before the call timed out.
- rejected means it was refused rather than attempted. Either we turned it away before dialing a carrier, in which case rejection_reason names the check it failed where there was one, or the far end declined it.
- failed means it was attempted and did not work, and sip_response_code is what came back.
- unknown means the outcome could not be determined. Contact support with the call id if you see one.
An active call carries ringing before it is picked up and in_progress
afterward. The call list's status filter takes any mix of the two sets.
busy and canceled are reserved for incoming calls delivered to your own
numbers: busy for a called party that rejected the call as busy, canceled
for a caller who hung up before it was picked up. Neither is emitted yet and
both outcomes are reported as failed today.
Possible values: answered, no_answer, busy, canceled, failed, rejected, unknown, ringing, in_progress
event_payload.data.sip_response_code
nullable integer
obligatoire
Final SIP response code received from the carrier. Null when no SIP response was received, for example on timeout or DNS failure.
event_payload.data.duration_ms
integer
obligatoire
Total call duration in milliseconds, measured from the first SIP INVITE to the BYE or final response.
event_payload.data.billable_ms
integer
obligatoire
Billable duration in milliseconds, measured from answer to call end. Zero for unanswered calls.
Call routing began.
event_payload.type
string
obligatoire
Event type.
Possible values: voice_call.initiated
event_payload.timestamp
string
obligatoire
Time the call was initiated.
event_payload.data
object
obligatoire
Payload of the voice_call.initiated event.
Afficher les attributs enfants
event_payload.data.call_id
string
obligatoire
ID of the call record.
event_payload.data.session_id
nullable string
Session identifier shared across all legs of a multi-party or transferred call. Use this to correlate related call records. Null when session correlation is not available for the call.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.direction
string
obligatoire
Whether the call originated from your PBX (outbound) or arrived from a remote party (inbound).
Possible values: inbound, outbound
event_payload.data.from
string
obligatoire
Calling party number in E.164 format.
event_payload.data.to
string
obligatoire
Called party number in E.164 format.
The API accepted and charged the send request.
event_payload.type
string
obligatoire
Event type.
Possible values: whatsapp.accepted
event_payload.timestamp
string
obligatoire
Time the API accepted and charged the send request.
event_payload.data
object
obligatoire
Payload of the whatsapp.accepted event.
Afficher les attributs enfants
event_payload.data.whatsapp_id
string
obligatoire
ID of the WhatsApp message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.direction
string
obligatoire
Whether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.from
object
obligatoire
Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Afficher les attributs enfants
event_payload.data.from.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.from.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.from.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.from.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.from.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.to
object
obligatoire
Recipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Afficher les attributs enfants
event_payload.data.to.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.to.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.to.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.to.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.to.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message. Null when the message carried no metadata.
event_payload.data.in_reply_to_message_id
string
The message this one answers. On an outbound message it is the in_reply_to_message_id the send request quoted. On an inbound message it is what WhatsApp reports as the reply's target: a tap on a button or a list row, and equally a text or media message the contact sent as a quoted reply. Absent when the message answers nothing, and absent on an inbound message whose target we cannot match to a message we hold, which is the case for one sent before this workspace started recording them or one already past the 15-day window we keep provider ids for.
The message was delivered to the recipient's device.
event_payload.type
string
obligatoire
Event type.
Possible values: whatsapp.delivered
event_payload.timestamp
string
obligatoire
Time the message was delivered to the recipient's device.
event_payload.data
object
obligatoire
Payload of the whatsapp.delivered event.
Afficher les attributs enfants
event_payload.data.whatsapp_id
string
obligatoire
ID of the WhatsApp message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.direction
string
obligatoire
Whether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.from
object
obligatoire
Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Afficher les attributs enfants
event_payload.data.from.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.from.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.from.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.from.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.from.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.to
object
obligatoire
Recipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Afficher les attributs enfants
event_payload.data.to.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.to.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.to.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.to.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.to.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message. Null when the message carried no metadata.
event_payload.data.in_reply_to_message_id
string
The message this one answers. On an outbound message it is the in_reply_to_message_id the send request quoted. On an inbound message it is what WhatsApp reports as the reply's target: a tap on a button or a list row, and equally a text or media message the contact sent as a quoted reply. Absent when the message answers nothing, and absent on an inbound message whose target we cannot match to a message we hold, which is the case for one sent before this workspace started recording them or one already past the 15-day window we keep provider ids for.
event_payload.data.recipient
object
The participant delivery was confirmed to, on a group message. A group send raises this event once per participant, so this is what tells the deliveries apart. Absent on a one-to-one message, whose to already names its recipient.
Afficher les attributs enfants
event_payload.data.recipient.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.recipient.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.recipient.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.recipient.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.recipient.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
Message delivery failed permanently.
event_payload.type
string
obligatoire
Event type.
Possible values: whatsapp.failed
event_payload.timestamp
string
obligatoire
Time the failure was recorded.
event_payload.data
object
obligatoire
Payload of the whatsapp.failed event.
Afficher les attributs enfants
event_payload.data.whatsapp_id
string
obligatoire
ID of the WhatsApp message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.direction
string
obligatoire
Whether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.from
object
obligatoire
Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Afficher les attributs enfants
event_payload.data.from.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.from.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.from.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.from.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.from.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.to
object
obligatoire
Recipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Afficher les attributs enfants
event_payload.data.to.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.to.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.to.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.to.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.to.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message. Null when the message carried no metadata.
event_payload.data.in_reply_to_message_id
string
The message this one answers. On an outbound message it is the in_reply_to_message_id the send request quoted. On an inbound message it is what WhatsApp reports as the reply's target: a tap on a button or a list row, and equally a text or media message the contact sent as a quoted reply. Absent when the message answers nothing, and absent on an inbound message whose target we cannot match to a message we hold, which is the case for one sent before this workspace started recording them or one already past the 15-day window we keep provider ids for.
event_payload.data.error
nullable object
obligatoire
Why the message terminally failed.
Afficher les attributs enfants
event_payload.data.error.code
string
obligatoire
Standardized failure reason:
- insufficient_balance: The workspace wallet could not fund the send.
- price_not_found: No price was configured for the destination and template.
- internal_error: An unexpected service failure occurred.
- undeliverable: The recipient could not be reached.
- service_window_expired: The 24-hour service window closed; send a template.
- rate_limited: The send was throttled.
- recipient_suppressed: The recipient is on the workspace suppression list.
- media_rejected: WhatsApp could not fetch the media URL, or refused the file it found there; description carries its reason.
This is an open enum. Accept unrecognized values.
Possible values (may grow over time): insufficient_balance, price_not_found, internal_error, undeliverable, service_window_expired, rate_limited, recipient_suppressed, media_rejected
event_payload.data.error.description
string
obligatoire
Human-readable explanation of the failure.
event_payload.data.error.meta_error_code
nullable string
Raw error code from the WhatsApp Cloud API, when available, for low-level debugging.
event_payload.data.error.occurred_at
string
obligatoire
When the failure occurred.
A contact placed, changed or took back a reaction on a message.
event_payload.type
string
obligatoire
Always whatsapp.reacted for this event.
Possible values: whatsapp.reacted
event_payload.timestamp
string
obligatoire
When the contact reacted, as reported by WhatsApp. Meta reports this to the second, so a contact who changes or withdraws a reaction quickly can produce two events sharing one timestamp. Sorting reactions on one message by this field cannot order those, and neither can delivery order, which retries make unreliable. Act on the reaction each event carries, as the change it describes; do not reconstruct the sequence from the events or treat the last one to arrive as the message's standing reaction. Read the message back for the reactions that stand: getWhatsAppMessage (GET /v1/whatsapp/messages/{message_id}) returns one entry per sender in reactions, and listWhatsAppMessageReactionEvents has every change.
event_payload.data
object
obligatoire
Payload of the whatsapp.reacted event. Names the message the contact reacted to, not the reaction, because a reaction is an annotation on a message rather than a message of its own.
Afficher les attributs enfants
event_payload.data.whatsapp_id
string
obligatoire
The message the contact reacted to. WhatsApp accepts a reaction on a message up to 30 days old, and we keep provider ids for 15, so a reaction placed on a message older than that cannot be matched to it and raises no event at all.
event_payload.data.emoji
nullable string
obligatoire
The emoji the contact placed, as WhatsApp sent it and not normalized. Null when they took their reaction back rather than placing one. Always present, so null is the removal itself rather than a value we are missing.
event_payload.data.from
object
obligatoire
The contact who reacted, as WhatsApp identified them.
Afficher les attributs enfants
event_payload.data.from.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.from.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.from.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.from.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.from.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.to
object
obligatoire
Your WhatsApp number, the business side of the conversation.
Afficher les attributs enfants
event_payload.data.to.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.to.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.to.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.to.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.to.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
The recipient read the message.
event_payload.type
string
obligatoire
Event type.
Possible values: whatsapp.read
event_payload.timestamp
string
obligatoire
Time the recipient read the message.
event_payload.data
object
obligatoire
Payload of the whatsapp.read event.
Afficher les attributs enfants
event_payload.data.whatsapp_id
string
obligatoire
ID of the WhatsApp message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.direction
string
obligatoire
Whether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.from
object
obligatoire
Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Afficher les attributs enfants
event_payload.data.from.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.from.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.from.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.from.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.from.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.to
object
obligatoire
Recipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Afficher les attributs enfants
event_payload.data.to.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.to.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.to.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.to.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.to.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message. Null when the message carried no metadata.
event_payload.data.in_reply_to_message_id
string
The message this one answers. On an outbound message it is the in_reply_to_message_id the send request quoted. On an inbound message it is what WhatsApp reports as the reply's target: a tap on a button or a list row, and equally a text or media message the contact sent as a quoted reply. Absent when the message answers nothing, and absent on an inbound message whose target we cannot match to a message we hold, which is the case for one sent before this workspace started recording them or one already past the 15-day window we keep provider ids for.
event_payload.data.recipient
object
The participant who opened the message, on a group message. A group send raises this event once per participant, so this is what tells the deliveries apart. Absent on a one-to-one message, whose to already names its recipient.
Afficher les attributs enfants
event_payload.data.recipient.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.recipient.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.recipient.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.recipient.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.recipient.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
A contact sent the business a WhatsApp message.
event_payload.type
string
obligatoire
Event type.
Possible values: whatsapp.received
event_payload.timestamp
string
obligatoire
Time the contact sent the message, as reported by WhatsApp.
event_payload.data
object
obligatoire
Payload of the whatsapp.received event. Carries the message's content so a subscriber can act on it without reading the message back.
Afficher les attributs enfants
event_payload.data.whatsapp_id
string
obligatoire
ID of the WhatsApp message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.direction
string
obligatoire
Whether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.from
object
obligatoire
Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Afficher les attributs enfants
event_payload.data.from.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.from.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.from.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.from.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.from.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.to
object
obligatoire
Recipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Afficher les attributs enfants
event_payload.data.to.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.to.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.to.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.to.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.to.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message. Null when the message carried no metadata.
event_payload.data.in_reply_to_message_id
string
The message this one answers. On an outbound message it is the in_reply_to_message_id the send request quoted. On an inbound message it is what WhatsApp reports as the reply's target: a tap on a button or a list row, and equally a text or media message the contact sent as a quoted reply. Absent when the message answers nothing, and absent on an inbound message whose target we cannot match to a message we hold, which is the case for one sent before this workspace started recording them or one already past the 15-day window we keep provider ids for.
event_payload.data.text
object
Text the contact sent.
Afficher les attributs enfants
event_payload.data.text.body
string
obligatoire
The message text.
event_payload.data.image
object
Image the contact sent.
Afficher les attributs enfants
event_payload.data.image.id
string
ID of the stored file, to pass as media_id when fetching it. Absent on an outbound message, whose file we never stored.
event_payload.data.image.url
string
Where to fetch the media. On an inbound message this is a Bird URL you fetch with your API key; it is absent when the file could not be retrieved from WhatsApp. It stays populated after the stored bytes expire, and the link returns 410 from then on. On an outbound message it is the URL the sender supplied, whose availability is the sender's to guarantee.
event_payload.data.image.mime_type
string
Media type WhatsApp reported for the file, for example image/jpeg. Absent on outbound messages.
event_payload.data.image.caption
string
Text shown beneath the image. Absent when the sender wrote none.
event_payload.data.video
object
Video the contact sent.
Afficher les attributs enfants
event_payload.data.video.id
string
ID of the stored file, to pass as media_id when fetching it. Absent on an outbound message, whose file we never stored.
event_payload.data.video.url
string
Where to fetch the media. On an inbound message this is a Bird URL you fetch with your API key; it is absent when the file could not be retrieved from WhatsApp. It stays populated after the stored bytes expire, and the link returns 410 from then on. On an outbound message it is the URL the sender supplied, whose availability is the sender's to guarantee.
event_payload.data.video.mime_type
string
Media type WhatsApp reported for the file, for example image/jpeg. Absent on outbound messages.
event_payload.data.video.caption
string
Text shown beneath the video. Absent when the sender wrote none.
event_payload.data.audio
object
Audio the contact sent.
Afficher les attributs enfants
event_payload.data.audio.id
string
ID of the stored file, to pass as media_id when fetching it. Absent on an outbound message, whose file we never stored.
event_payload.data.audio.url
string
Where to fetch the media. On an inbound message this is a Bird URL you fetch with your API key; it is absent when the file could not be retrieved from WhatsApp. It stays populated after the stored bytes expire, and the link returns 410 from then on. On an outbound message it is the URL the sender supplied, whose availability is the sender's to guarantee.
event_payload.data.audio.mime_type
string
Media type WhatsApp reported for the file, for example image/jpeg. Absent on outbound messages.
event_payload.data.audio.voice
boolean
Whether this is a voice note rather than an attached audio file. A voice note auto-downloads in the WhatsApp client and can be transcribed for the recipient.
event_payload.data.sticker
object
Sticker the contact sent.
Afficher les attributs enfants
event_payload.data.sticker.id
string
ID of the stored file, to pass as media_id when fetching it. Absent on an outbound message, whose file we never stored.
event_payload.data.sticker.url
string
Where to fetch the media. On an inbound message this is a Bird URL you fetch with your API key; it is absent when the file could not be retrieved from WhatsApp. It stays populated after the stored bytes expire, and the link returns 410 from then on. On an outbound message it is the URL the sender supplied, whose availability is the sender's to guarantee.
event_payload.data.sticker.mime_type
string
Media type WhatsApp reported for the file, for example image/jpeg. Absent on outbound messages.
event_payload.data.sticker.animated
boolean
Whether the sticker is animated. Absent on an outbound message.
event_payload.data.document
object
Document the contact sent.
Afficher les attributs enfants
event_payload.data.document.id
string
ID of the stored file, to pass as media_id when fetching it. Absent on an outbound message, whose file we never stored.
event_payload.data.document.url
string
Where to fetch the media. On an inbound message this is a Bird URL you fetch with your API key; it is absent when the file could not be retrieved from WhatsApp. It stays populated after the stored bytes expire, and the link returns 410 from then on. On an outbound message it is the URL the sender supplied, whose availability is the sender's to guarantee.
event_payload.data.document.mime_type
string
Media type WhatsApp reported for the file, for example image/jpeg. Absent on outbound messages.
event_payload.data.document.caption
string
Text shown beneath the document. Absent when the sender wrote none.
event_payload.data.document.filename
string
The sender's own name for the file.
event_payload.data.location
object
Location the contact sent.
Afficher les attributs enfants
event_payload.data.location.latitude
number
Latitude in decimal degrees.
event_payload.data.location.longitude
number
Longitude in decimal degrees.
event_payload.data.location.name
string
Name of the place. Absent when the sender shared a plain pin.
event_payload.data.location.address
string
Street address of the place. Shown only when name is also set.
event_payload.data.location.url
string
Link to the place, which WhatsApp includes mainly for business locations. Present on an inbound message when the sender's client supplied one, and absent on a message you sent, since sending a location does not support this field.
event_payload.data.contact_cards
array of object
Contact cards the contact shared, either by tapping a button that asked for their number or by sending a card from their address book.
Afficher les attributs enfants
event_payload.data.contact_cards.origin
string
Why the card arrived. contact_request means the contact tapped a button this workspace sent asking for their number, which is the only signal that the message answers that ask; other means they shared a card in the chat. Open enum: treat an unrecognized value as a way of sharing added since. Set on a card the contact shared; absent on one this workspace sent.
Possible values (may grow over time): contact_request, other
event_payload.data.contact_cards.vcard
string
The contact's card in vCard format. WhatsApp sends it on a card shared in the chat and omits it on a button tap, which carries the number alone. Set on a card the contact shared; absent on one this workspace sent.
event_payload.data.contact_cards.name
object
The contact's name, when the card carries one.
Afficher les attributs enfants
event_payload.data.contact_cards.name.formatted_name
string
The whole name as the contact's device renders it.
event_payload.data.contact_cards.name.first_name
string
event_payload.data.contact_cards.name.middle_name
string
event_payload.data.contact_cards.name.last_name
string
event_payload.data.contact_cards.name.prefix
string
event_payload.data.contact_cards.name.suffix
string
event_payload.data.contact_cards.org
object
Where the contact works, when the card carries it.
Afficher les attributs enfants
event_payload.data.contact_cards.org.company
string
event_payload.data.contact_cards.org.department
string
event_payload.data.contact_cards.org.title
string
event_payload.data.contact_cards.birthday
string
The contact's birthday, which WhatsApp sends as YYYY-MM-DD. Passed through as text rather than typed as a date: the value comes off the contact's own device unvalidated, and a card we could not parse would otherwise have to lose the field or fail the whole read.
event_payload.data.contact_cards.phone_numbers
array of object
The numbers on the card. A button tap carries the contact's own number here, which is the point of asking.
Afficher les attributs enfants
event_payload.data.contact_cards.phone_numbers.phone_number
string
The number as the card holds it, normalized to E.164 where we can parse it. A card is whatever the contact's device stored, so a number that no country's numbering plan accepts, an extension among them, is passed through exactly as it arrived rather than dropped. Parse defensively: most values are E.164 and none is guaranteed to be.
event_payload.data.contact_cards.phone_numbers.type
string
The label attached to this value, for example CELL, Home or iPhone. Free text: WhatsApp defines no vocabulary. A label on a received card is lowercased; one this workspace sent reads back exactly as sent.
event_payload.data.contact_cards.emails
array of object
Afficher les attributs enfants
event_payload.data.contact_cards.emails.email
string
event_payload.data.contact_cards.emails.type
string
The label attached to this value, for example CELL, Home or iPhone. Free text: WhatsApp defines no vocabulary. A label on a received card is lowercased; one this workspace sent reads back exactly as sent.
event_payload.data.contact_cards.urls
array of object
Afficher les attributs enfants
event_payload.data.contact_cards.urls.url
string
The address as the card holds it, which is often bare rather than a full URL, so it is passed through as text rather than validated.
event_payload.data.contact_cards.urls.type
string
The label attached to this value, for example CELL, Home or iPhone. Free text: WhatsApp defines no vocabulary. A label on a received card is lowercased; one this workspace sent reads back exactly as sent.
event_payload.data.contact_cards.addresses
array of object
Afficher les attributs enfants
event_payload.data.contact_cards.addresses.street
string
event_payload.data.contact_cards.addresses.city
string
event_payload.data.contact_cards.addresses.state
string
event_payload.data.contact_cards.addresses.zip
string
event_payload.data.contact_cards.addresses.country
string
event_payload.data.contact_cards.addresses.country_code
string
The country as the card holds it, left exactly as WhatsApp sent it: it describes a postal address rather than a routing destination.
event_payload.data.contact_cards.addresses.type
string
The label attached to this value, for example CELL, Home or iPhone. Free text: WhatsApp defines no vocabulary. A label on a received card is lowercased; one this workspace sent reads back exactly as sent.
event_payload.data.interactive_reply
object
What the contact tapped, when the message answers an interactive message or a template's quick-reply button.
Afficher les attributs enfants
event_payload.data.interactive_reply.type
string
obligatoire
Which kind of tap this reply came from, and which field carries it.
event_payload.data.interactive_reply.button
object
The button the contact tapped, as you declared it. On a reply to a template's quick-reply button, slug is the button's payload, which WhatsApp sets to the button's own label.
Afficher les attributs enfants
event_payload.data.interactive_reply.button.slug
string
obligatoire
The handle the button carries back, never shown to the recipient. On a tap on a template's quick-reply button, it is the payload that template declared.
event_payload.data.interactive_reply.button.text
string
obligatoire
The label the recipient saw.
event_payload.data.interactive_reply.list
object
The row the contact chose, as you declared it. description is present only when the row carried one.
Afficher les attributs enfants
event_payload.data.interactive_reply.list.slug
string
obligatoire
The handle the row carries back, never shown to the recipient.
event_payload.data.interactive_reply.list.text
string
obligatoire
The row's label, shown as its title in the menu.
event_payload.data.interactive_reply.list.description
string
The second line under the label. Absent when the row carried none.
event_payload.data.unsupported
object
Set when the contact sent content the API does not model, naming the WhatsApp content type.
Afficher les attributs enfants
event_payload.data.unsupported.type
string
obligatoire
The WhatsApp content type we did not model. unsupported is not a placeholder here: WhatsApp reports its own unsupported type for a message its own clients cannot render, and that arrives as this value. Open enum: WhatsApp adds content types over time, so treat an unrecognized value as a future type rather than an error.
Possible values (may grow over time): reaction, interactive, button, order, system, unsupported
The API rejected the message before sending it to WhatsApp because the recipient is on the workspace suppression list, the wallet has insufficient balance, or the destination is unpriced. The message is not sent or charged.
event_payload.type
string
obligatoire
Event type.
Possible values: whatsapp.rejected
event_payload.timestamp
string
obligatoire
Time the rejection was recorded.
event_payload.data
object
obligatoire
Payload of the whatsapp.rejected event.
Afficher les attributs enfants
event_payload.data.whatsapp_id
string
obligatoire
ID of the WhatsApp message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.direction
string
obligatoire
Whether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.from
object
obligatoire
Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Afficher les attributs enfants
event_payload.data.from.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.from.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.from.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.from.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.from.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.to
object
obligatoire
Recipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Afficher les attributs enfants
event_payload.data.to.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.to.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.to.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.to.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.to.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message. Null when the message carried no metadata.
event_payload.data.in_reply_to_message_id
string
The message this one answers. On an outbound message it is the in_reply_to_message_id the send request quoted. On an inbound message it is what WhatsApp reports as the reply's target: a tap on a button or a list row, and equally a text or media message the contact sent as a quoted reply. Absent when the message answers nothing, and absent on an inbound message whose target we cannot match to a message we hold, which is the case for one sent before this workspace started recording them or one already past the 15-day window we keep provider ids for.
event_payload.data.error
nullable object
obligatoire
Why the message was rejected before sending.
Afficher les attributs enfants
event_payload.data.error.code
string
obligatoire
Standardized failure reason:
- insufficient_balance: The workspace wallet could not fund the send.
- price_not_found: No price was configured for the destination and template.
- internal_error: An unexpected service failure occurred.
- undeliverable: The recipient could not be reached.
- service_window_expired: The 24-hour service window closed; send a template.
- rate_limited: The send was throttled.
- recipient_suppressed: The recipient is on the workspace suppression list.
- media_rejected: WhatsApp could not fetch the media URL, or refused the file it found there; description carries its reason.
This is an open enum. Accept unrecognized values.
Possible values (may grow over time): insufficient_balance, price_not_found, internal_error, undeliverable, service_window_expired, rate_limited, recipient_suppressed, media_rejected
event_payload.data.error.description
string
obligatoire
Human-readable explanation of the failure.
event_payload.data.error.meta_error_code
nullable string
Raw error code from the WhatsApp Cloud API, when available, for low-level debugging.
event_payload.data.error.occurred_at
string
obligatoire
When the failure occurred.
The API handed the message to Meta for delivery.
event_payload.type
string
obligatoire
Event type.
Possible values: whatsapp.sent
event_payload.timestamp
string
obligatoire
Time the API handed the message to Meta for delivery.
event_payload.data
object
obligatoire
Payload of the whatsapp.sent event.
Afficher les attributs enfants
event_payload.data.whatsapp_id
string
obligatoire
ID of the WhatsApp message.
event_payload.data.workspace_id
string
obligatoire
ID of the workspace that owns this event.
event_payload.data.direction
string
obligatoire
Whether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.from
object
obligatoire
Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Afficher les attributs enfants
event_payload.data.from.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.from.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.from.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.from.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.from.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.to
object
obligatoire
Recipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Afficher les attributs enfants
event_payload.data.to.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.to.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.to.group_id
string
The group this address was addressed as, or reached through. It appears on a message's to and nowhere else: never on from, and never on an event's recipient. Outbound, it stands in for the recipient, because a group send names no single phone number. Inbound, it qualifies one: to carries the business phone_number that received the message and the group it arrived through, while from stays the participant who wrote it. Its presence on to is what tells a group message from a one-to-one one, in either direction.
event_payload.data.to.username
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (WhatsAppNumberProfile.username), without a leading @; a message cannot be addressed by it.
event_payload.data.to.display_name
string
Present only on a message received from a WhatsApp user, on from; never on an outbound send's to, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them.
event_payload.data.tags
nullable array
obligatoire
Tags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadata
nullable object
obligatoire
The metadata object provided on the send request, echoed on every event for the message. Null when the message carried no metadata.
event_payload.data.in_reply_to_message_id
string
The message this one answers. On an outbound message it is the in_reply_to_message_id the send request quoted. On an inbound message it is what WhatsApp reports as the reply's target: a tap on a button or a list row, and equally a text or media message the contact sent as a quoted reply. Absent when the message answers nothing, and absent on an inbound message whose target we cannot match to a message we hold, which is the case for one sent before this workspace started recording them or one already past the 15-day window we keep provider ids for.
An address was added to the workspace's WhatsApp suppression ledger.
event_payload.type
string
obligatoire
Always whatsapp_suppression.created for this event.
Possible values: whatsapp_suppression.created
event_payload.timestamp
string
obligatoire
When the episode's opening statement took effect (effective_at).
event_payload.data
object
obligatoire
Payload of the whatsapp_suppression.created event.
Afficher les attributs enfants
event_payload.data.suppression_id
string
obligatoire
The suppression episode that was opened.
event_payload.data.address
string
obligatoire
The suppressed WhatsApp address. For a phone number this is canonical E.164 with a leading plus sign, such as +5511977670804.
event_payload.data.waba
nullable string
obligatoire
The WhatsApp Business Account the suppression is limited to, identified by its WhatsApp-issued account ID, or null when it covers the whole workspace.
event_payload.data.reason
string
obligatoire
Why the address is suppressed. manual means it was added directly rather than created automatically from a delivery outcome. This list grows over time, so treat an unknown value as informational rather than rejecting the record.
Possible values (may grow over time): manual
event_payload.data.workspace_id
string
obligatoire
The workspace the suppression belongs to.
error
string
A short explanation of why the event could not be delivered. Present only when your endpoint could not be reached.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Regarder le guideWebhooks done right: reliable delivery eventsComprendre le conceptHow do I verify a webhook signature?Suivre le parcours d'apprentissageOperate messaging reliablyGuide d'implémentationWebhooks & events
Essayez la pratique et obtenez un guide d'implémentation