Send a message

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.

Apple’s opaque customer identifier for this business, available as the conversation’s recipient.opaque_user_id. The conversation must exist and its native status must be open.

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

A text message. Alongside rich_link or interactive, it is sent first as its own text bubble, in the same message.

A link with a preview card.

Something for the customer to tap, such as quick replies, a list picker, a time picker, a form or a custom iMessage app.

Send using a stored template instead of text, rich_link or interactive. The category is derived from the template, so category is rejected alongside it.

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. Rejected alongside template, where the category is derived from the template.

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.

Structured {name, value} labels for filtering. Maximum 20 tags per send.

An identifier you want to find this message by, such as an order or ticket number, matched exactly by the message list's reference filter. Set it only when you need to search on it, and put any other data in metadata. Stored on the message, returned on reads and echoed in webhook payloads. Several messages can share one.

Department identifier for this message.

Purpose of this conversation.

Apple locale identifier, for example en_US. Defaults to the conversation locale.

Send the first part without the typing indicator and one-second pause Bird otherwise shows before it. Set it only after you sent typing_start with the conversation typing operation, so the customer already sees typing. A first part that Apple accepts clears that indicator when it arrives. If Bird accepts the message but it fails before then, such as a failed send or a rejection during processing, Bird sends typing_end instead. If the request itself returns an error, nothing is sent, so send typing_end yourself. When Bird splits the message into several parts, such as text around a link, the parts after the first keep their typing indicator.

ID of the message, assigned when it is accepted or received. Pass it as message_id to the get-message and list-events endpoints.

The conversation this message belongs to.

The business the message was sent from or received by.

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.

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.

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

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

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

Who sent this message. Absent on an inbound message, which has no source to report.

Possible values: operator, automation, api

The message's text and files. Next to rich_link, interactive or interactive_reply, it is the text that came with them.

The link preview an outbound message carried.

What an outbound message offered the customer to tap.

What the customer answered, on an inbound message replying to an interactive message.

Original message matched through Apple’s request identifier within the same workspace, business, and conversation. Omitted when no verified match exists, including when more than one sent message in the conversation uses the reply's request identifier.

Latest customer reply whose in_reply_to_message_id names this message. Omitted until a reply is matched, and in webhook payloads.

When Apple delivered the reply in reply_message_id to Bird. This can be slightly earlier than that reply's created_at, which records when Bird processed it. Omitted until a reply is matched, and in webhook payloads.

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.

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.

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.

Structured {name, value} filter labels applied to this message. Absent on an inbound message.

The reference from the send request. Absent when the send set none, and on inbound messages.

Recorded 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.

Failure detail on a message whose send failed or that Bird rejected before any send attempt. Omitted when there is no failure detail.

The moment this message was accepted (outbound), or recorded by Bird after Apple delivered it (inbound). This is the timestamp the outbound statistics families bucket and attribute on; there is no separate accepted_at field.

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.

Apple department identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.

Apple purpose identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.

The template language requested by the send, in canonical form. Null when the send named no language or used no template.

The template language whose text was rendered, in canonical form. Null when the send used no template. This can differ from requested_language when the template's fallback policy selects another language.

The template rendered for this message, or null for a message sent with native content.

The workspace published version or synthetic built-in version rendered at acceptance, or null for a message sent with native content. For a built-in template, template_content_hash identifies the exact catalogue source.

The rendered language's source fingerprint, or null for a message sent with native content.