Test a webhook with a sample event
/v1/webhooks/{webhook_id}/testconst 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"
}'{
"status": "delivered",
"response_status_code": 200,
"response_body": "OK",
"response_duration_ms": 142,
"event_payload": {
"type": "amb.accepted",
"timestamp": "2026-09-25T12:00:00Z",
"data": {
"workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
"message": {
"id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
"conversation_id": "acv_01krdgeqcxet5s7t44vh8rt9mg",
"business_account_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
"direction": "outbound",
"status": "accepted",
"kind": "text",
"source": "operator",
"in_reply_to_message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
"locale": "en_US",
"category": "order_update",
"tags": [
{
"name": "category",
"value": "welcome"
}
],
"cost": {
"amount": "0.00990",
"currency_code": "USD",
"transaction_amount": "0.00790",
"passthrough_amount": "0.00200"
},
"last_error": {
"code": "bird:business_not_registered",
"description": "Apple refused the message with HTTP status 404."
}
}
}
},
"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.
Parameters
webhook_idstringID of the webhook endpoint (whk_ prefix), as returned when it was created.
Request Payload
event_typeEvent 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.
Response Payload
statusWhether 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_codeHTTP status returned by your endpoint. Null when no response was received (timeout, connection error, DNS failure).
response_bodyResponse 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_msRound-trip delivery latency in milliseconds.
event_payloadThe 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.
Show child attributes
An outbound message was accepted for processing after confirming billing coverage. This does not confirm receipt by Apple.
event_payload.typeAlways amb.accepted for this event.
Possible values: amb.accepted
event_payload.timestampWhen this lifecycle event occurred, independent of webhook delivery time.
event_payload.dataThe workspace and message snapshot at the time of the lifecycle event.
Show child attributes
event_payload.data.workspace_idWorkspace that owns this message.
event_payload.data.messageMessage state when the event occurred. Later state changes do not alter this snapshot. Customer metadata is included when present; reserved Bird metadata is excluded.
Show child attributes
event_payload.data.message.idID of the message, assigned when it is accepted or received. Pass it as message_id to the get-message and list-events endpoints.
event_payload.data.message.conversation_idThe conversation this message belongs to.
event_payload.data.message.business_account_idThe business the message was sent from or received by.
event_payload.data.message.fromApple business identifier on outbound messages, or the customer's opaque Apple identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.toCustomer's opaque Apple identifier on outbound messages, or the Apple business identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.directionWhether a message was sent by the business or received from the customer:
outbound: A reply the business sent into the conversation.inbound: A message the customer sent.
Possible values: outbound, inbound
event_payload.data.message.statusSend status:
accepted: Accepted and queued for delivery to Apple.sent: Handed to Apple. There is no delivery or read receipt on this channel, sosentis the furthest an outbound message's status advances.send_failed: Sending stopped because of a business or conversation restriction, a recipient opt-out, an Apple refusal, or exhausted attempts. An earlier attempt may have reached Apple if its response or the local record of success was lost. Seelast_errorfor why sending stopped.rejected: Refused by Bird before any send attempt and never charged: the destination has no price, the wallet could not fund the send, or the content cannot be sent yet. Seelast_error.received: Received as an inbound message.
Possible values: accepted, sent, send_failed, rejected, received
event_payload.data.message.kindDerived content classification for filtering and statistics.
Possible values: text, attachment, rich_link, quick_reply, list_picker, time_picker, form, apple_pay, authenticate, imessage_app, interactive
event_payload.data.message.sourceWho sent this message. Absent on an inbound message, which has no source to report.
Possible values: operator, automation, api
event_payload.data.message.contentNative message content. Outgoing interactions contain requests; incoming interactions contain replies.
Show child attributes
event_payload.data.message.content.typeAlways text.
Value: text
event_payload.data.message.content.bodyText displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
event_payload.data.message.content.subjectSubject displayed above the message body.
event_payload.data.message.content.attachmentsOrdered attachments. Each object supplies a source URL or an encrypted Apple reference.
Show child attributes
event_payload.data.message.content.attachments.source_urlHTTPS URL Bird downloads and uploads to Apple.
event_payload.data.message.content.attachments.nameDisplay filename.
event_payload.data.message.content.attachments.mime_typeMedia type of the attachment.
event_payload.data.message.content.attachments.nameDisplay filename.
event_payload.data.message.content.attachments.mime_typeMedia type of the attachment.
event_payload.data.message.content.attachments.urlEncrypted attachment URL returned by Apple.
event_payload.data.message.content.attachments.ownerOpaque owner value returned by Apple.
event_payload.data.message.content.attachments.signature_base64Attachment authorization signature returned by Apple.
event_payload.data.message.content.attachments.keyAttachment decryption key returned by Apple.
event_payload.data.message.content.attachments.sizeAttachment size in bytes.
event_payload.data.message.content.rich_link_dataShow child attributes
event_payload.data.message.content.rich_link_data.urlHTTPS URL opened by the preview.
event_payload.data.message.content.rich_link_data.titlePreview title.
event_payload.data.message.content.rich_link_data.assetsShow child attributes
event_payload.data.message.content.rich_link_data.assets.imageShow child attributes
event_payload.data.message.content.rich_link_data.assets.image.source_urlHTTPS URL of a PNG preview image up to 200 kB. Bird fetches and encodes it when sending.
event_payload.data.message.content.rich_link_data.assets.image.mime_typePNG media type required by Apple. Defaults to image/png.
Value: image/png
event_payload.data.message.content.rich_link_data.assets.videoShow child attributes
event_payload.data.message.content.rich_link_data.assets.video.urlHTTPS video URL fetched by Apple.
event_payload.data.message.content.rich_link_data.assets.video.mime_typeMedia type of the video. Defaults to video/mp4; supply the actual type for other formats.
event_payload.data.message.content.rich_link_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Show child attributes
event_payload.data.message.content.rich_link_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.rich_link_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.content.rich_link_data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.interactive_dataA built-in interaction or custom iMessage app. Custom apps require the app metadata and both message bubbles.
Show child attributes
event_payload.data.message.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.dataExactly one built-in interaction. Protocol versions are managed by Bird.
Show child attributes
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.quick_replyShow child attributes
event_payload.data.message.content.interactive_data.data.quick_reply.summary_textText used for the device notification and shown in the transcript after the customer chooses an item. Send a separate text message to introduce the choices.
event_payload.data.message.content.interactive_data.data.quick_reply.itemsThe buttons offered to the customer. Apple requires between two and five; outside that range the request is refused with a 422 AMBQuickReplyItemsInvalid. For more choices, send list_picker content instead.
Show child attributes
event_payload.data.message.content.interactive_data.data.quick_reply.items.identifierOpaque choice identifier returned in interactive_data.data.quick_reply.selected_identifier.
event_payload.data.message.content.interactive_data.data.quick_reply.items.titleLabel shown on the button.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.list_pickerShow child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sectionsThe menu's sections, each with its own heading and rows.
Show child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sections.titleHeading shown above this section's rows.
event_payload.data.message.content.interactive_data.data.list_picker.sections.orderWhere this section sits relative to its siblings, ascending. Sections omitting it are laid out in list order, after any that specify one.
event_payload.data.message.content.interactive_data.data.list_picker.sections.itemsThe rows in this section.
Show child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.identifierOpaque item identifier returned in interactive_data.data.list_picker.sections.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.titleLabel shown on the row.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.subtitleSecondary line shown under the title.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.image_identifierIdentifier of an image in interactive_data.data.images, shown next to this row. A key with no matching entry in images is refused with a 422 AMBInteractiveImageInvalid.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.orderPosition within the section, ascending. Defaults to the row's array position.
event_payload.data.message.content.interactive_data.data.list_picker.sections.multiple_selectionWhether the customer can select more than one row in this section.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.eventShow child attributes
event_payload.data.message.content.interactive_data.data.event.identifierYour identifier for the event. Defaults to the message identifier.
event_payload.data.message.content.interactive_data.data.event.locationOptional appointment location.
Show child attributes
event_payload.data.message.content.interactive_data.data.event.location.titleName shown for the appointment location.
event_payload.data.message.content.interactive_data.data.event.location.latitudeLatitude in degrees. Set together with longitude.
event_payload.data.message.content.interactive_data.data.event.location.longitudeLongitude in degrees. Set together with latitude.
event_payload.data.message.content.interactive_data.data.event.location.radiusLocation radius in meters. Apple ignores it without coordinates.
event_payload.data.message.content.interactive_data.data.event.timezone_offsetMinutes from GMT at the event location. Omit to use the customer's time zone.
event_payload.data.message.content.interactive_data.data.event.timeslotsAppointment times with RFC 3339 timestamps and duration in seconds.
Show child attributes
event_payload.data.message.content.interactive_data.data.event.timeslots.identifierOpaque slot identifier. Apple may instead return only a localized label in interactive_data.reply_message.title.
event_payload.data.message.content.interactive_data.data.event.timeslots.start_atWhen this slot begins. Seconds and fractional seconds must be zero, for example 2026-09-02T14:30:00Z; otherwise sending returns 422 with error code E01001. The timestamp is converted to UTC for Apple while preserving the instant.
event_payload.data.message.content.interactive_data.data.event.timeslots.duration_secondsDuration in seconds. Zero indicates no duration.
event_payload.data.message.content.interactive_data.data.event.image_identifierIdentifier of the event image in interactive_data.data.images.
event_payload.data.message.content.interactive_data.data.event.titleEvent title.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.dynamicForm content. Bird supplies Apple’s messageForms template and protocol version.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.dataShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.start_page_identifierIdentifier of the first page to show.
event_payload.data.message.content.interactive_data.data.dynamic.data.privateWhether Apple marks the submitted response as private.
event_payload.data.message.content.interactive_data.data.dynamic.data.show_summaryWhether Apple shows a summary before the customer submits.
event_payload.data.message.content.interactive_data.data.dynamic.data.splashShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.splash.headerevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.splash_textevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.button_titleevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.image_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pagesForm pages referenced by the start page and navigation identifiers.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: select
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.multiple_selectionevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.itemsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.valueevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.image_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.next_page_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: picker
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.picker_titleText beside the picker field. Omit to center the field without a label.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.selected_item_indexZero-based index into items. Defaults to 0. Must be less than the number of items; otherwise sending returns 422 AMBFormPagesInvalid.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.itemsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.valueevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: date_picker
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.hint_textevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.optionsApple defaults to UTC when interpreting these dates.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.date_formatFormat used to read the date values in these options. Defaults to MM/dd/yyyy.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.start_dateDate initially shown by the picker, written in date_format. Defaults to the current date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.maximum_dateLatest date the picker shows, written in date_format. Defaults to the current date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.minimum_dateEarliest date the picker shows, written in date_format.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.label_textLabel beside the date field. Defaults to Date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: input
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.hint_textevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.optionsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.regexPattern Apple uses to validate the input. Use JSON string escaping for backslashes.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.placeholderShown when the field is empty. Defaults to Required when required is true, otherwise Optional.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.requiredDisables the next-page button until the customer enters a value.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.input_typeDefaults to singleline.
Possible values: singleline, multiline
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.label_textLabel for singleline input only. Omit for no label.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.prefix_textText beside singleline input only, such as a currency symbol. Omit for no prefix.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.maximum_character_countDefaults to 30 for singleline input and 300 for multiline input.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.keyboard_typeKeyboard to display. Defaults to default.
Possible values (may grow over time): default, asciiCapable, numbersAndPunctuation, URL, numberPad, phonePad, namePhonePad, emailAddress, decimalPad, webSearch
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.text_content_typeContent hint used for autofill.
Possible values (may grow over time): name, namePrefix, givenName, middleName, familyName, nameSuffix, nickname, jobTitle, organizationName, location, fullStreetAddress, streetAddressLine1, streetAddressLine2, addressCity, addressState, addressCityAndState, sublocality, countryName, postalCode, telephoneNumber, emailAddress, URL, creditCardNumber, username, password, newPassword, oneTimeCode
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.authenticateAuthentication attempt created through the conversation authentication endpoint. Contains no authorization parameters or credentials.
Show child attributes
event_payload.data.message.content.interactive_data.data.authenticate.authentication_idevent_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.paymentApple Pay request created through the conversation payment endpoint. Contains no payment token or provider credentials.
Show child attributes
event_payload.data.message.content.interactive_data.data.payment.payment_idevent_payload.data.message.content.interactive_data.app_idApp Store identifier of the iMessage app.
event_payload.data.message.content.interactive_data.app_nameName of the iMessage app.
event_payload.data.message.content.interactive_data.bidIdentifier of the iMessage extension, in Apple's com.apple.messages.MSMessageExtensionBalloonPlugin:team-id:extension-id format.
event_payload.data.message.content.interactive_data.urlOpaque URL string that Messages passes to the iMessage app.
event_payload.data.message.content.interactive_data.use_live_layoutWhether Messages renders the received and reply bubbles using Live Layout.
event_payload.data.message.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.received_messageContent Messages shows in the received message bubble.
Show child attributes
event_payload.data.message.content.interactive_data.received_message.titleText shown on the message bubble.
event_payload.data.message.content.interactive_data.received_message.subtitleSecondary text shown below the title.
event_payload.data.message.content.interactive_data.received_message.styleBubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
event_payload.data.message.content.interactive_data.received_message.image_identifierIdentifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
event_payload.data.message.content.interactive_data.received_message.image_titleTitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.image_subtitleSubtitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.secondary_subtitleRight-aligned title in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.tertiary_subtitleRight-aligned subtitle in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_messageContent Messages shows in the reply message bubble.
Show child attributes
event_payload.data.message.content.interactive_data.reply_message.titleText shown on the message bubble.
event_payload.data.message.content.interactive_data.reply_message.subtitleSecondary text shown below the title.
event_payload.data.message.content.interactive_data.reply_message.styleBubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
event_payload.data.message.content.interactive_data.reply_message.image_identifierIdentifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
event_payload.data.message.content.interactive_data.reply_message.image_titleTitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.image_subtitleSubtitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.secondary_subtitleRight-aligned title in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.tertiary_subtitleRight-aligned subtitle in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.app_icon_source_urlPublicly accessible HTTPS URL of the app's PNG icon. The icon must be smaller than 15 kB. We fetch and include it in the request to Apple.
event_payload.data.message.content.interactive_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Show child attributes
event_payload.data.message.content.interactive_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.content.interactive_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.interactive_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.content.interactive_data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.content.interactive_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.in_reply_to_message_idOriginal message matched through Apple’s request identifier within the same workspace, business, and conversation. Omitted when no verified match exists.
event_payload.data.message.localeLocale for this message, preserved in Apple’s format, for example en_US. Outbound messages use the request override, then the conversation locale, then the business default. Inbound messages preserve the locale in Apple’s callback. Null when unknown.
event_payload.data.message.categoryThe category this message was sent with, for reporting only. It does not affect sending or suppression policy, or select an Apple department or purpose. Defaults to an empty string when a send names no category. Absent on an inbound message, which has no category to report.
event_payload.data.message.metadataArbitrary JSON object for per-message context. Maximum 2 KB serialized. Top-level keys beginning with __bird are reserved. Returned in the send response, message reads and customer message webhooks.
event_payload.data.message.tagsStructured {name, value} filter labels applied to this message. Absent on an inbound message.
Show child attributes
event_payload.data.message.tags.nameTag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
event_payload.data.message.tags.valueTag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
event_payload.data.message.costRecorded per-message charge before MAC pricing. Null in the initial send response, while unpriced, and for MAC-covered replies. MAC fees belong to monthly contact usage, not individual messages. Historical charges have no priced passthrough component.
Show child attributes
event_payload.data.message.cost.amountTotal 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.message.cost.currency_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.message.cost.transaction_amountWhat 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.message.cost.passthrough_amountThird-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.message.last_errorFailure detail on a message whose send failed or that Bird rejected before any send attempt. Omitted when there is no failure detail.
Show child attributes
event_payload.data.message.last_error.codeMachine-readable reason a send failed, in one of two namespaces: bird: for a reason Bird's own pipeline assigned (for example bird:business_not_registered), or apple: followed by the HTTP status Apple's API returned for the send attempt (for example apple:404). This is an open, growing set in both namespaces; accept unrecognized values.
event_payload.data.message.last_error.descriptionThe failure in words. Free-form, so branch on code and show this to a human.
event_payload.data.message.last_error.occurred_atWhen the failure occurred.
event_payload.data.message.created_atThe moment this message was accepted (outbound) or received (inbound). This is the timestamp the outbound statistics families bucket and attribute on; there is no separate accepted_at field.
event_payload.data.message.sent_atWhen the selected sending outcome occurred. Null unless the current status is sent and the message is outbound. For older messages without a retained sending event, the stored record time is used.
event_payload.data.message.data_refReusable encrypted content reference returned by Apple after a successful send. Absent until Apple returns one.
Show child attributes
event_payload.data.message.data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.data_ref.urlLocation of the encrypted preview.
event_payload.data.message.data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.data_ref.urlLocation of the encrypted preview.
event_payload.data.message.data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.groupApple department identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
event_payload.data.message.intentApple purpose identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
A customer conversation closed. Closing a conversation is not a message.
event_payload.typeAlways amb.conversation_closed for this event.
Possible values: amb.conversation_closed
event_payload.timestampWhen this lifecycle event occurred, independent of webhook delivery time.
event_payload.dataConversation identity and routing context when a lifecycle event occurred.
Show child attributes
event_payload.data.workspace_idWorkspace that owns this conversation.
event_payload.data.business_account_idBusiness that owns this conversation.
event_payload.data.conversation_idConversation that changed state.
event_payload.data.open_countNumber of times the conversation has opened, starting at 1 and increasing on each reopen. Together with the conversation ID and event type, this identifies the lifecycle occurrence across retries.
event_payload.data.originSource of the lifecycle change, when recorded.
event_payload.data.group_idApple entry-point group recorded for this occurrence, when present.
event_payload.data.intent_idApple entry-point intent recorded for this occurrence, when present.
event_payload.data.queueRouting queue recorded for this occurrence, when present.
An existing customer conversation reopened after it had closed.
event_payload.typeAlways amb.conversation_reopened for this event.
Possible values: amb.conversation_reopened
event_payload.timestampWhen this lifecycle event occurred, independent of webhook delivery time.
event_payload.dataConversation identity and routing context when a lifecycle event occurred.
Show child attributes
event_payload.data.workspace_idWorkspace that owns this conversation.
event_payload.data.business_account_idBusiness that owns this conversation.
event_payload.data.conversation_idConversation that changed state.
event_payload.data.open_countNumber of times the conversation has opened, starting at 1 and increasing on each reopen. Together with the conversation ID and event type, this identifies the lifecycle occurrence across retries.
event_payload.data.originSource of the lifecycle change, when recorded.
event_payload.data.group_idApple entry-point group recorded for this occurrence, when present.
event_payload.data.intent_idApple entry-point intent recorded for this occurrence, when present.
event_payload.data.queueRouting queue recorded for this occurrence, when present.
A customer conversation opened for the first time.
event_payload.typeAlways amb.conversation_started for this event.
Possible values: amb.conversation_started
event_payload.timestampWhen this lifecycle event occurred, independent of webhook delivery time.
event_payload.dataConversation identity and routing context when a lifecycle event occurred.
Show child attributes
event_payload.data.workspace_idWorkspace that owns this conversation.
event_payload.data.business_account_idBusiness that owns this conversation.
event_payload.data.conversation_idConversation that changed state.
event_payload.data.open_countNumber of times the conversation has opened, starting at 1 and increasing on each reopen. Together with the conversation ID and event type, this identifies the lifecycle occurrence across retries.
event_payload.data.originSource of the lifecycle change, when recorded.
event_payload.data.group_idApple entry-point group recorded for this occurrence, when present.
event_payload.data.intent_idApple entry-point intent recorded for this occurrence, when present.
event_payload.data.queueRouting queue recorded for this occurrence, when present.
Bird received an ordinary customer message from Apple. Invitation responses are excluded.
event_payload.typeAlways amb.received for this event.
Possible values: amb.received
event_payload.timestampWhen this lifecycle event occurred, independent of webhook delivery time.
event_payload.dataThe workspace and message snapshot at the time of the lifecycle event.
Show child attributes
event_payload.data.workspace_idWorkspace that owns this message.
event_payload.data.messageMessage state when the event occurred. Later state changes do not alter this snapshot. Customer metadata is included when present; reserved Bird metadata is excluded.
Show child attributes
event_payload.data.message.idID of the message, assigned when it is accepted or received. Pass it as message_id to the get-message and list-events endpoints.
event_payload.data.message.conversation_idThe conversation this message belongs to.
event_payload.data.message.business_account_idThe business the message was sent from or received by.
event_payload.data.message.fromApple business identifier on outbound messages, or the customer's opaque Apple identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.toCustomer's opaque Apple identifier on outbound messages, or the Apple business identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.directionWhether a message was sent by the business or received from the customer:
outbound: A reply the business sent into the conversation.inbound: A message the customer sent.
Possible values: outbound, inbound
event_payload.data.message.statusSend status:
accepted: Accepted and queued for delivery to Apple.sent: Handed to Apple. There is no delivery or read receipt on this channel, sosentis the furthest an outbound message's status advances.send_failed: Sending stopped because of a business or conversation restriction, a recipient opt-out, an Apple refusal, or exhausted attempts. An earlier attempt may have reached Apple if its response or the local record of success was lost. Seelast_errorfor why sending stopped.rejected: Refused by Bird before any send attempt and never charged: the destination has no price, the wallet could not fund the send, or the content cannot be sent yet. Seelast_error.received: Received as an inbound message.
Possible values: accepted, sent, send_failed, rejected, received
event_payload.data.message.kindDerived content classification for filtering and statistics.
Possible values: text, attachment, rich_link, quick_reply, list_picker, time_picker, form, apple_pay, authenticate, imessage_app, interactive
event_payload.data.message.sourceWho sent this message. Absent on an inbound message, which has no source to report.
Possible values: operator, automation, api
event_payload.data.message.contentNative message content. Outgoing interactions contain requests; incoming interactions contain replies.
Show child attributes
event_payload.data.message.content.typeAlways text.
Value: text
event_payload.data.message.content.bodyText displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
event_payload.data.message.content.subjectSubject displayed above the message body.
event_payload.data.message.content.attachmentsOrdered attachments. Each object supplies a source URL or an encrypted Apple reference.
Show child attributes
event_payload.data.message.content.attachments.source_urlHTTPS URL Bird downloads and uploads to Apple.
event_payload.data.message.content.attachments.nameDisplay filename.
event_payload.data.message.content.attachments.mime_typeMedia type of the attachment.
event_payload.data.message.content.attachments.nameDisplay filename.
event_payload.data.message.content.attachments.mime_typeMedia type of the attachment.
event_payload.data.message.content.attachments.urlEncrypted attachment URL returned by Apple.
event_payload.data.message.content.attachments.ownerOpaque owner value returned by Apple.
event_payload.data.message.content.attachments.signature_base64Attachment authorization signature returned by Apple.
event_payload.data.message.content.attachments.keyAttachment decryption key returned by Apple.
event_payload.data.message.content.attachments.sizeAttachment size in bytes.
event_payload.data.message.content.rich_link_dataShow child attributes
event_payload.data.message.content.rich_link_data.urlHTTPS URL opened by the preview.
event_payload.data.message.content.rich_link_data.titlePreview title.
event_payload.data.message.content.rich_link_data.assetsShow child attributes
event_payload.data.message.content.rich_link_data.assets.imageShow child attributes
event_payload.data.message.content.rich_link_data.assets.image.source_urlHTTPS URL of a PNG preview image up to 200 kB. Bird fetches and encodes it when sending.
event_payload.data.message.content.rich_link_data.assets.image.mime_typePNG media type required by Apple. Defaults to image/png.
Value: image/png
event_payload.data.message.content.rich_link_data.assets.videoShow child attributes
event_payload.data.message.content.rich_link_data.assets.video.urlHTTPS video URL fetched by Apple.
event_payload.data.message.content.rich_link_data.assets.video.mime_typeMedia type of the video. Defaults to video/mp4; supply the actual type for other formats.
event_payload.data.message.content.rich_link_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Show child attributes
event_payload.data.message.content.rich_link_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.rich_link_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.content.rich_link_data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.interactive_dataA built-in interaction or custom iMessage app. Custom apps require the app metadata and both message bubbles.
Show child attributes
event_payload.data.message.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.dataExactly one built-in interaction. Protocol versions are managed by Bird.
Show child attributes
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.quick_replyShow child attributes
event_payload.data.message.content.interactive_data.data.quick_reply.summary_textText used for the device notification and shown in the transcript after the customer chooses an item. Send a separate text message to introduce the choices.
event_payload.data.message.content.interactive_data.data.quick_reply.itemsThe buttons offered to the customer. Apple requires between two and five; outside that range the request is refused with a 422 AMBQuickReplyItemsInvalid. For more choices, send list_picker content instead.
Show child attributes
event_payload.data.message.content.interactive_data.data.quick_reply.items.identifierOpaque choice identifier returned in interactive_data.data.quick_reply.selected_identifier.
event_payload.data.message.content.interactive_data.data.quick_reply.items.titleLabel shown on the button.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.list_pickerShow child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sectionsThe menu's sections, each with its own heading and rows.
Show child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sections.titleHeading shown above this section's rows.
event_payload.data.message.content.interactive_data.data.list_picker.sections.orderWhere this section sits relative to its siblings, ascending. Sections omitting it are laid out in list order, after any that specify one.
event_payload.data.message.content.interactive_data.data.list_picker.sections.itemsThe rows in this section.
Show child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.identifierOpaque item identifier returned in interactive_data.data.list_picker.sections.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.titleLabel shown on the row.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.subtitleSecondary line shown under the title.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.image_identifierIdentifier of an image in interactive_data.data.images, shown next to this row. A key with no matching entry in images is refused with a 422 AMBInteractiveImageInvalid.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.orderPosition within the section, ascending. Defaults to the row's array position.
event_payload.data.message.content.interactive_data.data.list_picker.sections.multiple_selectionWhether the customer can select more than one row in this section.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.eventShow child attributes
event_payload.data.message.content.interactive_data.data.event.identifierYour identifier for the event. Defaults to the message identifier.
event_payload.data.message.content.interactive_data.data.event.locationOptional appointment location.
Show child attributes
event_payload.data.message.content.interactive_data.data.event.location.titleName shown for the appointment location.
event_payload.data.message.content.interactive_data.data.event.location.latitudeLatitude in degrees. Set together with longitude.
event_payload.data.message.content.interactive_data.data.event.location.longitudeLongitude in degrees. Set together with latitude.
event_payload.data.message.content.interactive_data.data.event.location.radiusLocation radius in meters. Apple ignores it without coordinates.
event_payload.data.message.content.interactive_data.data.event.timezone_offsetMinutes from GMT at the event location. Omit to use the customer's time zone.
event_payload.data.message.content.interactive_data.data.event.timeslotsAppointment times with RFC 3339 timestamps and duration in seconds.
Show child attributes
event_payload.data.message.content.interactive_data.data.event.timeslots.identifierOpaque slot identifier. Apple may instead return only a localized label in interactive_data.reply_message.title.
event_payload.data.message.content.interactive_data.data.event.timeslots.start_atWhen this slot begins. Seconds and fractional seconds must be zero, for example 2026-09-02T14:30:00Z; otherwise sending returns 422 with error code E01001. The timestamp is converted to UTC for Apple while preserving the instant.
event_payload.data.message.content.interactive_data.data.event.timeslots.duration_secondsDuration in seconds. Zero indicates no duration.
event_payload.data.message.content.interactive_data.data.event.image_identifierIdentifier of the event image in interactive_data.data.images.
event_payload.data.message.content.interactive_data.data.event.titleEvent title.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.dynamicForm content. Bird supplies Apple’s messageForms template and protocol version.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.dataShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.start_page_identifierIdentifier of the first page to show.
event_payload.data.message.content.interactive_data.data.dynamic.data.privateWhether Apple marks the submitted response as private.
event_payload.data.message.content.interactive_data.data.dynamic.data.show_summaryWhether Apple shows a summary before the customer submits.
event_payload.data.message.content.interactive_data.data.dynamic.data.splashShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.splash.headerevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.splash_textevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.button_titleevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.image_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pagesForm pages referenced by the start page and navigation identifiers.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: select
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.multiple_selectionevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.itemsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.valueevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.image_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.next_page_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: picker
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.picker_titleText beside the picker field. Omit to center the field without a label.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.selected_item_indexZero-based index into items. Defaults to 0. Must be less than the number of items; otherwise sending returns 422 AMBFormPagesInvalid.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.itemsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.valueevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: date_picker
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.hint_textevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.optionsApple defaults to UTC when interpreting these dates.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.date_formatFormat used to read the date values in these options. Defaults to MM/dd/yyyy.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.start_dateDate initially shown by the picker, written in date_format. Defaults to the current date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.maximum_dateLatest date the picker shows, written in date_format. Defaults to the current date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.minimum_dateEarliest date the picker shows, written in date_format.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.label_textLabel beside the date field. Defaults to Date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: input
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.hint_textevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.optionsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.regexPattern Apple uses to validate the input. Use JSON string escaping for backslashes.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.placeholderShown when the field is empty. Defaults to Required when required is true, otherwise Optional.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.requiredDisables the next-page button until the customer enters a value.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.input_typeDefaults to singleline.
Possible values: singleline, multiline
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.label_textLabel for singleline input only. Omit for no label.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.prefix_textText beside singleline input only, such as a currency symbol. Omit for no prefix.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.maximum_character_countDefaults to 30 for singleline input and 300 for multiline input.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.keyboard_typeKeyboard to display. Defaults to default.
Possible values (may grow over time): default, asciiCapable, numbersAndPunctuation, URL, numberPad, phonePad, namePhonePad, emailAddress, decimalPad, webSearch
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.text_content_typeContent hint used for autofill.
Possible values (may grow over time): name, namePrefix, givenName, middleName, familyName, nameSuffix, nickname, jobTitle, organizationName, location, fullStreetAddress, streetAddressLine1, streetAddressLine2, addressCity, addressState, addressCityAndState, sublocality, countryName, postalCode, telephoneNumber, emailAddress, URL, creditCardNumber, username, password, newPassword, oneTimeCode
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.authenticateAuthentication attempt created through the conversation authentication endpoint. Contains no authorization parameters or credentials.
Show child attributes
event_payload.data.message.content.interactive_data.data.authenticate.authentication_idevent_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.paymentApple Pay request created through the conversation payment endpoint. Contains no payment token or provider credentials.
Show child attributes
event_payload.data.message.content.interactive_data.data.payment.payment_idevent_payload.data.message.content.interactive_data.app_idApp Store identifier of the iMessage app.
event_payload.data.message.content.interactive_data.app_nameName of the iMessage app.
event_payload.data.message.content.interactive_data.bidIdentifier of the iMessage extension, in Apple's com.apple.messages.MSMessageExtensionBalloonPlugin:team-id:extension-id format.
event_payload.data.message.content.interactive_data.urlOpaque URL string that Messages passes to the iMessage app.
event_payload.data.message.content.interactive_data.use_live_layoutWhether Messages renders the received and reply bubbles using Live Layout.
event_payload.data.message.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.received_messageContent Messages shows in the received message bubble.
Show child attributes
event_payload.data.message.content.interactive_data.received_message.titleText shown on the message bubble.
event_payload.data.message.content.interactive_data.received_message.subtitleSecondary text shown below the title.
event_payload.data.message.content.interactive_data.received_message.styleBubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
event_payload.data.message.content.interactive_data.received_message.image_identifierIdentifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
event_payload.data.message.content.interactive_data.received_message.image_titleTitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.image_subtitleSubtitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.secondary_subtitleRight-aligned title in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.tertiary_subtitleRight-aligned subtitle in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_messageContent Messages shows in the reply message bubble.
Show child attributes
event_payload.data.message.content.interactive_data.reply_message.titleText shown on the message bubble.
event_payload.data.message.content.interactive_data.reply_message.subtitleSecondary text shown below the title.
event_payload.data.message.content.interactive_data.reply_message.styleBubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
event_payload.data.message.content.interactive_data.reply_message.image_identifierIdentifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
event_payload.data.message.content.interactive_data.reply_message.image_titleTitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.image_subtitleSubtitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.secondary_subtitleRight-aligned title in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.tertiary_subtitleRight-aligned subtitle in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.app_icon_source_urlPublicly accessible HTTPS URL of the app's PNG icon. The icon must be smaller than 15 kB. We fetch and include it in the request to Apple.
event_payload.data.message.content.interactive_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Show child attributes
event_payload.data.message.content.interactive_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.content.interactive_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.interactive_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.content.interactive_data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.content.interactive_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.in_reply_to_message_idOriginal message matched through Apple’s request identifier within the same workspace, business, and conversation. Omitted when no verified match exists.
event_payload.data.message.localeLocale for this message, preserved in Apple’s format, for example en_US. Outbound messages use the request override, then the conversation locale, then the business default. Inbound messages preserve the locale in Apple’s callback. Null when unknown.
event_payload.data.message.categoryThe category this message was sent with, for reporting only. It does not affect sending or suppression policy, or select an Apple department or purpose. Defaults to an empty string when a send names no category. Absent on an inbound message, which has no category to report.
event_payload.data.message.metadataArbitrary JSON object for per-message context. Maximum 2 KB serialized. Top-level keys beginning with __bird are reserved. Returned in the send response, message reads and customer message webhooks.
event_payload.data.message.tagsStructured {name, value} filter labels applied to this message. Absent on an inbound message.
Show child attributes
event_payload.data.message.tags.nameTag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
event_payload.data.message.tags.valueTag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
event_payload.data.message.costRecorded per-message charge before MAC pricing. Null in the initial send response, while unpriced, and for MAC-covered replies. MAC fees belong to monthly contact usage, not individual messages. Historical charges have no priced passthrough component.
Show child attributes
event_payload.data.message.cost.amountTotal 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.message.cost.currency_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.message.cost.transaction_amountWhat 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.message.cost.passthrough_amountThird-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.message.last_errorFailure detail on a message whose send failed or that Bird rejected before any send attempt. Omitted when there is no failure detail.
Show child attributes
event_payload.data.message.last_error.codeMachine-readable reason a send failed, in one of two namespaces: bird: for a reason Bird's own pipeline assigned (for example bird:business_not_registered), or apple: followed by the HTTP status Apple's API returned for the send attempt (for example apple:404). This is an open, growing set in both namespaces; accept unrecognized values.
event_payload.data.message.last_error.descriptionThe failure in words. Free-form, so branch on code and show this to a human.
event_payload.data.message.last_error.occurred_atWhen the failure occurred.
event_payload.data.message.created_atThe moment this message was accepted (outbound) or received (inbound). This is the timestamp the outbound statistics families bucket and attribute on; there is no separate accepted_at field.
event_payload.data.message.sent_atWhen the selected sending outcome occurred. Null unless the current status is sent and the message is outbound. For older messages without a retained sending event, the stored record time is used.
event_payload.data.message.data_refReusable encrypted content reference returned by Apple after a successful send. Absent until Apple returns one.
Show child attributes
event_payload.data.message.data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.data_ref.urlLocation of the encrypted preview.
event_payload.data.message.data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.data_ref.urlLocation of the encrypted preview.
event_payload.data.message.data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.groupApple department identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
event_payload.data.message.intentApple purpose identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
Bird refused an outbound message before acceptance. This message has no accepted event.
event_payload.typeAlways amb.rejected for this event.
Possible values: amb.rejected
event_payload.timestampWhen this lifecycle event occurred, independent of webhook delivery time.
event_payload.dataThe workspace and message snapshot at the time of the lifecycle event.
Show child attributes
event_payload.data.workspace_idWorkspace that owns this message.
event_payload.data.messageMessage state when the event occurred. Later state changes do not alter this snapshot. Customer metadata is included when present; reserved Bird metadata is excluded.
Show child attributes
event_payload.data.message.idID of the message, assigned when it is accepted or received. Pass it as message_id to the get-message and list-events endpoints.
event_payload.data.message.conversation_idThe conversation this message belongs to.
event_payload.data.message.business_account_idThe business the message was sent from or received by.
event_payload.data.message.fromApple business identifier on outbound messages, or the customer's opaque Apple identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.toCustomer's opaque Apple identifier on outbound messages, or the Apple business identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.directionWhether a message was sent by the business or received from the customer:
outbound: A reply the business sent into the conversation.inbound: A message the customer sent.
Possible values: outbound, inbound
event_payload.data.message.statusSend status:
accepted: Accepted and queued for delivery to Apple.sent: Handed to Apple. There is no delivery or read receipt on this channel, sosentis the furthest an outbound message's status advances.send_failed: Sending stopped because of a business or conversation restriction, a recipient opt-out, an Apple refusal, or exhausted attempts. An earlier attempt may have reached Apple if its response or the local record of success was lost. Seelast_errorfor why sending stopped.rejected: Refused by Bird before any send attempt and never charged: the destination has no price, the wallet could not fund the send, or the content cannot be sent yet. Seelast_error.received: Received as an inbound message.
Possible values: accepted, sent, send_failed, rejected, received
event_payload.data.message.kindDerived content classification for filtering and statistics.
Possible values: text, attachment, rich_link, quick_reply, list_picker, time_picker, form, apple_pay, authenticate, imessage_app, interactive
event_payload.data.message.sourceWho sent this message. Absent on an inbound message, which has no source to report.
Possible values: operator, automation, api
event_payload.data.message.contentNative message content. Outgoing interactions contain requests; incoming interactions contain replies.
Show child attributes
event_payload.data.message.content.typeAlways text.
Value: text
event_payload.data.message.content.bodyText displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
event_payload.data.message.content.subjectSubject displayed above the message body.
event_payload.data.message.content.attachmentsOrdered attachments. Each object supplies a source URL or an encrypted Apple reference.
Show child attributes
event_payload.data.message.content.attachments.source_urlHTTPS URL Bird downloads and uploads to Apple.
event_payload.data.message.content.attachments.nameDisplay filename.
event_payload.data.message.content.attachments.mime_typeMedia type of the attachment.
event_payload.data.message.content.attachments.nameDisplay filename.
event_payload.data.message.content.attachments.mime_typeMedia type of the attachment.
event_payload.data.message.content.attachments.urlEncrypted attachment URL returned by Apple.
event_payload.data.message.content.attachments.ownerOpaque owner value returned by Apple.
event_payload.data.message.content.attachments.signature_base64Attachment authorization signature returned by Apple.
event_payload.data.message.content.attachments.keyAttachment decryption key returned by Apple.
event_payload.data.message.content.attachments.sizeAttachment size in bytes.
event_payload.data.message.content.rich_link_dataShow child attributes
event_payload.data.message.content.rich_link_data.urlHTTPS URL opened by the preview.
event_payload.data.message.content.rich_link_data.titlePreview title.
event_payload.data.message.content.rich_link_data.assetsShow child attributes
event_payload.data.message.content.rich_link_data.assets.imageShow child attributes
event_payload.data.message.content.rich_link_data.assets.image.source_urlHTTPS URL of a PNG preview image up to 200 kB. Bird fetches and encodes it when sending.
event_payload.data.message.content.rich_link_data.assets.image.mime_typePNG media type required by Apple. Defaults to image/png.
Value: image/png
event_payload.data.message.content.rich_link_data.assets.videoShow child attributes
event_payload.data.message.content.rich_link_data.assets.video.urlHTTPS video URL fetched by Apple.
event_payload.data.message.content.rich_link_data.assets.video.mime_typeMedia type of the video. Defaults to video/mp4; supply the actual type for other formats.
event_payload.data.message.content.rich_link_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Show child attributes
event_payload.data.message.content.rich_link_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.rich_link_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.content.rich_link_data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.interactive_dataA built-in interaction or custom iMessage app. Custom apps require the app metadata and both message bubbles.
Show child attributes
event_payload.data.message.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.dataExactly one built-in interaction. Protocol versions are managed by Bird.
Show child attributes
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.quick_replyShow child attributes
event_payload.data.message.content.interactive_data.data.quick_reply.summary_textText used for the device notification and shown in the transcript after the customer chooses an item. Send a separate text message to introduce the choices.
event_payload.data.message.content.interactive_data.data.quick_reply.itemsThe buttons offered to the customer. Apple requires between two and five; outside that range the request is refused with a 422 AMBQuickReplyItemsInvalid. For more choices, send list_picker content instead.
Show child attributes
event_payload.data.message.content.interactive_data.data.quick_reply.items.identifierOpaque choice identifier returned in interactive_data.data.quick_reply.selected_identifier.
event_payload.data.message.content.interactive_data.data.quick_reply.items.titleLabel shown on the button.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.list_pickerShow child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sectionsThe menu's sections, each with its own heading and rows.
Show child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sections.titleHeading shown above this section's rows.
event_payload.data.message.content.interactive_data.data.list_picker.sections.orderWhere this section sits relative to its siblings, ascending. Sections omitting it are laid out in list order, after any that specify one.
event_payload.data.message.content.interactive_data.data.list_picker.sections.itemsThe rows in this section.
Show child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.identifierOpaque item identifier returned in interactive_data.data.list_picker.sections.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.titleLabel shown on the row.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.subtitleSecondary line shown under the title.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.image_identifierIdentifier of an image in interactive_data.data.images, shown next to this row. A key with no matching entry in images is refused with a 422 AMBInteractiveImageInvalid.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.orderPosition within the section, ascending. Defaults to the row's array position.
event_payload.data.message.content.interactive_data.data.list_picker.sections.multiple_selectionWhether the customer can select more than one row in this section.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.eventShow child attributes
event_payload.data.message.content.interactive_data.data.event.identifierYour identifier for the event. Defaults to the message identifier.
event_payload.data.message.content.interactive_data.data.event.locationOptional appointment location.
Show child attributes
event_payload.data.message.content.interactive_data.data.event.location.titleName shown for the appointment location.
event_payload.data.message.content.interactive_data.data.event.location.latitudeLatitude in degrees. Set together with longitude.
event_payload.data.message.content.interactive_data.data.event.location.longitudeLongitude in degrees. Set together with latitude.
event_payload.data.message.content.interactive_data.data.event.location.radiusLocation radius in meters. Apple ignores it without coordinates.
event_payload.data.message.content.interactive_data.data.event.timezone_offsetMinutes from GMT at the event location. Omit to use the customer's time zone.
event_payload.data.message.content.interactive_data.data.event.timeslotsAppointment times with RFC 3339 timestamps and duration in seconds.
Show child attributes
event_payload.data.message.content.interactive_data.data.event.timeslots.identifierOpaque slot identifier. Apple may instead return only a localized label in interactive_data.reply_message.title.
event_payload.data.message.content.interactive_data.data.event.timeslots.start_atWhen this slot begins. Seconds and fractional seconds must be zero, for example 2026-09-02T14:30:00Z; otherwise sending returns 422 with error code E01001. The timestamp is converted to UTC for Apple while preserving the instant.
event_payload.data.message.content.interactive_data.data.event.timeslots.duration_secondsDuration in seconds. Zero indicates no duration.
event_payload.data.message.content.interactive_data.data.event.image_identifierIdentifier of the event image in interactive_data.data.images.
event_payload.data.message.content.interactive_data.data.event.titleEvent title.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.dynamicForm content. Bird supplies Apple’s messageForms template and protocol version.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.dataShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.start_page_identifierIdentifier of the first page to show.
event_payload.data.message.content.interactive_data.data.dynamic.data.privateWhether Apple marks the submitted response as private.
event_payload.data.message.content.interactive_data.data.dynamic.data.show_summaryWhether Apple shows a summary before the customer submits.
event_payload.data.message.content.interactive_data.data.dynamic.data.splashShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.splash.headerevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.splash_textevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.button_titleevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.image_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pagesForm pages referenced by the start page and navigation identifiers.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: select
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.multiple_selectionevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.itemsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.valueevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.image_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.next_page_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: picker
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.picker_titleText beside the picker field. Omit to center the field without a label.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.selected_item_indexZero-based index into items. Defaults to 0. Must be less than the number of items; otherwise sending returns 422 AMBFormPagesInvalid.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.itemsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.valueevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: date_picker
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.hint_textevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.optionsApple defaults to UTC when interpreting these dates.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.date_formatFormat used to read the date values in these options. Defaults to MM/dd/yyyy.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.start_dateDate initially shown by the picker, written in date_format. Defaults to the current date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.maximum_dateLatest date the picker shows, written in date_format. Defaults to the current date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.minimum_dateEarliest date the picker shows, written in date_format.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.label_textLabel beside the date field. Defaults to Date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: input
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.hint_textevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.optionsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.regexPattern Apple uses to validate the input. Use JSON string escaping for backslashes.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.placeholderShown when the field is empty. Defaults to Required when required is true, otherwise Optional.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.requiredDisables the next-page button until the customer enters a value.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.input_typeDefaults to singleline.
Possible values: singleline, multiline
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.label_textLabel for singleline input only. Omit for no label.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.prefix_textText beside singleline input only, such as a currency symbol. Omit for no prefix.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.maximum_character_countDefaults to 30 for singleline input and 300 for multiline input.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.keyboard_typeKeyboard to display. Defaults to default.
Possible values (may grow over time): default, asciiCapable, numbersAndPunctuation, URL, numberPad, phonePad, namePhonePad, emailAddress, decimalPad, webSearch
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.text_content_typeContent hint used for autofill.
Possible values (may grow over time): name, namePrefix, givenName, middleName, familyName, nameSuffix, nickname, jobTitle, organizationName, location, fullStreetAddress, streetAddressLine1, streetAddressLine2, addressCity, addressState, addressCityAndState, sublocality, countryName, postalCode, telephoneNumber, emailAddress, URL, creditCardNumber, username, password, newPassword, oneTimeCode
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.authenticateAuthentication attempt created through the conversation authentication endpoint. Contains no authorization parameters or credentials.
Show child attributes
event_payload.data.message.content.interactive_data.data.authenticate.authentication_idevent_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.paymentApple Pay request created through the conversation payment endpoint. Contains no payment token or provider credentials.
Show child attributes
event_payload.data.message.content.interactive_data.data.payment.payment_idevent_payload.data.message.content.interactive_data.app_idApp Store identifier of the iMessage app.
event_payload.data.message.content.interactive_data.app_nameName of the iMessage app.
event_payload.data.message.content.interactive_data.bidIdentifier of the iMessage extension, in Apple's com.apple.messages.MSMessageExtensionBalloonPlugin:team-id:extension-id format.
event_payload.data.message.content.interactive_data.urlOpaque URL string that Messages passes to the iMessage app.
event_payload.data.message.content.interactive_data.use_live_layoutWhether Messages renders the received and reply bubbles using Live Layout.
event_payload.data.message.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.received_messageContent Messages shows in the received message bubble.
Show child attributes
event_payload.data.message.content.interactive_data.received_message.titleText shown on the message bubble.
event_payload.data.message.content.interactive_data.received_message.subtitleSecondary text shown below the title.
event_payload.data.message.content.interactive_data.received_message.styleBubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
event_payload.data.message.content.interactive_data.received_message.image_identifierIdentifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
event_payload.data.message.content.interactive_data.received_message.image_titleTitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.image_subtitleSubtitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.secondary_subtitleRight-aligned title in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.tertiary_subtitleRight-aligned subtitle in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_messageContent Messages shows in the reply message bubble.
Show child attributes
event_payload.data.message.content.interactive_data.reply_message.titleText shown on the message bubble.
event_payload.data.message.content.interactive_data.reply_message.subtitleSecondary text shown below the title.
event_payload.data.message.content.interactive_data.reply_message.styleBubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
event_payload.data.message.content.interactive_data.reply_message.image_identifierIdentifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
event_payload.data.message.content.interactive_data.reply_message.image_titleTitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.image_subtitleSubtitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.secondary_subtitleRight-aligned title in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.tertiary_subtitleRight-aligned subtitle in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.app_icon_source_urlPublicly accessible HTTPS URL of the app's PNG icon. The icon must be smaller than 15 kB. We fetch and include it in the request to Apple.
event_payload.data.message.content.interactive_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Show child attributes
event_payload.data.message.content.interactive_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.content.interactive_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.interactive_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.content.interactive_data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.content.interactive_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.in_reply_to_message_idOriginal message matched through Apple’s request identifier within the same workspace, business, and conversation. Omitted when no verified match exists.
event_payload.data.message.localeLocale for this message, preserved in Apple’s format, for example en_US. Outbound messages use the request override, then the conversation locale, then the business default. Inbound messages preserve the locale in Apple’s callback. Null when unknown.
event_payload.data.message.categoryThe category this message was sent with, for reporting only. It does not affect sending or suppression policy, or select an Apple department or purpose. Defaults to an empty string when a send names no category. Absent on an inbound message, which has no category to report.
event_payload.data.message.metadataArbitrary JSON object for per-message context. Maximum 2 KB serialized. Top-level keys beginning with __bird are reserved. Returned in the send response, message reads and customer message webhooks.
event_payload.data.message.tagsStructured {name, value} filter labels applied to this message. Absent on an inbound message.
Show child attributes
event_payload.data.message.tags.nameTag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
event_payload.data.message.tags.valueTag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
event_payload.data.message.costRecorded per-message charge before MAC pricing. Null in the initial send response, while unpriced, and for MAC-covered replies. MAC fees belong to monthly contact usage, not individual messages. Historical charges have no priced passthrough component.
Show child attributes
event_payload.data.message.cost.amountTotal 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.message.cost.currency_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.message.cost.transaction_amountWhat 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.message.cost.passthrough_amountThird-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.message.last_errorFailure detail on a message whose send failed or that Bird rejected before any send attempt. Omitted when there is no failure detail.
Show child attributes
event_payload.data.message.last_error.codeMachine-readable reason a send failed, in one of two namespaces: bird: for a reason Bird's own pipeline assigned (for example bird:business_not_registered), or apple: followed by the HTTP status Apple's API returned for the send attempt (for example apple:404). This is an open, growing set in both namespaces; accept unrecognized values.
event_payload.data.message.last_error.descriptionThe failure in words. Free-form, so branch on code and show this to a human.
event_payload.data.message.last_error.occurred_atWhen the failure occurred.
event_payload.data.message.created_atThe moment this message was accepted (outbound) or received (inbound). This is the timestamp the outbound statistics families bucket and attribute on; there is no separate accepted_at field.
event_payload.data.message.sent_atWhen the selected sending outcome occurred. Null unless the current status is sent and the message is outbound. For older messages without a retained sending event, the stored record time is used.
event_payload.data.message.data_refReusable encrypted content reference returned by Apple after a successful send. Absent until Apple returns one.
Show child attributes
event_payload.data.message.data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.data_ref.urlLocation of the encrypted preview.
event_payload.data.message.data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.data_ref.urlLocation of the encrypted preview.
event_payload.data.message.data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.groupApple department identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
event_payload.data.message.intentApple purpose identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
An accepted outbound message could not be handed to Apple. The message snapshot carries the failure detail.
event_payload.typeAlways amb.send_failed for this event.
Possible values: amb.send_failed
event_payload.timestampWhen this lifecycle event occurred, independent of webhook delivery time.
event_payload.dataThe workspace and message snapshot at the time of the lifecycle event.
Show child attributes
event_payload.data.workspace_idWorkspace that owns this message.
event_payload.data.messageMessage state when the event occurred. Later state changes do not alter this snapshot. Customer metadata is included when present; reserved Bird metadata is excluded.
Show child attributes
event_payload.data.message.idID of the message, assigned when it is accepted or received. Pass it as message_id to the get-message and list-events endpoints.
event_payload.data.message.conversation_idThe conversation this message belongs to.
event_payload.data.message.business_account_idThe business the message was sent from or received by.
event_payload.data.message.fromApple business identifier on outbound messages, or the customer's opaque Apple identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.toCustomer's opaque Apple identifier on outbound messages, or the Apple business identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.directionWhether a message was sent by the business or received from the customer:
outbound: A reply the business sent into the conversation.inbound: A message the customer sent.
Possible values: outbound, inbound
event_payload.data.message.statusSend status:
accepted: Accepted and queued for delivery to Apple.sent: Handed to Apple. There is no delivery or read receipt on this channel, sosentis the furthest an outbound message's status advances.send_failed: Sending stopped because of a business or conversation restriction, a recipient opt-out, an Apple refusal, or exhausted attempts. An earlier attempt may have reached Apple if its response or the local record of success was lost. Seelast_errorfor why sending stopped.rejected: Refused by Bird before any send attempt and never charged: the destination has no price, the wallet could not fund the send, or the content cannot be sent yet. Seelast_error.received: Received as an inbound message.
Possible values: accepted, sent, send_failed, rejected, received
event_payload.data.message.kindDerived content classification for filtering and statistics.
Possible values: text, attachment, rich_link, quick_reply, list_picker, time_picker, form, apple_pay, authenticate, imessage_app, interactive
event_payload.data.message.sourceWho sent this message. Absent on an inbound message, which has no source to report.
Possible values: operator, automation, api
event_payload.data.message.contentNative message content. Outgoing interactions contain requests; incoming interactions contain replies.
Show child attributes
event_payload.data.message.content.typeAlways text.
Value: text
event_payload.data.message.content.bodyText displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
event_payload.data.message.content.subjectSubject displayed above the message body.
event_payload.data.message.content.attachmentsOrdered attachments. Each object supplies a source URL or an encrypted Apple reference.
Show child attributes
event_payload.data.message.content.attachments.source_urlHTTPS URL Bird downloads and uploads to Apple.
event_payload.data.message.content.attachments.nameDisplay filename.
event_payload.data.message.content.attachments.mime_typeMedia type of the attachment.
event_payload.data.message.content.attachments.nameDisplay filename.
event_payload.data.message.content.attachments.mime_typeMedia type of the attachment.
event_payload.data.message.content.attachments.urlEncrypted attachment URL returned by Apple.
event_payload.data.message.content.attachments.ownerOpaque owner value returned by Apple.
event_payload.data.message.content.attachments.signature_base64Attachment authorization signature returned by Apple.
event_payload.data.message.content.attachments.keyAttachment decryption key returned by Apple.
event_payload.data.message.content.attachments.sizeAttachment size in bytes.
event_payload.data.message.content.rich_link_dataShow child attributes
event_payload.data.message.content.rich_link_data.urlHTTPS URL opened by the preview.
event_payload.data.message.content.rich_link_data.titlePreview title.
event_payload.data.message.content.rich_link_data.assetsShow child attributes
event_payload.data.message.content.rich_link_data.assets.imageShow child attributes
event_payload.data.message.content.rich_link_data.assets.image.source_urlHTTPS URL of a PNG preview image up to 200 kB. Bird fetches and encodes it when sending.
event_payload.data.message.content.rich_link_data.assets.image.mime_typePNG media type required by Apple. Defaults to image/png.
Value: image/png
event_payload.data.message.content.rich_link_data.assets.videoShow child attributes
event_payload.data.message.content.rich_link_data.assets.video.urlHTTPS video URL fetched by Apple.
event_payload.data.message.content.rich_link_data.assets.video.mime_typeMedia type of the video. Defaults to video/mp4; supply the actual type for other formats.
event_payload.data.message.content.rich_link_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Show child attributes
event_payload.data.message.content.rich_link_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.rich_link_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.content.rich_link_data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.interactive_dataA built-in interaction or custom iMessage app. Custom apps require the app metadata and both message bubbles.
Show child attributes
event_payload.data.message.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.dataExactly one built-in interaction. Protocol versions are managed by Bird.
Show child attributes
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.quick_replyShow child attributes
event_payload.data.message.content.interactive_data.data.quick_reply.summary_textText used for the device notification and shown in the transcript after the customer chooses an item. Send a separate text message to introduce the choices.
event_payload.data.message.content.interactive_data.data.quick_reply.itemsThe buttons offered to the customer. Apple requires between two and five; outside that range the request is refused with a 422 AMBQuickReplyItemsInvalid. For more choices, send list_picker content instead.
Show child attributes
event_payload.data.message.content.interactive_data.data.quick_reply.items.identifierOpaque choice identifier returned in interactive_data.data.quick_reply.selected_identifier.
event_payload.data.message.content.interactive_data.data.quick_reply.items.titleLabel shown on the button.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.list_pickerShow child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sectionsThe menu's sections, each with its own heading and rows.
Show child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sections.titleHeading shown above this section's rows.
event_payload.data.message.content.interactive_data.data.list_picker.sections.orderWhere this section sits relative to its siblings, ascending. Sections omitting it are laid out in list order, after any that specify one.
event_payload.data.message.content.interactive_data.data.list_picker.sections.itemsThe rows in this section.
Show child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.identifierOpaque item identifier returned in interactive_data.data.list_picker.sections.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.titleLabel shown on the row.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.subtitleSecondary line shown under the title.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.image_identifierIdentifier of an image in interactive_data.data.images, shown next to this row. A key with no matching entry in images is refused with a 422 AMBInteractiveImageInvalid.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.orderPosition within the section, ascending. Defaults to the row's array position.
event_payload.data.message.content.interactive_data.data.list_picker.sections.multiple_selectionWhether the customer can select more than one row in this section.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.eventShow child attributes
event_payload.data.message.content.interactive_data.data.event.identifierYour identifier for the event. Defaults to the message identifier.
event_payload.data.message.content.interactive_data.data.event.locationOptional appointment location.
Show child attributes
event_payload.data.message.content.interactive_data.data.event.location.titleName shown for the appointment location.
event_payload.data.message.content.interactive_data.data.event.location.latitudeLatitude in degrees. Set together with longitude.
event_payload.data.message.content.interactive_data.data.event.location.longitudeLongitude in degrees. Set together with latitude.
event_payload.data.message.content.interactive_data.data.event.location.radiusLocation radius in meters. Apple ignores it without coordinates.
event_payload.data.message.content.interactive_data.data.event.timezone_offsetMinutes from GMT at the event location. Omit to use the customer's time zone.
event_payload.data.message.content.interactive_data.data.event.timeslotsAppointment times with RFC 3339 timestamps and duration in seconds.
Show child attributes
event_payload.data.message.content.interactive_data.data.event.timeslots.identifierOpaque slot identifier. Apple may instead return only a localized label in interactive_data.reply_message.title.
event_payload.data.message.content.interactive_data.data.event.timeslots.start_atWhen this slot begins. Seconds and fractional seconds must be zero, for example 2026-09-02T14:30:00Z; otherwise sending returns 422 with error code E01001. The timestamp is converted to UTC for Apple while preserving the instant.
event_payload.data.message.content.interactive_data.data.event.timeslots.duration_secondsDuration in seconds. Zero indicates no duration.
event_payload.data.message.content.interactive_data.data.event.image_identifierIdentifier of the event image in interactive_data.data.images.
event_payload.data.message.content.interactive_data.data.event.titleEvent title.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.dynamicForm content. Bird supplies Apple’s messageForms template and protocol version.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.dataShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.start_page_identifierIdentifier of the first page to show.
event_payload.data.message.content.interactive_data.data.dynamic.data.privateWhether Apple marks the submitted response as private.
event_payload.data.message.content.interactive_data.data.dynamic.data.show_summaryWhether Apple shows a summary before the customer submits.
event_payload.data.message.content.interactive_data.data.dynamic.data.splashShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.splash.headerevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.splash_textevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.button_titleevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.image_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pagesForm pages referenced by the start page and navigation identifiers.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: select
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.multiple_selectionevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.itemsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.valueevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.image_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.next_page_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: picker
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.picker_titleText beside the picker field. Omit to center the field without a label.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.selected_item_indexZero-based index into items. Defaults to 0. Must be less than the number of items; otherwise sending returns 422 AMBFormPagesInvalid.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.itemsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.valueevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: date_picker
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.hint_textevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.optionsApple defaults to UTC when interpreting these dates.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.date_formatFormat used to read the date values in these options. Defaults to MM/dd/yyyy.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.start_dateDate initially shown by the picker, written in date_format. Defaults to the current date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.maximum_dateLatest date the picker shows, written in date_format. Defaults to the current date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.minimum_dateEarliest date the picker shows, written in date_format.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.label_textLabel beside the date field. Defaults to Date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: input
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.hint_textevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.optionsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.regexPattern Apple uses to validate the input. Use JSON string escaping for backslashes.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.placeholderShown when the field is empty. Defaults to Required when required is true, otherwise Optional.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.requiredDisables the next-page button until the customer enters a value.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.input_typeDefaults to singleline.
Possible values: singleline, multiline
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.label_textLabel for singleline input only. Omit for no label.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.prefix_textText beside singleline input only, such as a currency symbol. Omit for no prefix.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.maximum_character_countDefaults to 30 for singleline input and 300 for multiline input.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.keyboard_typeKeyboard to display. Defaults to default.
Possible values (may grow over time): default, asciiCapable, numbersAndPunctuation, URL, numberPad, phonePad, namePhonePad, emailAddress, decimalPad, webSearch
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.text_content_typeContent hint used for autofill.
Possible values (may grow over time): name, namePrefix, givenName, middleName, familyName, nameSuffix, nickname, jobTitle, organizationName, location, fullStreetAddress, streetAddressLine1, streetAddressLine2, addressCity, addressState, addressCityAndState, sublocality, countryName, postalCode, telephoneNumber, emailAddress, URL, creditCardNumber, username, password, newPassword, oneTimeCode
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.authenticateAuthentication attempt created through the conversation authentication endpoint. Contains no authorization parameters or credentials.
Show child attributes
event_payload.data.message.content.interactive_data.data.authenticate.authentication_idevent_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.paymentApple Pay request created through the conversation payment endpoint. Contains no payment token or provider credentials.
Show child attributes
event_payload.data.message.content.interactive_data.data.payment.payment_idevent_payload.data.message.content.interactive_data.app_idApp Store identifier of the iMessage app.
event_payload.data.message.content.interactive_data.app_nameName of the iMessage app.
event_payload.data.message.content.interactive_data.bidIdentifier of the iMessage extension, in Apple's com.apple.messages.MSMessageExtensionBalloonPlugin:team-id:extension-id format.
event_payload.data.message.content.interactive_data.urlOpaque URL string that Messages passes to the iMessage app.
event_payload.data.message.content.interactive_data.use_live_layoutWhether Messages renders the received and reply bubbles using Live Layout.
event_payload.data.message.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.received_messageContent Messages shows in the received message bubble.
Show child attributes
event_payload.data.message.content.interactive_data.received_message.titleText shown on the message bubble.
event_payload.data.message.content.interactive_data.received_message.subtitleSecondary text shown below the title.
event_payload.data.message.content.interactive_data.received_message.styleBubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
event_payload.data.message.content.interactive_data.received_message.image_identifierIdentifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
event_payload.data.message.content.interactive_data.received_message.image_titleTitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.image_subtitleSubtitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.secondary_subtitleRight-aligned title in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.tertiary_subtitleRight-aligned subtitle in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_messageContent Messages shows in the reply message bubble.
Show child attributes
event_payload.data.message.content.interactive_data.reply_message.titleText shown on the message bubble.
event_payload.data.message.content.interactive_data.reply_message.subtitleSecondary text shown below the title.
event_payload.data.message.content.interactive_data.reply_message.styleBubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
event_payload.data.message.content.interactive_data.reply_message.image_identifierIdentifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
event_payload.data.message.content.interactive_data.reply_message.image_titleTitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.image_subtitleSubtitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.secondary_subtitleRight-aligned title in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.tertiary_subtitleRight-aligned subtitle in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.app_icon_source_urlPublicly accessible HTTPS URL of the app's PNG icon. The icon must be smaller than 15 kB. We fetch and include it in the request to Apple.
event_payload.data.message.content.interactive_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Show child attributes
event_payload.data.message.content.interactive_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.content.interactive_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.interactive_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.content.interactive_data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.content.interactive_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.in_reply_to_message_idOriginal message matched through Apple’s request identifier within the same workspace, business, and conversation. Omitted when no verified match exists.
event_payload.data.message.localeLocale for this message, preserved in Apple’s format, for example en_US. Outbound messages use the request override, then the conversation locale, then the business default. Inbound messages preserve the locale in Apple’s callback. Null when unknown.
event_payload.data.message.categoryThe category this message was sent with, for reporting only. It does not affect sending or suppression policy, or select an Apple department or purpose. Defaults to an empty string when a send names no category. Absent on an inbound message, which has no category to report.
event_payload.data.message.metadataArbitrary JSON object for per-message context. Maximum 2 KB serialized. Top-level keys beginning with __bird are reserved. Returned in the send response, message reads and customer message webhooks.
event_payload.data.message.tagsStructured {name, value} filter labels applied to this message. Absent on an inbound message.
Show child attributes
event_payload.data.message.tags.nameTag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
event_payload.data.message.tags.valueTag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
event_payload.data.message.costRecorded per-message charge before MAC pricing. Null in the initial send response, while unpriced, and for MAC-covered replies. MAC fees belong to monthly contact usage, not individual messages. Historical charges have no priced passthrough component.
Show child attributes
event_payload.data.message.cost.amountTotal 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.message.cost.currency_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.message.cost.transaction_amountWhat 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.message.cost.passthrough_amountThird-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.message.last_errorFailure detail on a message whose send failed or that Bird rejected before any send attempt. Omitted when there is no failure detail.
Show child attributes
event_payload.data.message.last_error.codeMachine-readable reason a send failed, in one of two namespaces: bird: for a reason Bird's own pipeline assigned (for example bird:business_not_registered), or apple: followed by the HTTP status Apple's API returned for the send attempt (for example apple:404). This is an open, growing set in both namespaces; accept unrecognized values.
event_payload.data.message.last_error.descriptionThe failure in words. Free-form, so branch on code and show this to a human.
event_payload.data.message.last_error.occurred_atWhen the failure occurred.
event_payload.data.message.created_atThe moment this message was accepted (outbound) or received (inbound). This is the timestamp the outbound statistics families bucket and attribute on; there is no separate accepted_at field.
event_payload.data.message.sent_atWhen the selected sending outcome occurred. Null unless the current status is sent and the message is outbound. For older messages without a retained sending event, the stored record time is used.
event_payload.data.message.data_refReusable encrypted content reference returned by Apple after a successful send. Absent until Apple returns one.
Show child attributes
event_payload.data.message.data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.data_ref.urlLocation of the encrypted preview.
event_payload.data.message.data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.data_ref.urlLocation of the encrypted preview.
event_payload.data.message.data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.groupApple department identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
event_payload.data.message.intentApple purpose identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
Apple accepted an outbound message from Bird. This does not establish delivery to the customer or a read receipt.
event_payload.typeAlways amb.sent for this event.
Possible values: amb.sent
event_payload.timestampWhen this lifecycle event occurred, independent of webhook delivery time.
event_payload.dataThe workspace and message snapshot at the time of the lifecycle event.
Show child attributes
event_payload.data.workspace_idWorkspace that owns this message.
event_payload.data.messageMessage state when the event occurred. Later state changes do not alter this snapshot. Customer metadata is included when present; reserved Bird metadata is excluded.
Show child attributes
event_payload.data.message.idID of the message, assigned when it is accepted or received. Pass it as message_id to the get-message and list-events endpoints.
event_payload.data.message.conversation_idThe conversation this message belongs to.
event_payload.data.message.business_account_idThe business the message was sent from or received by.
event_payload.data.message.fromApple business identifier on outbound messages, or the customer's opaque Apple identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.toCustomer's opaque Apple identifier on outbound messages, or the Apple business identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.directionWhether a message was sent by the business or received from the customer:
outbound: A reply the business sent into the conversation.inbound: A message the customer sent.
Possible values: outbound, inbound
event_payload.data.message.statusSend status:
accepted: Accepted and queued for delivery to Apple.sent: Handed to Apple. There is no delivery or read receipt on this channel, sosentis the furthest an outbound message's status advances.send_failed: Sending stopped because of a business or conversation restriction, a recipient opt-out, an Apple refusal, or exhausted attempts. An earlier attempt may have reached Apple if its response or the local record of success was lost. Seelast_errorfor why sending stopped.rejected: Refused by Bird before any send attempt and never charged: the destination has no price, the wallet could not fund the send, or the content cannot be sent yet. Seelast_error.received: Received as an inbound message.
Possible values: accepted, sent, send_failed, rejected, received
event_payload.data.message.kindDerived content classification for filtering and statistics.
Possible values: text, attachment, rich_link, quick_reply, list_picker, time_picker, form, apple_pay, authenticate, imessage_app, interactive
event_payload.data.message.sourceWho sent this message. Absent on an inbound message, which has no source to report.
Possible values: operator, automation, api
event_payload.data.message.contentNative message content. Outgoing interactions contain requests; incoming interactions contain replies.
Show child attributes
event_payload.data.message.content.typeAlways text.
Value: text
event_payload.data.message.content.bodyText displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
event_payload.data.message.content.subjectSubject displayed above the message body.
event_payload.data.message.content.attachmentsOrdered attachments. Each object supplies a source URL or an encrypted Apple reference.
Show child attributes
event_payload.data.message.content.attachments.source_urlHTTPS URL Bird downloads and uploads to Apple.
event_payload.data.message.content.attachments.nameDisplay filename.
event_payload.data.message.content.attachments.mime_typeMedia type of the attachment.
event_payload.data.message.content.attachments.nameDisplay filename.
event_payload.data.message.content.attachments.mime_typeMedia type of the attachment.
event_payload.data.message.content.attachments.urlEncrypted attachment URL returned by Apple.
event_payload.data.message.content.attachments.ownerOpaque owner value returned by Apple.
event_payload.data.message.content.attachments.signature_base64Attachment authorization signature returned by Apple.
event_payload.data.message.content.attachments.keyAttachment decryption key returned by Apple.
event_payload.data.message.content.attachments.sizeAttachment size in bytes.
event_payload.data.message.content.rich_link_dataShow child attributes
event_payload.data.message.content.rich_link_data.urlHTTPS URL opened by the preview.
event_payload.data.message.content.rich_link_data.titlePreview title.
event_payload.data.message.content.rich_link_data.assetsShow child attributes
event_payload.data.message.content.rich_link_data.assets.imageShow child attributes
event_payload.data.message.content.rich_link_data.assets.image.source_urlHTTPS URL of a PNG preview image up to 200 kB. Bird fetches and encodes it when sending.
event_payload.data.message.content.rich_link_data.assets.image.mime_typePNG media type required by Apple. Defaults to image/png.
Value: image/png
event_payload.data.message.content.rich_link_data.assets.videoShow child attributes
event_payload.data.message.content.rich_link_data.assets.video.urlHTTPS video URL fetched by Apple.
event_payload.data.message.content.rich_link_data.assets.video.mime_typeMedia type of the video. Defaults to video/mp4; supply the actual type for other formats.
event_payload.data.message.content.rich_link_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Show child attributes
event_payload.data.message.content.rich_link_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.rich_link_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.content.rich_link_data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.interactive_dataA built-in interaction or custom iMessage app. Custom apps require the app metadata and both message bubbles.
Show child attributes
event_payload.data.message.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.dataExactly one built-in interaction. Protocol versions are managed by Bird.
Show child attributes
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.quick_replyShow child attributes
event_payload.data.message.content.interactive_data.data.quick_reply.summary_textText used for the device notification and shown in the transcript after the customer chooses an item. Send a separate text message to introduce the choices.
event_payload.data.message.content.interactive_data.data.quick_reply.itemsThe buttons offered to the customer. Apple requires between two and five; outside that range the request is refused with a 422 AMBQuickReplyItemsInvalid. For more choices, send list_picker content instead.
Show child attributes
event_payload.data.message.content.interactive_data.data.quick_reply.items.identifierOpaque choice identifier returned in interactive_data.data.quick_reply.selected_identifier.
event_payload.data.message.content.interactive_data.data.quick_reply.items.titleLabel shown on the button.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.list_pickerShow child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sectionsThe menu's sections, each with its own heading and rows.
Show child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sections.titleHeading shown above this section's rows.
event_payload.data.message.content.interactive_data.data.list_picker.sections.orderWhere this section sits relative to its siblings, ascending. Sections omitting it are laid out in list order, after any that specify one.
event_payload.data.message.content.interactive_data.data.list_picker.sections.itemsThe rows in this section.
Show child attributes
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.identifierOpaque item identifier returned in interactive_data.data.list_picker.sections.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.titleLabel shown on the row.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.subtitleSecondary line shown under the title.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.image_identifierIdentifier of an image in interactive_data.data.images, shown next to this row. A key with no matching entry in images is refused with a 422 AMBInteractiveImageInvalid.
event_payload.data.message.content.interactive_data.data.list_picker.sections.items.orderPosition within the section, ascending. Defaults to the row's array position.
event_payload.data.message.content.interactive_data.data.list_picker.sections.multiple_selectionWhether the customer can select more than one row in this section.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.eventShow child attributes
event_payload.data.message.content.interactive_data.data.event.identifierYour identifier for the event. Defaults to the message identifier.
event_payload.data.message.content.interactive_data.data.event.locationOptional appointment location.
Show child attributes
event_payload.data.message.content.interactive_data.data.event.location.titleName shown for the appointment location.
event_payload.data.message.content.interactive_data.data.event.location.latitudeLatitude in degrees. Set together with longitude.
event_payload.data.message.content.interactive_data.data.event.location.longitudeLongitude in degrees. Set together with latitude.
event_payload.data.message.content.interactive_data.data.event.location.radiusLocation radius in meters. Apple ignores it without coordinates.
event_payload.data.message.content.interactive_data.data.event.timezone_offsetMinutes from GMT at the event location. Omit to use the customer's time zone.
event_payload.data.message.content.interactive_data.data.event.timeslotsAppointment times with RFC 3339 timestamps and duration in seconds.
Show child attributes
event_payload.data.message.content.interactive_data.data.event.timeslots.identifierOpaque slot identifier. Apple may instead return only a localized label in interactive_data.reply_message.title.
event_payload.data.message.content.interactive_data.data.event.timeslots.start_atWhen this slot begins. Seconds and fractional seconds must be zero, for example 2026-09-02T14:30:00Z; otherwise sending returns 422 with error code E01001. The timestamp is converted to UTC for Apple while preserving the instant.
event_payload.data.message.content.interactive_data.data.event.timeslots.duration_secondsDuration in seconds. Zero indicates no duration.
event_payload.data.message.content.interactive_data.data.event.image_identifierIdentifier of the event image in interactive_data.data.images.
event_payload.data.message.content.interactive_data.data.event.titleEvent title.
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.dynamicForm content. Bird supplies Apple’s messageForms template and protocol version.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.dataShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.start_page_identifierIdentifier of the first page to show.
event_payload.data.message.content.interactive_data.data.dynamic.data.privateWhether Apple marks the submitted response as private.
event_payload.data.message.content.interactive_data.data.dynamic.data.show_summaryWhether Apple shows a summary before the customer submits.
event_payload.data.message.content.interactive_data.data.dynamic.data.splashShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.splash.headerevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.splash_textevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.button_titleevent_payload.data.message.content.interactive_data.data.dynamic.data.splash.image_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pagesForm pages referenced by the start page and navigation identifiers.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: select
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.multiple_selectionevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.itemsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.valueevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.image_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.next_page_identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: picker
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.picker_titleText beside the picker field. Omit to center the field without a label.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.selected_item_indexZero-based index into items. Defaults to 0. Must be less than the number of items; otherwise sending returns 422 AMBFormPagesInvalid.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.itemsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.identifierevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.items.valueevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: date_picker
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.hint_textevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.optionsApple defaults to UTC when interpreting these dates.
Show child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.date_formatFormat used to read the date values in these options. Defaults to MM/dd/yyyy.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.start_dateDate initially shown by the picker, written in date_format. Defaults to the current date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.maximum_dateLatest date the picker shows, written in date_format. Defaults to the current date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.minimum_dateEarliest date the picker shows, written in date_format.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.label_textLabel beside the date field. Defaults to Date.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.page_identifierUnique identifier for this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.typeValue: input
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.titleevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.subtitleQuestion shown on this page.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.next_page_identifierNext page to show. Omit to finish the form. Single-select pages route through their items instead.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.submit_formMarks this page as an end page for the form. A page with no next page also finishes the form.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.hint_textevent_payload.data.message.content.interactive_data.data.dynamic.data.pages.optionsShow child attributes
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.regexPattern Apple uses to validate the input. Use JSON string escaping for backslashes.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.placeholderShown when the field is empty. Defaults to Required when required is true, otherwise Optional.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.requiredDisables the next-page button until the customer enters a value.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.input_typeDefaults to singleline.
Possible values: singleline, multiline
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.label_textLabel for singleline input only. Omit for no label.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.prefix_textText beside singleline input only, such as a currency symbol. Omit for no prefix.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.maximum_character_countDefaults to 30 for singleline input and 300 for multiline input.
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.keyboard_typeKeyboard to display. Defaults to default.
Possible values (may grow over time): default, asciiCapable, numbersAndPunctuation, URL, numberPad, phonePad, namePhonePad, emailAddress, decimalPad, webSearch
event_payload.data.message.content.interactive_data.data.dynamic.data.pages.options.text_content_typeContent hint used for autofill.
Possible values (may grow over time): name, namePrefix, givenName, middleName, familyName, nameSuffix, nickname, jobTitle, organizationName, location, fullStreetAddress, streetAddressLine1, streetAddressLine2, addressCity, addressState, addressCityAndState, sublocality, countryName, postalCode, telephoneNumber, emailAddress, URL, creditCardNumber, username, password, newPassword, oneTimeCode
event_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.authenticateAuthentication attempt created through the conversation authentication endpoint. Contains no authorization parameters or credentials.
Show child attributes
event_payload.data.message.content.interactive_data.data.authenticate.authentication_idevent_payload.data.message.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.imagesImages referenced by identifier.
Show child attributes
event_payload.data.message.content.interactive_data.data.images.identifierIdentifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_urlHTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.descriptionAccessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.paymentApple Pay request created through the conversation payment endpoint. Contains no payment token or provider credentials.
Show child attributes
event_payload.data.message.content.interactive_data.data.payment.payment_idevent_payload.data.message.content.interactive_data.app_idApp Store identifier of the iMessage app.
event_payload.data.message.content.interactive_data.app_nameName of the iMessage app.
event_payload.data.message.content.interactive_data.bidIdentifier of the iMessage extension, in Apple's com.apple.messages.MSMessageExtensionBalloonPlugin:team-id:extension-id format.
event_payload.data.message.content.interactive_data.urlOpaque URL string that Messages passes to the iMessage app.
event_payload.data.message.content.interactive_data.use_live_layoutWhether Messages renders the received and reply bubbles using Live Layout.
event_payload.data.message.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.received_messageContent Messages shows in the received message bubble.
Show child attributes
event_payload.data.message.content.interactive_data.received_message.titleText shown on the message bubble.
event_payload.data.message.content.interactive_data.received_message.subtitleSecondary text shown below the title.
event_payload.data.message.content.interactive_data.received_message.styleBubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
event_payload.data.message.content.interactive_data.received_message.image_identifierIdentifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
event_payload.data.message.content.interactive_data.received_message.image_titleTitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.image_subtitleSubtitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.secondary_subtitleRight-aligned title in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.received_message.tertiary_subtitleRight-aligned subtitle in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_messageContent Messages shows in the reply message bubble.
Show child attributes
event_payload.data.message.content.interactive_data.reply_message.titleText shown on the message bubble.
event_payload.data.message.content.interactive_data.reply_message.subtitleSecondary text shown below the title.
event_payload.data.message.content.interactive_data.reply_message.styleBubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
event_payload.data.message.content.interactive_data.reply_message.image_identifierIdentifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
event_payload.data.message.content.interactive_data.reply_message.image_titleTitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.image_subtitleSubtitle shown over an attached image in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.secondary_subtitleRight-aligned title in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.reply_message.tertiary_subtitleRight-aligned subtitle in a custom iMessage app bubble.
event_payload.data.message.content.interactive_data.app_icon_source_urlPublicly accessible HTTPS URL of the app's PNG icon. The icon must be smaller than 15 kB. We fetch and include it in the request to Apple.
event_payload.data.message.content.interactive_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Show child attributes
event_payload.data.message.content.interactive_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.content.interactive_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.content.interactive_data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.content.interactive_data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.content.interactive_data_ref.urlLocation of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.in_reply_to_message_idOriginal message matched through Apple’s request identifier within the same workspace, business, and conversation. Omitted when no verified match exists.
event_payload.data.message.localeLocale for this message, preserved in Apple’s format, for example en_US. Outbound messages use the request override, then the conversation locale, then the business default. Inbound messages preserve the locale in Apple’s callback. Null when unknown.
event_payload.data.message.categoryThe category this message was sent with, for reporting only. It does not affect sending or suppression policy, or select an Apple department or purpose. Defaults to an empty string when a send names no category. Absent on an inbound message, which has no category to report.
event_payload.data.message.metadataArbitrary JSON object for per-message context. Maximum 2 KB serialized. Top-level keys beginning with __bird are reserved. Returned in the send response, message reads and customer message webhooks.
event_payload.data.message.tagsStructured {name, value} filter labels applied to this message. Absent on an inbound message.
Show child attributes
event_payload.data.message.tags.nameTag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
event_payload.data.message.tags.valueTag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
event_payload.data.message.costRecorded per-message charge before MAC pricing. Null in the initial send response, while unpriced, and for MAC-covered replies. MAC fees belong to monthly contact usage, not individual messages. Historical charges have no priced passthrough component.
Show child attributes
event_payload.data.message.cost.amountTotal 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.message.cost.currency_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.message.cost.transaction_amountWhat 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.message.cost.passthrough_amountThird-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.message.last_errorFailure detail on a message whose send failed or that Bird rejected before any send attempt. Omitted when there is no failure detail.
Show child attributes
event_payload.data.message.last_error.codeMachine-readable reason a send failed, in one of two namespaces: bird: for a reason Bird's own pipeline assigned (for example bird:business_not_registered), or apple: followed by the HTTP status Apple's API returned for the send attempt (for example apple:404). This is an open, growing set in both namespaces; accept unrecognized values.
event_payload.data.message.last_error.descriptionThe failure in words. Free-form, so branch on code and show this to a human.
event_payload.data.message.last_error.occurred_atWhen the failure occurred.
event_payload.data.message.created_atThe moment this message was accepted (outbound) or received (inbound). This is the timestamp the outbound statistics families bucket and attribute on; there is no separate accepted_at field.
event_payload.data.message.sent_atWhen the selected sending outcome occurred. Null unless the current status is sent and the message is outbound. For older messages without a retained sending event, the stored record time is used.
event_payload.data.message.data_refReusable encrypted content reference returned by Apple after a successful send. Absent until Apple returns one.
Show child attributes
event_payload.data.message.data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.data_ref.urlLocation of the encrypted preview.
event_payload.data.message.data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.data_ref.keyDecryption key supplied by Apple.
event_payload.data.message.data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.data_ref.titleTitle supplied by Apple for the preview.
event_payload.data.message.data_ref.bidMessages extension identifier supplied by Apple, when present.
event_payload.data.message.data_ref.data_ref_sigSignature binding the reference to the business, when supplied by Apple.
event_payload.data.message.data_ref.urlLocation of the encrypted preview.
event_payload.data.message.data_ref.ownerOwner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64Signature supplied by Apple.
event_payload.data.message.data_ref.sizeSize of the encrypted preview in bytes.
event_payload.data.message.groupApple department identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
event_payload.data.message.intentApple purpose identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
An address was added to the workspace's Apple Messages for Business suppression ledger.
event_payload.typeAlways amb_suppression.created for this event.
Possible values: amb_suppression.created
event_payload.timestampWhen the suppression episode took effect.
event_payload.dataPayload of the amb_suppression.created event.
Show child attributes
event_payload.data.suppression_idThe suppression episode that was opened.
event_payload.data.business_account_idThe business account this suppression covers, or null when it covers the workspace.
event_payload.data.addressThe canonical phone number or exact opaque Apple identifier that was suppressed.
event_payload.data.address_typeWhat kind of value address holds.
phone_numbermeansaddressis the customer's phone number. Apple's CloseSession event carries a phone number rather than an opaque identifier, so a suppression opened by a close on a conversation identified by phone number takes this kind.opaque_user_idmeansaddressis the opaque identifier Apple assigns to the customer's conversation with the business, stable across a close and a later re-initiation.
Possible values: phone_number, opaque_user_id
event_payload.data.reasonWhy the handle is suppressed. manual means it was added directly through this API or the dashboard. opted_out covers every case where Apple or the customer signaled they should not be contacted: a close, a permanent delivery failure, a declined invitation, or a stop keyword. This list grows over time, so treat an unknown value as informational rather than rejecting the record.
Possible values (may grow over time): manual, opted_out
event_payload.data.originWho created the episode. user and api_key identify manual blocks. close_session and gone are protected automatic conversation facts. Phone invitation opt-outs are recorded as preferences.
Possible values (may grow over time): user, api_key, close_session, gone
event_payload.data.workspace_idThe workspace the suppression belongs to.
A sending domain failed DNS verification.
event_payload.typeEvent type.
Possible values: domain.failed
event_payload.timestampWhen the event occurred.
event_payload.dataPayload of the domain.failed event.
Show child attributes
event_payload.data.domain_idThe sending domain resource whose verification failed.
event_payload.data.domainThe sending domain hostname.
event_payload.data.workspace_idThe workspace the domain is assigned to.
event_payload.data.failure_reasonWhy 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.typeEvent type.
Possible values: domain.verified
event_payload.timestampWhen the event occurred.
event_payload.dataPayload of the domain.verified event.
Show child attributes
event_payload.data.domain_idThe sending domain resource that verified.
event_payload.data.domainThe sending domain hostname.
event_payload.data.workspace_idThe 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.typeEvent type.
Possible values: email.accepted
event_payload.timestampTime the API accepted the send.
event_payload.dataPayload of the email.accepted event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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.typeEvent type.
Possible values: email.bounced
event_payload.timestampTime the bounce was recorded.
event_payload.dataPayload of the email.bounced event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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_typeBounce 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_classNumeric 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_codeSMTP reply code returned by the receiving mail server, or null when none was provided.
event_payload.data.bounce_descriptionHuman-readable reason the receiving mail server gave for the bounce, or null when none was provided.
event_payload.data.sending_ipThe 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.typeEvent type.
Possible values: email.canceled
event_payload.timestampTime the scheduled send was canceled.
event_payload.dataPayload of the email.canceled event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.tagsTags 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.metadataThe 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.typeEvent type.
Possible values: email.clicked
event_payload.timestampTime the click was recorded.
event_payload.dataPayload of the email.clicked event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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.urlThe URL the recipient clicked.
event_payload.data.ip_addressIP address of the client that clicked the link, or null when it is not known.
event_payload.data.user_agentUser-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.typeEvent type.
Possible values: email.complained
event_payload.timestampTime the complaint was recorded.
event_payload.dataPayload of the email.complained event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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_typeThe 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.typeEvent type.
Possible values: email.deferred
event_payload.timestampTime the deferral was recorded.
event_payload.dataPayload of the email.deferred event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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_typeBounce 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_classNumeric 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_reasonHuman-readable reason the receiving mail server gave for the deferral, or null when none was provided.
event_payload.data.sending_ipThe 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.typeEvent type.
Possible values: email.delivered
event_payload.timestampTime the recipient's mail server accepted the message.
event_payload.dataPayload of the email.delivered event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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.typeEvent type.
Possible values: email.list_unsubscribed
event_payload.timestampTime the unsubscribe was recorded.
event_payload.dataPayload of the email.list_unsubscribed event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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.typeEvent type.
Possible values: email.opened
event_payload.timestampTime the open was recorded.
event_payload.dataPayload of the email.opened event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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_addressIP address of the client that opened the email, or null when it is not known.
event_payload.data.user_agentUser-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.typeEvent type.
Possible values: email.out_of_band_bounce
event_payload.timestampTime the bounce notification was recorded.
event_payload.dataPayload of the email.out_of_band_bounce event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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_typeBounce 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_classNumeric bounce classification for fine-grained deliverability triage, or null when the receiving server's response could not be classified.
event_payload.data.bounce_codeSMTP reply code returned by the receiving mail server, or null when none was provided.
event_payload.data.bounce_descriptionHuman-readable reason the receiving mail server gave for the bounce, or null when none was provided.
event_payload.data.sending_ipThe 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.typeEvent type.
Possible values: email.processed
event_payload.timestampTime the message was prepared for delivery.
event_payload.dataPayload of the email.processed event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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.typeEvent type.
Possible values: email.received
event_payload.timestampWhen the API received the message.
event_payload.dataPayload of the email.received event.
Show child attributes
event_payload.data.inbound_message_idID 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_idID of the workspace that owns this event.
event_payload.data.message_idRFC 5322 Message-ID header from the sender, or null when the sender did not include one.
event_payload.data.fromAddress 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.toParsed recipient addresses from the message headers, not the envelope recipient used to route this delivery.
event_payload.data.subjectSubject line as received, or null when the message had no subject.
event_payload.data.in_reply_toIn-Reply-To header containing the Message-ID this message replies to, or null when it is not a reply.
event_payload.data.authenticationDMARC 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_passWhether 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_passWhether 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_passWhether 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_scoreContent 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.typeEvent type.
Possible values: email.rejected
event_payload.timestampTime the rejection was recorded.
event_payload.dataPayload of the email.rejected event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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_reasonWhy 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.typeEvent type.
Possible values: email.scheduled
event_payload.timestampTime the send was scheduled.
event_payload.dataPayload of the email.scheduled event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.tagsTags 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.metadataThe 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_atWhen the message is scheduled to send.
Recipient unsubscribed by clicking a tracked unsubscribe link in the email. Fires once per recipient.
event_payload.typeEvent type.
Possible values: email.unsubscribed
event_payload.timestampTime the unsubscribe was recorded.
event_payload.dataPayload of the email.unsubscribed event.
Show child attributes
event_payload.data.email_idID of the email send.
event_payload.data.recipient_idID of the recipient.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.recipientRecipient address as it appeared on the envelope.
event_payload.data.recipient_roleEnvelope position of the recipient.
Possible values: to, cc, bcc
event_payload.data.tagsTags 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.metadataThe 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_idThe 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.typeEvent type.
Possible values: email_mailbox.message_delivered
event_payload.timestampWhen the event occurred.
event_payload.dataPayload of the email_mailbox.message_delivered event.
Show child attributes
event_payload.data.message_idID 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_idID of the mailbox the message was sent from.
event_payload.data.thread_idID 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.typeEvent type.
Possible values: email_mailbox.message_failed
event_payload.timestampWhen the event occurred.
event_payload.dataPayload of the email_mailbox.message_failed event.
Show child attributes
event_payload.data.message_idID 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_idID of the mailbox the message was sent from.
event_payload.data.thread_idID of the thread the message belongs to.
event_payload.data.reasonWhy 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.typeEvent type.
Possible values: email_mailbox.message_received
event_payload.timestampWhen the event occurred.
event_payload.dataIdentifiers, 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.
Show child attributes
event_payload.data.message_idID 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_idID of the mailbox that received the message.
event_payload.data.thread_idID of the thread the message was filed into.
event_payload.data.route_idID (ein_…) of the explicit inbound route that matched, or null when the message was delivered by the virtual exact-address route.
event_payload.data.fromEnvelope-from address.
event_payload.data.toRecipient addresses the message was sent to.
event_payload.data.subjectSubject line as received, or null when the message had no subject.
event_payload.data.extracted_textPlain-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_textTrue when extracted_text was truncated to the 64 KB cap. Fetch the full text through the thread-member endpoint.
event_payload.data.attachment_countNumber of attachments on the message. Attachment content remains available for the mailbox's retention tier.
event_payload.data.authenticationDMARC 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_passWhether 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_passWhether 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_passWhether 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.typeEvent type.
Possible values: email_mailbox.message_sent
event_payload.timestampWhen the event occurred.
event_payload.dataPayload of the email_mailbox.message_sent event.
Show child attributes
event_payload.data.message_idID 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_idID of the mailbox the message was sent from.
event_payload.data.thread_idID of the thread the message belongs to.
This mailbox-suspension event is reserved and is not currently emitted.
event_payload.typeEvent type.
Possible values: email_mailbox.suspended
event_payload.timestampWhen the event occurred.
event_payload.dataPayload of the email_mailbox.suspended event.
Show child attributes
event_payload.data.mailbox_idID of the suspended mailbox.
event_payload.data.reasonWhy the mailbox was suspended.
A new thread was created in a mailbox, from either direction.
event_payload.typeEvent type.
Possible values: email_mailbox.thread_created
event_payload.timestampWhen the event occurred.
event_payload.dataPayload of the email_mailbox.thread_created event.
Show child attributes
event_payload.data.thread_idID of the thread.
event_payload.data.mailbox_idID of the mailbox the thread was created in.
event_payload.data.subjectSubject of the first message in the thread, or null when it had none.
event_payload.data.initiated_byWhich 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.typeEvent type.
Possible values: email_suppression.created
event_payload.timestampWhen the event occurred.
event_payload.dataPayload of the email_suppression.created event.
Show child attributes
event_payload.data.suppression_idThe suppression entry that was created.
event_payload.data.emailThe recipient address that was added to the suppression list.
event_payload.data.reasonWhy 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_idThe workspace the suppression belongs to.
A stated preference was deleted, superseding it in the ledger without erasing its history.
event_payload.typeAlways preference.deleted for this event.
Possible values: preference.deleted
event_payload.timestampWhen the delete took effect (effective_at), not when it was recorded.
event_payload.dataPayload of the preference.deleted event.
Show child attributes
event_payload.data.preference_idThe preference key this write applied to.
event_payload.data.transition_idThe ledger entry this write appended.
event_payload.data.channelevent_payload.data.handleWho the statement is about: an email address on the email channel, a phone number in E.164 format on SMS, WhatsApp, and Apple Messages for Business.
event_payload.data.sender_scopeThe sender the statement is limited to, or null when it covers the whole channel. On Apple Messages for Business, this is the Apple business ID used to send invitations. 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_idThe 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.coverageevent_payload.data.contact_idThe 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.typeAlways preference.granted for this event.
Possible values: preference.granted
event_payload.timestampWhen the statement took effect (effective_at), not when it was recorded.
event_payload.dataPayload of the preference.granted event.
Show child attributes
event_payload.data.preference_idThe preference key this write applied to.
event_payload.data.transition_idThe ledger entry this write appended.
event_payload.data.channelevent_payload.data.handleWho the statement is about: an email address on the email channel, a phone number in E.164 format on SMS, WhatsApp, and Apple Messages for Business.
event_payload.data.sender_scopeThe sender the statement is limited to, or null when it covers the whole channel. On Apple Messages for Business, this is the Apple business ID used to send invitations. 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_idThe 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.coverageevent_payload.data.contact_idThe 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.typeAlways preference.revoked for this event.
Possible values: preference.revoked
event_payload.timestampWhen the statement took effect (effective_at), not when it was recorded.
event_payload.dataPayload of the preference.revoked event.
Show child attributes
event_payload.data.preference_idThe preference key this write applied to.
event_payload.data.transition_idThe ledger entry this write appended.
event_payload.data.channelevent_payload.data.handleWho the statement is about: an email address on the email channel, a phone number in E.164 format on SMS, WhatsApp, and Apple Messages for Business.
event_payload.data.sender_scopeThe sender the statement is limited to, or null when it covers the whole channel. On Apple Messages for Business, this is the Apple business ID used to send invitations. 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_idThe 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.coverageevent_payload.data.contact_idThe 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.typeEvent type.
Possible values: sms.accepted
event_payload.timestampTime the API accepted the request.
event_payload.dataPayload of the sms.accepted event.
Show child attributes
event_payload.data.sms_idID of the SMS message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toWhere 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.fromWhere 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.tagsTags 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.metadataThe 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_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_languageThe template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_idThe template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_idThe 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_hashThe rendered language's source fingerprint, or null for a free-text message.
event_payload.data.costMessage 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.
Show child attributes
event_payload.data.cost.amountTotal 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_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amountWhat 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_amountThird-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.segmentsSegment breakdown used to calculate the message charge.
Show child attributes
event_payload.data.segments.countNumber of segments the body is split into. Each segment is a billable unit.
event_payload.data.segments.encodingEncoding 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.charactersCharacter 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.typeEvent type.
Possible values: sms.delivered
event_payload.timestampTime the carrier confirmed delivery.
event_payload.dataPayload of the sms.delivered event.
Show child attributes
event_payload.data.sms_idID of the SMS message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toWhere 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.fromWhere 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.tagsTags 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.metadataThe 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_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_languageThe template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_idThe template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_idThe 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_hashThe rendered language's source fingerprint, or null for a free-text message.
event_payload.data.costMessage 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.
Show child attributes
event_payload.data.cost.amountTotal 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_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amountWhat 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_amountThird-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.carrierCarrier that delivered the message. Absent when the carrier does not report one.
event_payload.data.mcc_mncMobile 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.typeEvent type.
Possible values: sms.expired
event_payload.timestampTime the message expired.
event_payload.dataPayload of the sms.expired event.
Show child attributes
event_payload.data.sms_idID of the SMS message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toWhere 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.fromWhere 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.tagsTags 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.metadataThe 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_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_languageThe template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_idThe template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_idThe 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_hashThe rendered language's source fingerprint, or null for a free-text message.
event_payload.data.costMessage 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.
Show child attributes
event_payload.data.cost.amountTotal 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_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amountWhat 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_amountThird-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.errorWhy 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.
Show child attributes
event_payload.data.error.codeStandardized 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_fraud_protection: Bird fraud protection blocked suspected SMS pumping.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_fraud_protection, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, insufficient_balance, unknown
event_payload.data.error.descriptionThe failure in words: the provider's reason text, or Bird's explanation for a fraud protection block or a message refused before submission. Free-form, so branch on code and show this to a human.
event_payload.data.error.carrier_error_codeRaw 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_atWhen the failure occurred.
Message delivery failed permanently.
event_payload.typeEvent type.
Possible values: sms.failed
event_payload.timestampTime the failure was recorded.
event_payload.dataPayload of the sms.failed event.
Show child attributes
event_payload.data.sms_idID of the SMS message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toWhere 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.fromWhere 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.tagsTags 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.metadataThe 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_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_languageThe template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_idThe template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_idThe 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_hashThe rendered language's source fingerprint, or null for a free-text message.
event_payload.data.costMessage 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.
Show child attributes
event_payload.data.cost.amountTotal 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_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amountWhat 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_amountThird-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.errorWhy the message terminally failed.
Show child attributes
event_payload.data.error.codeStandardized 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_fraud_protection: Bird fraud protection blocked suspected SMS pumping.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_fraud_protection, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, insufficient_balance, unknown
event_payload.data.error.descriptionThe failure in words: the provider's reason text, or Bird's explanation for a fraud protection block or a message refused before submission. Free-form, so branch on code and show this to a human.
event_payload.data.error.carrier_error_codeRaw 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_atWhen the failure occurred.
A message was received on one of your numbers.
event_payload.typeAlways sms.received for this event.
Possible values: sms.received
event_payload.timestampTime the sender sent the message.
event_payload.dataPayload of the sms.received event.
Show child attributes
event_payload.data.sms_idID of the SMS message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toWhere 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.fromWhere 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.tagsTags 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.metadataThe 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_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_languageThe template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_idThe template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_idThe 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_hashThe rendered language's source fingerprint, or null for a free-text message.
event_payload.data.costMessage 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.
Show child attributes
event_payload.data.cost.amountTotal 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_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amountWhat 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_amountThird-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.textThe 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.segmentsSegment breakdown of the received body.
Show child attributes
event_payload.data.segments.countNumber of segments the body is split into. Each segment is a billable unit.
event_payload.data.segments.encodingEncoding 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.charactersCharacter 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.carrierCarrier the message came in over. Absent where the carrier does not report one.
event_payload.data.mcc_mncMobile country code and mobile network code of the carrier. Absent when not known.
event_payload.data.subjectSubject line. Absent when the message carried none.
event_payload.data.sms_idID of the SMS message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toWhere 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.fromWhere 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.tagsTags 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.metadataThe 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_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_languageThe template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_idThe template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_idThe 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_hashThe rendered language's source fingerprint, or null for a free-text message.
event_payload.data.costMessage 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.
Show child attributes
event_payload.data.cost.amountTotal 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_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amountWhat 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_amountThird-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.segmentsSegment breakdown of the received body.
Show child attributes
event_payload.data.segments.countNumber of segments the body is split into. Each segment is a billable unit.
event_payload.data.segments.encodingEncoding 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.charactersCharacter 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.carrierCarrier the message came in over. Absent where the carrier does not report one.
event_payload.data.mcc_mncMobile country code and mobile network code of the carrier. Absent when not known.
event_payload.data.subjectSubject 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.typeEvent type.
Possible values: sms.rejected
event_payload.timestampTime the rejection was recorded.
event_payload.dataPayload of the sms.rejected event.
Show child attributes
event_payload.data.sms_idID of the SMS message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toWhere 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.fromWhere 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.tagsTags 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.metadataThe 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_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_languageThe template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_idThe template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_idThe 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_hashThe rendered language's source fingerprint, or null for a free-text message.
event_payload.data.costMessage 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.
Show child attributes
event_payload.data.cost.amountTotal 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_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amountWhat 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_amountThird-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.errorWhy the message was rejected before reaching the carrier.
Show child attributes
event_payload.data.error.codeStandardized 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_fraud_protection: Bird fraud protection blocked suspected SMS pumping.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_fraud_protection, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, insufficient_balance, unknown
event_payload.data.error.descriptionThe failure in words: the provider's reason text, or Bird's explanation for a fraud protection block or a message refused before submission. Free-form, so branch on code and show this to a human.
event_payload.data.error.carrier_error_codeRaw 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_atWhen the failure occurred.
The API handed the message to the carrier for delivery.
event_payload.typeEvent type.
Possible values: sms.sent
event_payload.timestampTime the message was handed to the carrier.
event_payload.dataPayload of the sms.sent event.
Show child attributes
event_payload.data.sms_idID of the SMS message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toWhere 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.fromWhere 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.tagsTags 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.metadataThe 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_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_languageThe template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_idThe template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_idThe 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_hashThe rendered language's source fingerprint, or null for a free-text message.
event_payload.data.costMessage 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.
Show child attributes
event_payload.data.cost.amountTotal 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_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amountWhat 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_amountThird-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.carrierCarrier that handled the message. Absent when the carrier does not report one.
event_payload.data.mcc_mncMobile 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.typeEvent type.
Possible values: sms.undelivered
event_payload.timestampTime the non-delivery was recorded.
event_payload.dataPayload of the sms.undelivered event.
Show child attributes
event_payload.data.sms_idID of the SMS message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toWhere 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.fromWhere 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.tagsTags 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.metadataThe 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_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
event_payload.data.resolved_languageThe template language rendered at acceptance, in canonical form. Null when the send used no template.
event_payload.data.template_idThe template rendered at acceptance, or null for a free-text message.
event_payload.data.template_version_idThe 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_hashThe rendered language's source fingerprint, or null for a free-text message.
event_payload.data.costMessage 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.
Show child attributes
event_payload.data.cost.amountTotal 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_codeISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.cost.transaction_amountWhat 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_amountThird-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.errorWhy the message was not delivered.
Show child attributes
event_payload.data.error.codeStandardized 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_fraud_protection: Bird fraud protection blocked suspected SMS pumping.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_fraud_protection, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, insufficient_balance, unknown
event_payload.data.error.descriptionThe failure in words: the provider's reason text, or Bird's explanation for a fraud protection block or a message refused before submission. Free-form, so branch on code and show this to a human.
event_payload.data.error.carrier_error_codeRaw 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_atWhen 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.typeAlways sms_suppression.created for this event.
Possible values: sms_suppression.created
event_payload.timestampWhen the episode's opening statement took effect (effective_at).
event_payload.dataPayload of the sms_suppression.created event.
Show child attributes
event_payload.data.suppression_idThe suppression episode that was opened.
event_payload.data.destinationThe subscriber, in E.164 format.
event_payload.data.originatorThe sender this stops. An SMS suppression is the exact (sender, recipient) pair, so your other senders still reach this subscriber.
event_payload.data.reasonevent_payload.data.workspace_idThe workspace the suppression belongs to.
The channel confirmed delivery of a one-time passcode to the recipient.
event_payload.typeEvent type.
Possible values: verify.attempt.delivered
event_payload.timestampTime delivery was confirmed.
event_payload.dataPayload of the verify.attempt.delivered event.
Show child attributes
event_payload.data.verification_idID of the verification session.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toThe 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.
Show child attributes
event_payload.data.to.emailThe recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_numberThe 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.metadataThe 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.channelThe channel this attempt was sent on.
Possible values (may grow over time): email, sms, whatsapp, telegram, voice
event_payload.data.addressThe single address this attempt was dispatched to, an E.164 phone number or an email address.
event_payload.data.carrierCarrier that delivered the message, when the carrier network reports it. Always null for email, WhatsApp, and Telegram.
event_payload.data.mcc_mncMobile country code and mobile network code of the delivering carrier, when reported. Always null for email, WhatsApp, and Telegram.
event_payload.data.delivered_atTime delivery was confirmed.
A one-time passcode was dispatched to the recipient on a channel.
event_payload.typeEvent type.
Possible values: verify.attempt.sent
event_payload.timestampTime the passcode was dispatched.
event_payload.dataPayload of the verify.attempt.sent event.
Show child attributes
event_payload.data.verification_idID of the verification session.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toThe 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.
Show child attributes
event_payload.data.to.emailThe recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_numberThe 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.metadataThe 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.channelThe channel this attempt was sent on.
Possible values (may grow over time): email, sms, whatsapp, telegram, voice
event_payload.data.addressThe single address this attempt was dispatched to, an E.164 phone number or an email address.
event_payload.data.fromThe 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_atTime the passcode was dispatched.
A one-time passcode failed to deliver to the recipient.
event_payload.typeEvent type.
Possible values: verify.attempt.undelivered
event_payload.timestampTime the failure was recorded.
event_payload.dataPayload of the verify.attempt.undelivered event.
Show child attributes
event_payload.data.verification_idID of the verification session.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toThe 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.
Show child attributes
event_payload.data.to.emailThe recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_numberThe 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.metadataThe 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.channelThe channel this attempt was sent on.
Possible values (may grow over time): email, sms, whatsapp, telegram, voice
event_payload.data.addressThe single address this attempt was dispatched to, an E.164 phone number or an email address.
event_payload.data.reasonWhy 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.errorDiagnostic text describing the failure, for display only. Null when none was reported.
event_payload.data.failed_atTime the failure was recorded.
A verification session was created and its first one-time passcode is being sent.
event_payload.typeEvent type.
Possible values: verify.verification.created
event_payload.timestampTime the verification session was created.
event_payload.dataPayload of the verify.verification.created event.
Show child attributes
event_payload.data.verification_idID of the verification session.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toThe 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.
Show child attributes
event_payload.data.to.emailThe recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_numberThe 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.metadataThe 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.channelThe first channel of the verification's resolved channel plan.
Possible values (may grow over time): email, sms, whatsapp, telegram, voice
event_payload.data.statusThe verification's state at creation, always pending. Open enum for forward compatibility.
Possible values (may grow over time): pending
event_payload.data.created_atTime 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.typeAlways verify.verification.failed for this event.
Possible values: verify.verification.failed
event_payload.timestampTime the verification was resolved.
event_payload.dataPayload of the verify.verification.failed event.
Show child attributes
event_payload.data.verification_idID of the verification session.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toThe 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.
Show child attributes
event_payload.data.to.emailThe recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_numberThe 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.metadataThe 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.statusThe verification's state, always failed. Open enum for forward compatibility.
Possible values (may grow over time): failed
event_payload.data.reasonWhy 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.channelThe 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_reasonWhy 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_atTime the verification was resolved.
The verification was successfully resolved: the recipient confirmed the correct code.
event_payload.typeEvent type.
Possible values: verify.verification.verified
event_payload.timestampTime the verification was verified.
event_payload.dataPayload of the verify.verification.verified event.
Show child attributes
event_payload.data.verification_idID of the verification session.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.toThe 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.
Show child attributes
event_payload.data.to.emailThe recipient's email address. Case does not matter; the address is lowercased before use.
event_payload.data.to.phone_numberThe 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.metadataThe 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.statusThe verification's state, always verified. Open enum for forward compatibility.
Possible values (may grow over time): verified
event_payload.data.channelThe channel whose passcode the recipient confirmed, the channel that converted. Null when the verification was resolved without attributing a channel.
event_payload.data.verified_atTime the verification was verified.
The called party answered and media began flowing.
event_payload.typeEvent type.
Possible values: voice_call.answered
event_payload.timestampTime the call was answered.
event_payload.dataPayload of the voice_call.answered event.
Show child attributes
event_payload.data.call_idID of the call record.
event_payload.data.session_idSession 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_idID of the workspace that owns this event.
event_payload.data.directionWhether the call was placed from your side, by your PBX, the API, the browser or Bird dialing onward for you (outbound), or arrived from a remote party (inbound).
Possible values: inbound, outbound
event_payload.data.fromCalling party number in E.164 format.
event_payload.data.toCalled party number in E.164 format.
The call ended after either party hung up or call setup failed.
event_payload.typeEvent type.
Possible values: voice_call.ended
event_payload.timestampTime either party hung up or call setup failed.
event_payload.dataPayload of the voice_call.ended event.
Show child attributes
event_payload.data.call_idID of the call record.
event_payload.data.session_idSession 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_idID of the workspace that owns this event.
event_payload.data.directionWhether the call was placed from your side, by your PBX, the API, the browser or Bird dialing onward for you (outbound), or arrived from a remote party (inbound).
Possible values: inbound, outbound
event_payload.data.fromCalling party number in E.164 format.
event_payload.data.toCalled party number in E.164 format.
event_payload.data.statusCall status.
A call that has ended carries one of:
answeredmeans it connected and the far end picked up.no_answermeans nobody picked up before the call timed out.rejectedmeans it was refused rather than attempted. Either we turned it away before dialing a carrier, in which caserejection_reasonnames the check it failed where there was one, or the far end declined it.failedmeans it was attempted and did not work, andsip_response_codeis what came back.unknownmeans the outcome could not be determined. Contact support with the callidif 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_codeFinal 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_msTotal call duration in milliseconds, measured from the first SIP INVITE to the BYE or final response.
event_payload.data.billable_msBillable duration in milliseconds, measured from answer to call end. Zero for unanswered calls.
Call routing began.
event_payload.typeEvent type.
Possible values: voice_call.initiated
event_payload.timestampTime the call was initiated.
event_payload.dataPayload of the voice_call.initiated event.
Show child attributes
event_payload.data.call_idID of the call record.
event_payload.data.session_idSession 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_idID of the workspace that owns this event.
event_payload.data.directionWhether the call was placed from your side, by your PBX, the API, the browser or Bird dialing onward for you (outbound), or arrived from a remote party (inbound).
Possible values: inbound, outbound
event_payload.data.fromCalling party number in E.164 format.
event_payload.data.toCalled party number in E.164 format.
The API accepted and charged the send request.
event_payload.typeEvent type.
Possible values: whatsapp.accepted
event_payload.timestampTime the API accepted and charged the send request.
event_payload.dataPayload of the whatsapp.accepted event.
Show child attributes
event_payload.data.whatsapp_idID of the WhatsApp message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.directionWhether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.fromSender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Show child attributes
event_payload.data.from.phone_numberPhone number in E.164 format, when known.
event_payload.data.from.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.toRecipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Show child attributes
event_payload.data.to.phone_numberPhone number in E.164 format, when known.
event_payload.data.to.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.tagsTags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadataThe 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_idThe 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.typeEvent type.
Possible values: whatsapp.delivered
event_payload.timestampTime the message was delivered to the recipient's device.
event_payload.dataPayload of the whatsapp.delivered event.
Show child attributes
event_payload.data.whatsapp_idID of the WhatsApp message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.directionWhether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.fromSender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Show child attributes
event_payload.data.from.phone_numberPhone number in E.164 format, when known.
event_payload.data.from.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.toRecipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Show child attributes
event_payload.data.to.phone_numberPhone number in E.164 format, when known.
event_payload.data.to.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.tagsTags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadataThe 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_idThe 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.recipientThe 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.
Show child attributes
event_payload.data.recipient.phone_numberPhone number in E.164 format, when known.
event_payload.data.recipient.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.typeEvent type.
Possible values: whatsapp.failed
event_payload.timestampTime the failure was recorded.
event_payload.dataPayload of the whatsapp.failed event.
Show child attributes
event_payload.data.whatsapp_idID of the WhatsApp message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.directionWhether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.fromSender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Show child attributes
event_payload.data.from.phone_numberPhone number in E.164 format, when known.
event_payload.data.from.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.toRecipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Show child attributes
event_payload.data.to.phone_numberPhone number in E.164 format, when known.
event_payload.data.to.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.tagsTags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadataThe 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_idThe 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.errorWhy the message terminally failed.
Show child attributes
event_payload.data.error.codeStandardized 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;descriptioncarries 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.descriptionHuman-readable explanation of the failure.
event_payload.data.error.meta_error_codeRaw error code from the WhatsApp Cloud API, when available, for low-level debugging.
event_payload.data.error.occurred_atWhen the failure occurred.
Someone asked to join a group that requires approval.
event_payload.typeAlways whatsapp.group.join_request_created for this event.
Possible values: whatsapp.group.join_request_created
event_payload.timestampWhen the person asked to join.
event_payload.dataPayload shared by the whatsapp.group.join_request_created and whatsapp.group.join_request_revoked events. Everything about the person who asked is nested under join_request; the sibling identifiers name the business side.
Show child attributes
event_payload.data.group_idThe group the person asked to join.
event_payload.data.whatsapp_number_idThe business number that created the group and administers it.
event_payload.data.workspace_idThe workspace that owns the group.
event_payload.data.join_requestThe request itself, and who made it.
Show child attributes
event_payload.data.join_request.idUnique identifier for the join request. Pass it to the batch-approve and batch-reject operations.
event_payload.data.join_request.bsuidBusiness-scoped user ID, Meta's identifier for this person against your business. The one identifier every request has, and the one that carries over to participants if you approve it.
event_payload.data.join_request.phone_numberPhone number in E.164 format. Null when WhatsApp withholds it, which it does for anyone who has not shared their number with your business.
event_payload.data.join_request.usernameThe WhatsApp username this person chose. Null when they have none, and theirs to change, so it names them in a list rather than keying anything.
Someone withdrew their request to join a group before it was decided.
event_payload.typeAlways whatsapp.group.join_request_revoked for this event.
Possible values: whatsapp.group.join_request_revoked
event_payload.timestampWhen the person withdrew their request.
event_payload.dataPayload shared by the whatsapp.group.join_request_created and whatsapp.group.join_request_revoked events. Everything about the person who asked is nested under join_request; the sibling identifiers name the business side.
Show child attributes
event_payload.data.group_idThe group the person asked to join.
event_payload.data.whatsapp_number_idThe business number that created the group and administers it.
event_payload.data.workspace_idThe workspace that owns the group.
event_payload.data.join_requestThe request itself, and who made it.
Show child attributes
event_payload.data.join_request.idUnique identifier for the join request. Pass it to the batch-approve and batch-reject operations.
event_payload.data.join_request.bsuidBusiness-scoped user ID, Meta's identifier for this person against your business. The one identifier every request has, and the one that carries over to participants if you approve it.
event_payload.data.join_request.phone_numberPhone number in E.164 format. Null when WhatsApp withholds it, which it does for anyone who has not shared their number with your business.
event_payload.data.join_request.usernameThe WhatsApp username this person chose. Null when they have none, and theirs to change, so it names them in a list rather than keying anything.
A contact placed, changed or took back a reaction on a message.
event_payload.typeAlways whatsapp.reacted for this event.
Possible values: whatsapp.reacted
event_payload.timestampWhen 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.dataPayload 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.
Show child attributes
event_payload.data.whatsapp_idThe 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.emojiThe 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.fromThe contact who reacted, as WhatsApp identified them.
Show child attributes
event_payload.data.from.phone_numberPhone number in E.164 format, when known.
event_payload.data.from.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.toYour WhatsApp number, the business side of the conversation.
Show child attributes
event_payload.data.to.phone_numberPhone number in E.164 format, when known.
event_payload.data.to.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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_idID of the workspace that owns this event.
The recipient read the message.
event_payload.typeEvent type.
Possible values: whatsapp.read
event_payload.timestampTime the recipient read the message.
event_payload.dataPayload of the whatsapp.read event.
Show child attributes
event_payload.data.whatsapp_idID of the WhatsApp message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.directionWhether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.fromSender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Show child attributes
event_payload.data.from.phone_numberPhone number in E.164 format, when known.
event_payload.data.from.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.toRecipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Show child attributes
event_payload.data.to.phone_numberPhone number in E.164 format, when known.
event_payload.data.to.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.tagsTags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadataThe 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_idThe 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.recipientThe 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.
Show child attributes
event_payload.data.recipient.phone_numberPhone number in E.164 format, when known.
event_payload.data.recipient.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.typeEvent type.
Possible values: whatsapp.received
event_payload.timestampTime the contact sent the message, as reported by WhatsApp.
event_payload.dataPayload of the whatsapp.received event. Carries the message's content so a subscriber can act on it without reading the message back.
Show child attributes
event_payload.data.whatsapp_idID of the WhatsApp message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.directionWhether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.fromSender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Show child attributes
event_payload.data.from.phone_numberPhone number in E.164 format, when known.
event_payload.data.from.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.toRecipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Show child attributes
event_payload.data.to.phone_numberPhone number in E.164 format, when known.
event_payload.data.to.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.tagsTags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadataThe 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_idThe 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.textText the contact sent.
Show child attributes
event_payload.data.text.bodyThe message text.
event_payload.data.imageImage the contact sent.
Show child attributes
event_payload.data.image.idID 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.urlWhere 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_typeMedia type WhatsApp reported for the file, for example image/jpeg. Absent on outbound messages.
event_payload.data.image.captionText shown beneath the image. Absent when the sender wrote none.
event_payload.data.videoVideo the contact sent.
Show child attributes
event_payload.data.video.idID 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.urlWhere 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_typeMedia type WhatsApp reported for the file, for example image/jpeg. Absent on outbound messages.
event_payload.data.video.captionText shown beneath the video. Absent when the sender wrote none.
event_payload.data.audioAudio the contact sent.
Show child attributes
event_payload.data.audio.idID 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.urlWhere 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_typeMedia type WhatsApp reported for the file, for example image/jpeg. Absent on outbound messages.
event_payload.data.audio.voiceWhether 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.stickerSticker the contact sent.
Show child attributes
event_payload.data.sticker.idID 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.urlWhere 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_typeMedia type WhatsApp reported for the file, for example image/jpeg. Absent on outbound messages.
event_payload.data.sticker.animatedWhether the sticker is animated. Absent on an outbound message.
event_payload.data.documentDocument the contact sent.
Show child attributes
event_payload.data.document.idID 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.urlWhere 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_typeMedia type WhatsApp reported for the file, for example image/jpeg. Absent on outbound messages.
event_payload.data.document.captionText shown beneath the document. Absent when the sender wrote none.
event_payload.data.document.filenameThe sender's own name for the file.
event_payload.data.locationLocation the contact sent.
Show child attributes
event_payload.data.location.latitudeLatitude in decimal degrees.
event_payload.data.location.longitudeLongitude in decimal degrees.
event_payload.data.location.nameName of the place. Absent when the sender shared a plain pin.
event_payload.data.location.addressStreet address of the place. Shown only when name is also set.
event_payload.data.location.urlLink 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_cardsContact cards the contact shared, either by tapping a button that asked for their number or by sending a card from their address book.
Show child attributes
event_payload.data.contact_cards.originWhy 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.vcardThe 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.nameThe contact's name, when the card carries one.
Show child attributes
event_payload.data.contact_cards.name.formatted_nameThe whole name as the contact's device renders it.
event_payload.data.contact_cards.name.first_nameevent_payload.data.contact_cards.name.middle_nameevent_payload.data.contact_cards.name.last_nameevent_payload.data.contact_cards.name.prefixevent_payload.data.contact_cards.name.suffixevent_payload.data.contact_cards.orgWhere the contact works, when the card carries it.
Show child attributes
event_payload.data.contact_cards.org.companyevent_payload.data.contact_cards.org.departmentevent_payload.data.contact_cards.org.titleevent_payload.data.contact_cards.birthdayThe 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_numbersThe numbers on the card. A button tap carries the contact's own number here, which is the point of asking.
Show child attributes
event_payload.data.contact_cards.phone_numbers.phone_numberThe 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.typeThe 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.emailsShow child attributes
event_payload.data.contact_cards.emails.emailevent_payload.data.contact_cards.emails.typeThe 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.urlsShow child attributes
event_payload.data.contact_cards.urls.urlThe 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.typeThe 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.addressesShow child attributes
event_payload.data.contact_cards.addresses.streetevent_payload.data.contact_cards.addresses.cityevent_payload.data.contact_cards.addresses.stateevent_payload.data.contact_cards.addresses.zipevent_payload.data.contact_cards.addresses.countryevent_payload.data.contact_cards.addresses.country_codeThe 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.typeThe 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_replyWhat the contact tapped, when the message answers an interactive message or a template's quick-reply button.
Show child attributes
event_payload.data.interactive_reply.typeWhich kind of tap this reply came from, and which field carries it.
event_payload.data.interactive_reply.buttonThe 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.
Show child attributes
event_payload.data.interactive_reply.button.slugThe 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.textThe label the recipient saw.
event_payload.data.interactive_reply.listThe row the contact chose, as you declared it. description is present only when the row carried one.
Show child attributes
event_payload.data.interactive_reply.list.slugThe handle the row carries back, never shown to the recipient.
event_payload.data.interactive_reply.list.textThe row's label, shown as its title in the menu.
event_payload.data.interactive_reply.list.descriptionThe second line under the label. Absent when the row carried none.
event_payload.data.unsupportedSet when the contact sent content the API does not model, naming the WhatsApp content type.
Show child attributes
event_payload.data.unsupported.typeThe 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.typeEvent type.
Possible values: whatsapp.rejected
event_payload.timestampTime the rejection was recorded.
event_payload.dataPayload of the whatsapp.rejected event.
Show child attributes
event_payload.data.whatsapp_idID of the WhatsApp message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.directionWhether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.fromSender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Show child attributes
event_payload.data.from.phone_numberPhone number in E.164 format, when known.
event_payload.data.from.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.toRecipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Show child attributes
event_payload.data.to.phone_numberPhone number in E.164 format, when known.
event_payload.data.to.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.tagsTags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadataThe 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_idThe 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.errorWhy the message was rejected before sending.
Show child attributes
event_payload.data.error.codeStandardized 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;descriptioncarries 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.descriptionHuman-readable explanation of the failure.
event_payload.data.error.meta_error_codeRaw error code from the WhatsApp Cloud API, when available, for low-level debugging.
event_payload.data.error.occurred_atWhen the failure occurred.
The API handed the message to Meta for delivery.
event_payload.typeEvent type.
Possible values: whatsapp.sent
event_payload.timestampTime the API handed the message to Meta for delivery.
event_payload.dataPayload of the whatsapp.sent event.
Show child attributes
event_payload.data.whatsapp_idID of the WhatsApp message.
event_payload.data.workspace_idID of the workspace that owns this event.
event_payload.data.directionWhether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.fromSender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Show child attributes
event_payload.data.from.phone_numberPhone number in E.164 format, when known.
event_payload.data.from.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.toRecipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Show child attributes
event_payload.data.to.phone_numberPhone number in E.164 format, when known.
event_payload.data.to.bsuidBusiness-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_idThe 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.usernamePresent 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_namePresent 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.tagsTags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadataThe 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_idThe 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.typeAlways whatsapp_suppression.created for this event.
Possible values: whatsapp_suppression.created
event_payload.timestampWhen the episode's opening statement took effect (effective_at).
event_payload.dataPayload of the whatsapp_suppression.created event.
Show child attributes
event_payload.data.suppression_idThe suppression episode that was opened.
event_payload.data.addressThe suppressed WhatsApp address. For a phone number this is canonical E.164 with a leading plus sign, such as +5511977670804.
event_payload.data.wabaThe 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.reasonWhy 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_idThe workspace the suppression belongs to.
errorA short explanation of why the event could not be delivered. Present only when your endpoint could not be reached.
Related resources
Continue with the documentation, guides and examples for this topic.