Send a message
POST
/v1/amb/messages
const result = await bird.amb.send({
from: "b52d6267-2b62-4f8a-8842-0533d0f1dc07",
to: "opaque-customer",
content: { type: "text", body: "Your order is ready." },
});
console.log(result);result = client.amb.send(from_='b52d6267-2b62-4f8a-8842-0533d0f1dc07', to='opaque-customer', content={'type': 'text', 'body': 'Your order is ready.'})
print(result)result, err := client.Amb.Send(ctx, bird.AmbSendParams{From: "b52d6267-2b62-4f8a-8842-0533d0f1dc07", To: "opaque-customer", Content: map[string]any{"type": "text", "body": "Your order is ready."}})
if err != nil {
log.Fatal(err)
}
fmt.Println(result)$bird->amb->send((new Model\AMBMessageSendRequest())->setFrom('b52d6267-2b62-4f8a-8842-0533d0f1dc07')->setTo('opaque-customer')->setContent(['type' => 'text', 'body' => 'Your order is ready.']));bird amb send \
--content '{"body":"Your order is ready.","type":"text"}' \
--from b52d6267-2b62-4f8a-8842-0533d0f1dc07 \
--to opaque-customer-idcurl -X POST "https://us1.platform.bird.com/v1/amb/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": "b52d6267-2b62-4f8a-8842-0533d0f1dc07",
"to": "opaque-customer-id",
"content": {
"type": "text",
"body": "Your order is ready."
}
}'Risposta202
{
"id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
"conversation_id": "acv_01krdgeqcxet5s7t44vh8rt9mg",
"business_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."
}
}
Send a message in an existing Apple Messages for Business conversation. from is the Apple business identifier and to is the customer’s opaque identifier for that business. An unknown conversation returns 404; a closed conversation returns 422. Only the customer can reopen a conversation.
Choose text, rich_link, or interactive content. Interactive content contains a quick reply, list picker, event, form, or custom iMessage app. Native payment and authentication requests are not available through this public operation. Device support varies; an unsupported interaction returns 422.
Supply attachment URLs or reusable Apple references. Bird downloads source URLs and uploads the files before sending. Interactive images must be PNG files up to 200 kB each, totaling at most 5 MB. Each attachment must be smaller than 100 MB. A media or provider failure after acceptance changes the message status to send_failed.
The 202 response confirms acceptance, not delivery. Read the message to obtain its final status and any reusable reference returned by Apple.
Payload della richiesta
from
string
obbligatorio
Apple business identifier of the brand sending the message. Read it from the business’s apple_business_id. The customer must have opened the conversation with this business.
to
string
obbligatorio
Apple’s opaque customer identifier for this business, available as the conversation’s opaque_user_id. The conversation must exist and be open.
source
string
Who this message is sent as. A signed-in session may send as operator or automation; an API key may send as api or automation. Omit it to take the default for your credential. Naming a source your credential cannot use is refused with a 422 AMBMessageSourceNotPermitted.
Possible values: operator, automation, api
content
object
obbligatorio
Message content in Apple’s native text, rich_link, or interactive family.
Mostra parametri secondari
content.type
string
obbligatorio
Always text.
Value: text
content.body
string
Text displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
content.subject
string
Subject displayed above the message body.
content.attachments
array
Ordered attachments. Each object supplies a source URL or an encrypted Apple reference.
Mostra parametri secondari
content.attachments.source_url
string
obbligatorio
HTTPS URL Bird downloads and uploads to Apple.
content.attachments.name
string
Display filename.
content.attachments.mime_type
string
Media type of the attachment.
content.attachments.name
string
Display filename.
content.attachments.mime_type
string
Media type of the attachment.
content.attachments.url
string
obbligatorio
Encrypted attachment URL returned by Apple.
content.attachments.owner
string
obbligatorio
Opaque owner value returned by Apple.
content.attachments.signature_base64
string
obbligatorio
Attachment authorization signature returned by Apple.
content.attachments.key
string
obbligatorio
Attachment decryption key returned by Apple.
content.attachments.size
integer
obbligatorio
Attachment size in bytes.
content.type
string
obbligatorio
Always rich_link.
Value: rich_link
content.body
string
Text displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
content.subject
string
Subject displayed above the message body.
content.attachments
array
Ordered attachments. Each object supplies a source URL or an encrypted Apple reference.
Mostra parametri secondari
content.attachments.source_url
string
obbligatorio
HTTPS URL Bird downloads and uploads to Apple.
content.attachments.name
string
Display filename.
content.attachments.mime_type
string
Media type of the attachment.
content.attachments.name
string
Display filename.
content.attachments.mime_type
string
Media type of the attachment.
content.attachments.url
string
obbligatorio
Encrypted attachment URL returned by Apple.
content.attachments.owner
string
obbligatorio
Opaque owner value returned by Apple.
content.attachments.signature_base64
string
obbligatorio
Attachment authorization signature returned by Apple.
content.attachments.key
string
obbligatorio
Attachment decryption key returned by Apple.
content.attachments.size
integer
obbligatorio
Attachment size in bytes.
content.rich_link_data
object
Mostra parametri secondari
content.rich_link_data.url
string
obbligatorio
HTTPS URL opened by the preview.
content.rich_link_data.title
string
obbligatorio
Preview title.
content.rich_link_data.assets
object
obbligatorio
Mostra parametri secondari
content.rich_link_data.assets.image
object
obbligatorio
Mostra parametri secondari
content.rich_link_data.assets.image.source_url
string
obbligatorio
HTTPS URL of a PNG preview image up to 200 kB. Bird fetches and encodes it when sending.
content.rich_link_data.assets.image.mime_type
string
PNG media type required by Apple. Defaults to image/png.
Value: image/png
content.rich_link_data.assets.video
object
Mostra parametri secondari
content.rich_link_data.assets.video.url
string
obbligatorio
HTTPS video URL fetched by Apple.
content.rich_link_data.assets.video.mime_type
string
Media type of the video. Defaults to video/mp4; supply the actual type for other formats.
content.rich_link_data_ref
Reusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Mostra parametri secondari
content.rich_link_data_ref.title
string
Title supplied by Apple for the preview.
content.rich_link_data_ref.url
string
obbligatorio
Location of the encrypted preview.
content.rich_link_data_ref.owner
string
obbligatorio
Owner identifier supplied by Apple.
content.rich_link_data_ref.signature_base64
string
obbligatorio
Signature supplied by Apple.
content.rich_link_data_ref.key
string
obbligatorio
Decryption key supplied by Apple.
content.rich_link_data_ref.size
integer
obbligatorio
Size of the encrypted preview in bytes.
content.rich_link_data_ref.title
string
Title supplied by Apple for the preview.
content.rich_link_data_ref.bid
string
obbligatorio
Messages extension identifier supplied by Apple, when present.
content.rich_link_data_ref.data_ref_sig
string
obbligatorio
Signature binding the reference to the business, when supplied by Apple.
content.rich_link_data_ref.url
string
obbligatorio
Location of the encrypted preview.
content.rich_link_data_ref.owner
string
obbligatorio
Owner identifier supplied by Apple.
content.rich_link_data_ref.signature_base64
string
obbligatorio
Signature supplied by Apple.
content.rich_link_data_ref.size
integer
obbligatorio
Size of the encrypted preview in bytes.
content.type
string
obbligatorio
Always interactive.
Value: interactive
content.body
string
Text displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
content.subject
string
Subject displayed above the message body.
content.attachments
array
Ordered attachments. Each object supplies a source URL or an encrypted Apple reference.
Mostra parametri secondari
content.attachments.source_url
string
obbligatorio
HTTPS URL Bird downloads and uploads to Apple.
content.attachments.name
string
Display filename.
content.attachments.mime_type
string
Media type of the attachment.
content.attachments.name
string
Display filename.
content.attachments.mime_type
string
Media type of the attachment.
content.attachments.url
string
obbligatorio
Encrypted attachment URL returned by Apple.
content.attachments.owner
string
obbligatorio
Opaque owner value returned by Apple.
content.attachments.signature_base64
string
obbligatorio
Attachment authorization signature returned by Apple.
content.attachments.key
string
obbligatorio
Attachment decryption key returned by Apple.
content.attachments.size
integer
obbligatorio
Attachment size in bytes.
content.interactive_data
A built-in interaction or custom iMessage app. Custom apps require the app metadata and both message bubbles.
Mostra parametri secondari
content.interactive_data.session_identifier
string
Session UUID to preserve across interactions. Apple creates one when omitted.
content.interactive_data.data
obbligatorio
Exactly one built-in interaction. Protocol versions are managed by Bird.
Mostra parametri secondari
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra parametri secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.quick_reply
object
obbligatorio
Mostra parametri secondari
content.interactive_data.data.quick_reply.summary_text
string
obbligatorio
Text 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.
content.interactive_data.data.quick_reply.items
array of object
obbligatorio
The 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.
Mostra parametri secondari
content.interactive_data.data.quick_reply.items.identifier
string
obbligatorio
Opaque choice identifier returned in interactive_data.data.quick_reply.selected_identifier.
content.interactive_data.data.quick_reply.items.title
string
obbligatorio
Label shown on the button.
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra parametri secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.list_picker
object
obbligatorio
Mostra parametri secondari
content.interactive_data.data.list_picker.sections
array of object
obbligatorio
The menu's sections, each with its own heading and rows.
Mostra parametri secondari
content.interactive_data.data.list_picker.sections.title
string
obbligatorio
Heading shown above this section's rows.
content.interactive_data.data.list_picker.sections.order
nullable integer
Where this section sits relative to its siblings, ascending. Sections omitting it are laid out in list order, after any that specify one.
content.interactive_data.data.list_picker.sections.items
array of object
obbligatorio
The rows in this section.
Mostra parametri secondari
content.interactive_data.data.list_picker.sections.items.identifier
string
obbligatorio
Opaque item identifier returned in interactive_data.data.list_picker.sections.
content.interactive_data.data.list_picker.sections.items.title
string
obbligatorio
Label shown on the row.
content.interactive_data.data.list_picker.sections.items.subtitle
nullable string
Secondary line shown under the title.
content.interactive_data.data.list_picker.sections.items.image_identifier
nullable string
Identifier 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.
content.interactive_data.data.list_picker.sections.items.order
integer
Position within the section, ascending. Defaults to the row's array position.
content.interactive_data.data.list_picker.sections.multiple_selection
boolean
Whether the customer can select more than one row in this section.
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra parametri secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.event
object
obbligatorio
Mostra parametri secondari
content.interactive_data.data.event.identifier
string
Your identifier for the event. Defaults to the message identifier.
content.interactive_data.data.event.location
object
Optional appointment location.
Mostra parametri secondari
content.interactive_data.data.event.location.title
string
Name shown for the appointment location.
content.interactive_data.data.event.location.latitude
number
Latitude in degrees. Set together with longitude.
content.interactive_data.data.event.location.longitude
number
Longitude in degrees. Set together with latitude.
content.interactive_data.data.event.location.radius
number
Location radius in meters. Apple ignores it without coordinates.
content.interactive_data.data.event.timezone_offset
integer
Minutes from GMT at the event location. Omit to use the customer's time zone.
content.interactive_data.data.event.timeslots
array of object
obbligatorio
Appointment times with RFC 3339 timestamps and duration in seconds.
Mostra parametri secondari
content.interactive_data.data.event.timeslots.identifier
string
obbligatorio
Opaque slot identifier. Apple may instead return only a localized label in interactive_data.reply_message.title.
content.interactive_data.data.event.timeslots.start_at
string
obbligatorio
When 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.
content.interactive_data.data.event.timeslots.duration_seconds
integer
obbligatorio
Duration in seconds. Zero indicates no duration.
content.interactive_data.data.event.image_identifier
string
Identifier of the event image in interactive_data.data.images.
content.interactive_data.data.event.title
string
Event title.
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra parametri secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.dynamic
object
obbligatorio
Form content. Bird supplies Apple’s messageForms template and protocol version.
Mostra parametri secondari
content.interactive_data.data.dynamic.data
object
obbligatorio
Mostra parametri secondari
content.interactive_data.data.dynamic.data.start_page_identifier
string
obbligatorio
Identifier of the first page to show.
content.interactive_data.data.dynamic.data.private
boolean
Whether Apple marks the submitted response as private.
content.interactive_data.data.dynamic.data.show_summary
boolean
Whether Apple shows a summary before the customer submits.
content.interactive_data.data.dynamic.data.splash
object
Mostra parametri secondari
content.interactive_data.data.dynamic.data.splash.header
string
content.interactive_data.data.dynamic.data.splash.splash_text
string
content.interactive_data.data.dynamic.data.splash.button_title
string
obbligatorio
content.interactive_data.data.dynamic.data.splash.image_identifier
string
content.interactive_data.data.dynamic.data.pages
array of object
obbligatorio
Form pages referenced by the start page and navigation identifiers.
Mostra parametri secondari
content.interactive_data.data.dynamic.data.pages.page_identifier
string
obbligatorio
Unique identifier for this page.
content.interactive_data.data.dynamic.data.pages.type
string
obbligatorio
Value: select
content.interactive_data.data.dynamic.data.pages.title
string
content.interactive_data.data.dynamic.data.pages.subtitle
string
obbligatorio
Question shown on this page.
content.interactive_data.data.dynamic.data.pages.next_page_identifier
string
Next page to show. Omit to finish the form. Single-select pages route through their items instead.
content.interactive_data.data.dynamic.data.pages.submit_form
boolean
Marks this page as an end page for the form. A page with no next page also finishes the form.
content.interactive_data.data.dynamic.data.pages.multiple_selection
boolean
content.interactive_data.data.dynamic.data.pages.items
array of object
obbligatorio
Mostra parametri secondari
content.interactive_data.data.dynamic.data.pages.items.identifier
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.items.title
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.items.value
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.items.image_identifier
string
content.interactive_data.data.dynamic.data.pages.items.next_page_identifier
string
content.interactive_data.data.dynamic.data.pages.page_identifier
string
obbligatorio
Unique identifier for this page.
content.interactive_data.data.dynamic.data.pages.type
string
obbligatorio
Value: picker
content.interactive_data.data.dynamic.data.pages.title
string
content.interactive_data.data.dynamic.data.pages.subtitle
string
obbligatorio
Question shown on this page.
content.interactive_data.data.dynamic.data.pages.next_page_identifier
string
Next page to show. Omit to finish the form. Single-select pages route through their items instead.
content.interactive_data.data.dynamic.data.pages.submit_form
boolean
Marks this page as an end page for the form. A page with no next page also finishes the form.
content.interactive_data.data.dynamic.data.pages.picker_title
string
Text beside the picker field. Omit to center the field without a label.
content.interactive_data.data.dynamic.data.pages.selected_item_index
integer
Zero-based index into items. Defaults to 0. Must be less than the number of items; otherwise sending returns 422 AMBFormPagesInvalid.
content.interactive_data.data.dynamic.data.pages.items
array of object
obbligatorio
Mostra parametri secondari
content.interactive_data.data.dynamic.data.pages.items.identifier
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.items.title
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.items.value
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.page_identifier
string
obbligatorio
Unique identifier for this page.
content.interactive_data.data.dynamic.data.pages.type
string
obbligatorio
Value: date_picker
content.interactive_data.data.dynamic.data.pages.title
string
content.interactive_data.data.dynamic.data.pages.subtitle
string
obbligatorio
Question shown on this page.
content.interactive_data.data.dynamic.data.pages.next_page_identifier
string
Next page to show. Omit to finish the form. Single-select pages route through their items instead.
content.interactive_data.data.dynamic.data.pages.submit_form
boolean
Marks this page as an end page for the form. A page with no next page also finishes the form.
content.interactive_data.data.dynamic.data.pages.hint_text
string
content.interactive_data.data.dynamic.data.pages.options
object
Apple defaults to UTC when interpreting these dates.
Mostra parametri secondari
content.interactive_data.data.dynamic.data.pages.options.date_format
string
Format used to read the date values in these options. Defaults to MM/dd/yyyy.
content.interactive_data.data.dynamic.data.pages.options.start_date
string
Date initially shown by the picker, written in date_format. Defaults to the current date.
content.interactive_data.data.dynamic.data.pages.options.maximum_date
string
Latest date the picker shows, written in date_format. Defaults to the current date.
content.interactive_data.data.dynamic.data.pages.options.minimum_date
string
Earliest date the picker shows, written in date_format.
content.interactive_data.data.dynamic.data.pages.options.label_text
string
Label beside the date field. Defaults to Date.
content.interactive_data.data.dynamic.data.pages.page_identifier
string
obbligatorio
Unique identifier for this page.
content.interactive_data.data.dynamic.data.pages.type
string
obbligatorio
Value: input
content.interactive_data.data.dynamic.data.pages.title
string
content.interactive_data.data.dynamic.data.pages.subtitle
string
obbligatorio
Question shown on this page.
content.interactive_data.data.dynamic.data.pages.next_page_identifier
string
Next page to show. Omit to finish the form. Single-select pages route through their items instead.
content.interactive_data.data.dynamic.data.pages.submit_form
boolean
Marks this page as an end page for the form. A page with no next page also finishes the form.
content.interactive_data.data.dynamic.data.pages.hint_text
string
content.interactive_data.data.dynamic.data.pages.options
object
Mostra parametri secondari
content.interactive_data.data.dynamic.data.pages.options.regex
string
Pattern Apple uses to validate the input. Use JSON string escaping for backslashes.
content.interactive_data.data.dynamic.data.pages.options.placeholder
string
Shown when the field is empty. Defaults to Required when required is true, otherwise Optional.
content.interactive_data.data.dynamic.data.pages.options.required
boolean
Disables the next-page button until the customer enters a value.
content.interactive_data.data.dynamic.data.pages.options.input_type
string
Defaults to singleline.
Possible values: singleline, multiline
content.interactive_data.data.dynamic.data.pages.options.label_text
string
Label for singleline input only. Omit for no label.
content.interactive_data.data.dynamic.data.pages.options.prefix_text
string
Text beside singleline input only, such as a currency symbol. Omit for no prefix.
content.interactive_data.data.dynamic.data.pages.options.maximum_character_count
integer
Defaults to 30 for singleline input and 300 for multiline input.
content.interactive_data.data.dynamic.data.pages.options.keyboard_type
string
Keyboard to display. Defaults to default.
Possible values (may grow over time): default, asciiCapable, numbersAndPunctuation, URL, numberPad, phonePad, namePhonePad, emailAddress, decimalPad, webSearch
content.interactive_data.data.dynamic.data.pages.options.text_content_type
string
Content 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
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra parametri secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.authenticate
object
obbligatorio
Authentication attempt created through the conversation authentication endpoint. Contains no authorization parameters or credentials.
Mostra parametri secondari
content.interactive_data.data.authenticate.authentication_id
string
obbligatorio
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra parametri secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.payment
object
obbligatorio
Apple Pay request created through the conversation payment endpoint. Contains no payment token or provider credentials.
Mostra parametri secondari
content.interactive_data.data.payment.payment_id
string
obbligatorio
content.interactive_data.app_id
string
obbligatorio
App Store identifier of the iMessage app.
content.interactive_data.app_name
string
obbligatorio
Name of the iMessage app.
content.interactive_data.bid
string
obbligatorio
Identifier of the iMessage extension, in Apple's com.apple.messages.MSMessageExtensionBalloonPlugin:team-id:extension-id format.
content.interactive_data.url
string
obbligatorio
Opaque URL string that Messages passes to the iMessage app.
content.interactive_data.use_live_layout
boolean
obbligatorio
Whether Messages renders the received and reply bubbles using Live Layout.
content.interactive_data.session_identifier
string
Session UUID to preserve across interactions. Apple creates one when omitted.
content.interactive_data.received_message
object
obbligatorio
Content Messages shows in the received message bubble.
Mostra parametri secondari
content.interactive_data.received_message.title
string
obbligatorio
Text shown on the message bubble.
content.interactive_data.received_message.subtitle
string
Secondary text shown below the title.
content.interactive_data.received_message.style
string
Bubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
content.interactive_data.received_message.image_identifier
string
Identifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
content.interactive_data.received_message.image_title
string
Title shown over an attached image in a custom iMessage app bubble.
content.interactive_data.received_message.image_subtitle
string
Subtitle shown over an attached image in a custom iMessage app bubble.
content.interactive_data.received_message.secondary_subtitle
string
Right-aligned title in a custom iMessage app bubble.
content.interactive_data.received_message.tertiary_subtitle
string
Right-aligned subtitle in a custom iMessage app bubble.
content.interactive_data.reply_message
object
obbligatorio
Content Messages shows in the reply message bubble.
Mostra parametri secondari
content.interactive_data.reply_message.title
string
obbligatorio
Text shown on the message bubble.
content.interactive_data.reply_message.subtitle
string
Secondary text shown below the title.
content.interactive_data.reply_message.style
string
Bubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
content.interactive_data.reply_message.image_identifier
string
Identifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
content.interactive_data.reply_message.image_title
string
Title shown over an attached image in a custom iMessage app bubble.
content.interactive_data.reply_message.image_subtitle
string
Subtitle shown over an attached image in a custom iMessage app bubble.
content.interactive_data.reply_message.secondary_subtitle
string
Right-aligned title in a custom iMessage app bubble.
content.interactive_data.reply_message.tertiary_subtitle
string
Right-aligned subtitle in a custom iMessage app bubble.
content.interactive_data.app_icon_source_url
string
obbligatorio
Publicly 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.
content.interactive_data_ref
Reusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Mostra parametri secondari
content.interactive_data_ref.title
string
Title supplied by Apple for the preview.
content.interactive_data_ref.url
string
obbligatorio
Location of the encrypted preview.
content.interactive_data_ref.owner
string
obbligatorio
Owner identifier supplied by Apple.
content.interactive_data_ref.signature_base64
string
obbligatorio
Signature supplied by Apple.
content.interactive_data_ref.key
string
obbligatorio
Decryption key supplied by Apple.
content.interactive_data_ref.size
integer
obbligatorio
Size of the encrypted preview in bytes.
content.interactive_data_ref.title
string
Title supplied by Apple for the preview.
content.interactive_data_ref.bid
string
obbligatorio
Messages extension identifier supplied by Apple, when present.
content.interactive_data_ref.data_ref_sig
string
obbligatorio
Signature binding the reference to the business, when supplied by Apple.
content.interactive_data_ref.url
string
obbligatorio
Location of the encrypted preview.
content.interactive_data_ref.owner
string
obbligatorio
Owner identifier supplied by Apple.
content.interactive_data_ref.signature_base64
string
obbligatorio
Signature supplied by Apple.
content.interactive_data_ref.size
integer
obbligatorio
Size of the encrypted preview in bytes.
category
string
Free-form reporting label; it does not change sending or suppression policy, for example order_update. Omit it to send with the default empty category.
metadata
object
Arbitrary 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.
tags
array of object
Structured {name, value} labels for filtering. Maximum 20 tags per send.
Mostra parametri secondari
tags.name
string
obbligatorio
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
tags.value
string
obbligatorio
Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
group
string
Department identifier for this message.
intent
string
Purpose of this conversation.
locale
string
Apple locale identifier, for example en_US. Defaults to the conversation locale.
Payload di risposta
id
string
obbligatorio
ID of the message, assigned when it is accepted or received. Pass it as message_id to the get-message and list-events endpoints.
conversation_id
string
obbligatorio
The conversation this message belongs to.
business_id
string
obbligatorio
The business the message was sent from or received by.
from
string
Apple 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.
to
string
Customer'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.
direction
string
obbligatorio
Whether 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
status
string
obbligatorio
Send status:
- accepted: Accepted and queued for delivery to Apple.
- sent: Handed to Apple. There is no delivery or read receipt on this channel, so sent is 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. See last_error for 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. See last_error.
- received: Received as an inbound message.
Possible values: accepted, sent, send_failed, rejected, received
kind
string
obbligatorio
Derived 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
source
string
Who sent this message. Absent on an inbound message, which has no source to report.
Possible values: operator, automation, api
content
object
obbligatorio
Native message content. Outgoing interactions contain requests; incoming interactions contain replies.
Mostra attributi secondari
content.type
string
obbligatorio
Always text.
Value: text
content.body
string
Text displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
content.subject
string
Subject displayed above the message body.
content.attachments
array
Ordered attachments. Each object supplies a source URL or an encrypted Apple reference.
Mostra attributi secondari
content.attachments.source_url
string
obbligatorio
HTTPS URL Bird downloads and uploads to Apple.
content.attachments.name
string
Display filename.
content.attachments.mime_type
string
Media type of the attachment.
content.attachments.name
string
Display filename.
content.attachments.mime_type
string
Media type of the attachment.
content.attachments.url
string
obbligatorio
Encrypted attachment URL returned by Apple.
content.attachments.owner
string
obbligatorio
Opaque owner value returned by Apple.
content.attachments.signature_base64
string
obbligatorio
Attachment authorization signature returned by Apple.
content.attachments.key
string
obbligatorio
Attachment decryption key returned by Apple.
content.attachments.size
integer
obbligatorio
Attachment size in bytes.
content.rich_link_data
object
Mostra attributi secondari
content.rich_link_data.url
string
obbligatorio
HTTPS URL opened by the preview.
content.rich_link_data.title
string
obbligatorio
Preview title.
content.rich_link_data.assets
object
obbligatorio
Mostra attributi secondari
content.rich_link_data.assets.image
object
obbligatorio
Mostra attributi secondari
content.rich_link_data.assets.image.source_url
string
obbligatorio
HTTPS URL of a PNG preview image up to 200 kB. Bird fetches and encodes it when sending.
content.rich_link_data.assets.image.mime_type
string
PNG media type required by Apple. Defaults to image/png.
Value: image/png
content.rich_link_data.assets.video
object
Mostra attributi secondari
content.rich_link_data.assets.video.url
string
obbligatorio
HTTPS video URL fetched by Apple.
content.rich_link_data.assets.video.mime_type
string
Media type of the video. Defaults to video/mp4; supply the actual type for other formats.
content.rich_link_data_ref
Reusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Mostra attributi secondari
content.rich_link_data_ref.title
string
Title supplied by Apple for the preview.
content.rich_link_data_ref.url
string
obbligatorio
Location of the encrypted preview.
content.rich_link_data_ref.owner
string
obbligatorio
Owner identifier supplied by Apple.
content.rich_link_data_ref.signature_base64
string
obbligatorio
Signature supplied by Apple.
content.rich_link_data_ref.key
string
obbligatorio
Decryption key supplied by Apple.
content.rich_link_data_ref.size
integer
obbligatorio
Size of the encrypted preview in bytes.
content.rich_link_data_ref.title
string
Title supplied by Apple for the preview.
content.rich_link_data_ref.bid
string
obbligatorio
Messages extension identifier supplied by Apple, when present.
content.rich_link_data_ref.data_ref_sig
string
obbligatorio
Signature binding the reference to the business, when supplied by Apple.
content.rich_link_data_ref.url
string
obbligatorio
Location of the encrypted preview.
content.rich_link_data_ref.owner
string
obbligatorio
Owner identifier supplied by Apple.
content.rich_link_data_ref.signature_base64
string
obbligatorio
Signature supplied by Apple.
content.rich_link_data_ref.size
integer
obbligatorio
Size of the encrypted preview in bytes.
content.interactive_data
A built-in interaction or custom iMessage app. Custom apps require the app metadata and both message bubbles.
Mostra attributi secondari
content.interactive_data.session_identifier
string
Session UUID to preserve across interactions. Apple creates one when omitted.
content.interactive_data.data
obbligatorio
Exactly one built-in interaction. Protocol versions are managed by Bird.
Mostra attributi secondari
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra attributi secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.quick_reply
object
obbligatorio
Mostra attributi secondari
content.interactive_data.data.quick_reply.summary_text
string
obbligatorio
Text 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.
content.interactive_data.data.quick_reply.items
array of object
obbligatorio
The 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.
Mostra attributi secondari
content.interactive_data.data.quick_reply.items.identifier
string
obbligatorio
Opaque choice identifier returned in interactive_data.data.quick_reply.selected_identifier.
content.interactive_data.data.quick_reply.items.title
string
obbligatorio
Label shown on the button.
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra attributi secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.list_picker
object
obbligatorio
Mostra attributi secondari
content.interactive_data.data.list_picker.sections
array of object
obbligatorio
The menu's sections, each with its own heading and rows.
Mostra attributi secondari
content.interactive_data.data.list_picker.sections.title
string
obbligatorio
Heading shown above this section's rows.
content.interactive_data.data.list_picker.sections.order
nullable integer
Where this section sits relative to its siblings, ascending. Sections omitting it are laid out in list order, after any that specify one.
content.interactive_data.data.list_picker.sections.items
array of object
obbligatorio
The rows in this section.
Mostra attributi secondari
content.interactive_data.data.list_picker.sections.items.identifier
string
obbligatorio
Opaque item identifier returned in interactive_data.data.list_picker.sections.
content.interactive_data.data.list_picker.sections.items.title
string
obbligatorio
Label shown on the row.
content.interactive_data.data.list_picker.sections.items.subtitle
nullable string
Secondary line shown under the title.
content.interactive_data.data.list_picker.sections.items.image_identifier
nullable string
Identifier 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.
content.interactive_data.data.list_picker.sections.items.order
integer
Position within the section, ascending. Defaults to the row's array position.
content.interactive_data.data.list_picker.sections.multiple_selection
boolean
Whether the customer can select more than one row in this section.
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra attributi secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.event
object
obbligatorio
Mostra attributi secondari
content.interactive_data.data.event.identifier
string
Your identifier for the event. Defaults to the message identifier.
content.interactive_data.data.event.location
object
Optional appointment location.
Mostra attributi secondari
content.interactive_data.data.event.location.title
string
Name shown for the appointment location.
content.interactive_data.data.event.location.latitude
number
Latitude in degrees. Set together with longitude.
content.interactive_data.data.event.location.longitude
number
Longitude in degrees. Set together with latitude.
content.interactive_data.data.event.location.radius
number
Location radius in meters. Apple ignores it without coordinates.
content.interactive_data.data.event.timezone_offset
integer
Minutes from GMT at the event location. Omit to use the customer's time zone.
content.interactive_data.data.event.timeslots
array of object
obbligatorio
Appointment times with RFC 3339 timestamps and duration in seconds.
Mostra attributi secondari
content.interactive_data.data.event.timeslots.identifier
string
obbligatorio
Opaque slot identifier. Apple may instead return only a localized label in interactive_data.reply_message.title.
content.interactive_data.data.event.timeslots.start_at
string
obbligatorio
When 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.
content.interactive_data.data.event.timeslots.duration_seconds
integer
obbligatorio
Duration in seconds. Zero indicates no duration.
content.interactive_data.data.event.image_identifier
string
Identifier of the event image in interactive_data.data.images.
content.interactive_data.data.event.title
string
Event title.
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra attributi secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.dynamic
object
obbligatorio
Form content. Bird supplies Apple’s messageForms template and protocol version.
Mostra attributi secondari
content.interactive_data.data.dynamic.data
object
obbligatorio
Mostra attributi secondari
content.interactive_data.data.dynamic.data.start_page_identifier
string
obbligatorio
Identifier of the first page to show.
content.interactive_data.data.dynamic.data.private
boolean
Whether Apple marks the submitted response as private.
content.interactive_data.data.dynamic.data.show_summary
boolean
Whether Apple shows a summary before the customer submits.
content.interactive_data.data.dynamic.data.splash
object
Mostra attributi secondari
content.interactive_data.data.dynamic.data.splash.header
string
content.interactive_data.data.dynamic.data.splash.splash_text
string
content.interactive_data.data.dynamic.data.splash.button_title
string
obbligatorio
content.interactive_data.data.dynamic.data.splash.image_identifier
string
content.interactive_data.data.dynamic.data.pages
array of object
obbligatorio
Form pages referenced by the start page and navigation identifiers.
Mostra attributi secondari
content.interactive_data.data.dynamic.data.pages.page_identifier
string
obbligatorio
Unique identifier for this page.
content.interactive_data.data.dynamic.data.pages.type
string
obbligatorio
Value: select
content.interactive_data.data.dynamic.data.pages.title
string
content.interactive_data.data.dynamic.data.pages.subtitle
string
obbligatorio
Question shown on this page.
content.interactive_data.data.dynamic.data.pages.next_page_identifier
string
Next page to show. Omit to finish the form. Single-select pages route through their items instead.
content.interactive_data.data.dynamic.data.pages.submit_form
boolean
Marks this page as an end page for the form. A page with no next page also finishes the form.
content.interactive_data.data.dynamic.data.pages.multiple_selection
boolean
content.interactive_data.data.dynamic.data.pages.items
array of object
obbligatorio
Mostra attributi secondari
content.interactive_data.data.dynamic.data.pages.items.identifier
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.items.title
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.items.value
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.items.image_identifier
string
content.interactive_data.data.dynamic.data.pages.items.next_page_identifier
string
content.interactive_data.data.dynamic.data.pages.page_identifier
string
obbligatorio
Unique identifier for this page.
content.interactive_data.data.dynamic.data.pages.type
string
obbligatorio
Value: picker
content.interactive_data.data.dynamic.data.pages.title
string
content.interactive_data.data.dynamic.data.pages.subtitle
string
obbligatorio
Question shown on this page.
content.interactive_data.data.dynamic.data.pages.next_page_identifier
string
Next page to show. Omit to finish the form. Single-select pages route through their items instead.
content.interactive_data.data.dynamic.data.pages.submit_form
boolean
Marks this page as an end page for the form. A page with no next page also finishes the form.
content.interactive_data.data.dynamic.data.pages.picker_title
string
Text beside the picker field. Omit to center the field without a label.
content.interactive_data.data.dynamic.data.pages.selected_item_index
integer
Zero-based index into items. Defaults to 0. Must be less than the number of items; otherwise sending returns 422 AMBFormPagesInvalid.
content.interactive_data.data.dynamic.data.pages.items
array of object
obbligatorio
Mostra attributi secondari
content.interactive_data.data.dynamic.data.pages.items.identifier
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.items.title
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.items.value
string
obbligatorio
content.interactive_data.data.dynamic.data.pages.page_identifier
string
obbligatorio
Unique identifier for this page.
content.interactive_data.data.dynamic.data.pages.type
string
obbligatorio
Value: date_picker
content.interactive_data.data.dynamic.data.pages.title
string
content.interactive_data.data.dynamic.data.pages.subtitle
string
obbligatorio
Question shown on this page.
content.interactive_data.data.dynamic.data.pages.next_page_identifier
string
Next page to show. Omit to finish the form. Single-select pages route through their items instead.
content.interactive_data.data.dynamic.data.pages.submit_form
boolean
Marks this page as an end page for the form. A page with no next page also finishes the form.
content.interactive_data.data.dynamic.data.pages.hint_text
string
content.interactive_data.data.dynamic.data.pages.options
object
Apple defaults to UTC when interpreting these dates.
Mostra attributi secondari
content.interactive_data.data.dynamic.data.pages.options.date_format
string
Format used to read the date values in these options. Defaults to MM/dd/yyyy.
content.interactive_data.data.dynamic.data.pages.options.start_date
string
Date initially shown by the picker, written in date_format. Defaults to the current date.
content.interactive_data.data.dynamic.data.pages.options.maximum_date
string
Latest date the picker shows, written in date_format. Defaults to the current date.
content.interactive_data.data.dynamic.data.pages.options.minimum_date
string
Earliest date the picker shows, written in date_format.
content.interactive_data.data.dynamic.data.pages.options.label_text
string
Label beside the date field. Defaults to Date.
content.interactive_data.data.dynamic.data.pages.page_identifier
string
obbligatorio
Unique identifier for this page.
content.interactive_data.data.dynamic.data.pages.type
string
obbligatorio
Value: input
content.interactive_data.data.dynamic.data.pages.title
string
content.interactive_data.data.dynamic.data.pages.subtitle
string
obbligatorio
Question shown on this page.
content.interactive_data.data.dynamic.data.pages.next_page_identifier
string
Next page to show. Omit to finish the form. Single-select pages route through their items instead.
content.interactive_data.data.dynamic.data.pages.submit_form
boolean
Marks this page as an end page for the form. A page with no next page also finishes the form.
content.interactive_data.data.dynamic.data.pages.hint_text
string
content.interactive_data.data.dynamic.data.pages.options
object
Mostra attributi secondari
content.interactive_data.data.dynamic.data.pages.options.regex
string
Pattern Apple uses to validate the input. Use JSON string escaping for backslashes.
content.interactive_data.data.dynamic.data.pages.options.placeholder
string
Shown when the field is empty. Defaults to Required when required is true, otherwise Optional.
content.interactive_data.data.dynamic.data.pages.options.required
boolean
Disables the next-page button until the customer enters a value.
content.interactive_data.data.dynamic.data.pages.options.input_type
string
Defaults to singleline.
Possible values: singleline, multiline
content.interactive_data.data.dynamic.data.pages.options.label_text
string
Label for singleline input only. Omit for no label.
content.interactive_data.data.dynamic.data.pages.options.prefix_text
string
Text beside singleline input only, such as a currency symbol. Omit for no prefix.
content.interactive_data.data.dynamic.data.pages.options.maximum_character_count
integer
Defaults to 30 for singleline input and 300 for multiline input.
content.interactive_data.data.dynamic.data.pages.options.keyboard_type
string
Keyboard to display. Defaults to default.
Possible values (may grow over time): default, asciiCapable, numbersAndPunctuation, URL, numberPad, phonePad, namePhonePad, emailAddress, decimalPad, webSearch
content.interactive_data.data.dynamic.data.pages.options.text_content_type
string
Content 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
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra attributi secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.authenticate
object
obbligatorio
Authentication attempt created through the conversation authentication endpoint. Contains no authorization parameters or credentials.
Mostra attributi secondari
content.interactive_data.data.authenticate.authentication_id
string
obbligatorio
content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
content.interactive_data.data.images
array of object
Images referenced by identifier.
Mostra attributi secondari
content.interactive_data.data.images.identifier
string
obbligatorio
Identifier referenced by a bubble, item, or event.
content.interactive_data.data.images.source_url
string
obbligatorio
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
content.interactive_data.data.payment
object
obbligatorio
Apple Pay request created through the conversation payment endpoint. Contains no payment token or provider credentials.
Mostra attributi secondari
content.interactive_data.data.payment.payment_id
string
obbligatorio
content.interactive_data.app_id
string
obbligatorio
App Store identifier of the iMessage app.
content.interactive_data.app_name
string
obbligatorio
Name of the iMessage app.
content.interactive_data.bid
string
obbligatorio
Identifier of the iMessage extension, in Apple's com.apple.messages.MSMessageExtensionBalloonPlugin:team-id:extension-id format.
content.interactive_data.url
string
obbligatorio
Opaque URL string that Messages passes to the iMessage app.
content.interactive_data.use_live_layout
boolean
obbligatorio
Whether Messages renders the received and reply bubbles using Live Layout.
content.interactive_data.session_identifier
string
Session UUID to preserve across interactions. Apple creates one when omitted.
content.interactive_data.received_message
object
obbligatorio
Content Messages shows in the received message bubble.
Mostra attributi secondari
content.interactive_data.received_message.title
string
obbligatorio
Text shown on the message bubble.
content.interactive_data.received_message.subtitle
string
Secondary text shown below the title.
content.interactive_data.received_message.style
string
Bubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
content.interactive_data.received_message.image_identifier
string
Identifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
content.interactive_data.received_message.image_title
string
Title shown over an attached image in a custom iMessage app bubble.
content.interactive_data.received_message.image_subtitle
string
Subtitle shown over an attached image in a custom iMessage app bubble.
content.interactive_data.received_message.secondary_subtitle
string
Right-aligned title in a custom iMessage app bubble.
content.interactive_data.received_message.tertiary_subtitle
string
Right-aligned subtitle in a custom iMessage app bubble.
content.interactive_data.reply_message
object
obbligatorio
Content Messages shows in the reply message bubble.
Mostra attributi secondari
content.interactive_data.reply_message.title
string
obbligatorio
Text shown on the message bubble.
content.interactive_data.reply_message.subtitle
string
Secondary text shown below the title.
content.interactive_data.reply_message.style
string
Bubble layout. Apple defaults to icon when omitted and ignores it for custom iMessage apps.
Possible values: icon, small, large
content.interactive_data.reply_message.image_identifier
string
Identifier of an image in interactive_data.data.images. Apple ignores it for custom iMessage apps.
content.interactive_data.reply_message.image_title
string
Title shown over an attached image in a custom iMessage app bubble.
content.interactive_data.reply_message.image_subtitle
string
Subtitle shown over an attached image in a custom iMessage app bubble.
content.interactive_data.reply_message.secondary_subtitle
string
Right-aligned title in a custom iMessage app bubble.
content.interactive_data.reply_message.tertiary_subtitle
string
Right-aligned subtitle in a custom iMessage app bubble.
content.interactive_data.app_icon_source_url
string
obbligatorio
Publicly 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.
content.interactive_data_ref
Reusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Mostra attributi secondari
content.interactive_data_ref.title
string
Title supplied by Apple for the preview.
content.interactive_data_ref.url
string
obbligatorio
Location of the encrypted preview.
content.interactive_data_ref.owner
string
obbligatorio
Owner identifier supplied by Apple.
content.interactive_data_ref.signature_base64
string
obbligatorio
Signature supplied by Apple.
content.interactive_data_ref.key
string
obbligatorio
Decryption key supplied by Apple.
content.interactive_data_ref.size
integer
obbligatorio
Size of the encrypted preview in bytes.
content.interactive_data_ref.title
string
Title supplied by Apple for the preview.
content.interactive_data_ref.bid
string
obbligatorio
Messages extension identifier supplied by Apple, when present.
content.interactive_data_ref.data_ref_sig
string
obbligatorio
Signature binding the reference to the business, when supplied by Apple.
content.interactive_data_ref.url
string
obbligatorio
Location of the encrypted preview.
content.interactive_data_ref.owner
string
obbligatorio
Owner identifier supplied by Apple.
content.interactive_data_ref.signature_base64
string
obbligatorio
Signature supplied by Apple.
content.interactive_data_ref.size
integer
obbligatorio
Size of the encrypted preview in bytes.
in_reply_to_message_id
string
Original message matched through Apple’s request identifier within the same workspace, business, and conversation. Omitted when no verified match exists.
locale
nullable string
Locale 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.
category
string
The 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.
metadata
object
Arbitrary 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.
tags
array of object
Structured {name, value} filter labels applied to this message. Absent on an inbound message.
Mostra attributi secondari
tags.name
string
obbligatorio
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
tags.value
string
obbligatorio
Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
cost
nullable object
obbligatorio
Recorded message charge. Null in the initial send response and while unpriced. The AMB charge is the transaction amount; no passthrough component is priced.
Mostra attributi secondari
cost.amount
string
obbligatorio
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
cost.currency_code
string
obbligatorio
ISO 4217 currency code. Every component is denominated in this currency.
cost.transaction_amount
nullable string
obbligatorio
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
cost.passthrough_amount
nullable string
obbligatorio
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
last_error
nullable object
Failure detail on a message whose send failed or that Bird rejected before any send attempt. Omitted when there is no failure detail.
Mostra attributi secondari
last_error.code
string
obbligatorio
Machine-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.
last_error.description
string
obbligatorio
The failure in words. Free-form, so branch on code and show this to a human.
last_error.occurred_at
string
obbligatorio
When the failure occurred.
created_at
string
obbligatorio
The 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.
sent_at
nullable string
When 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.
data_ref
Reusable encrypted content reference returned by Apple after a successful send. Absent until Apple returns one.
Mostra attributi secondari
data_ref.title
string
Title supplied by Apple for the preview.
data_ref.url
string
obbligatorio
Location of the encrypted preview.
data_ref.owner
string
obbligatorio
Owner identifier supplied by Apple.
data_ref.signature_base64
string
obbligatorio
Signature supplied by Apple.
data_ref.key
string
obbligatorio
Decryption key supplied by Apple.
data_ref.size
integer
obbligatorio
Size of the encrypted preview in bytes.
data_ref.title
string
Title supplied by Apple for the preview.
data_ref.bid
string
obbligatorio
Messages extension identifier supplied by Apple, when present.
data_ref.data_ref_sig
string
obbligatorio
Signature binding the reference to the business, when supplied by Apple.
data_ref.url
string
obbligatorio
Location of the encrypted preview.
data_ref.owner
string
obbligatorio
Owner identifier supplied by Apple.
data_ref.signature_base64
string
obbligatorio
Signature supplied by Apple.
data_ref.size
integer
obbligatorio
Size of the encrypted preview in bytes.
group
string
Apple department identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
intent
string
Apple purpose identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Ottieni un brief di implementazione