Reply through the Apple Messages API
Send a text reply to an existing Apple Messages conversation using the public Bird API, then inspect its processing status and receive customer replies.
Prepare the workspace and credential
Complete the dashboard first-conversation quickstart to connect a business and open a test conversation. Before approval, a business in Testing can send test messages to your test users. Ordinary replies use the customer's Apple opaque identifier; a phone number cannot replace it.
Create a workspace API key with amb:read, amb:write, and amb_management:read. Use Bash with curl, jq, and uuidgen. Run the following blocks in one Bash script or shell. The error settings stop the walkthrough if a request or validation fails. Keep credentials in your environment rather than source files:
set -euo pipefail
read -r -s -p "Bird API key: " BIRD_API_KEY
printf '\n'
export BIRD_API_KEY
case "$BIRD_API_KEY" in
bk_eu1_*) BIRD_API_URL=https://eu1.platform.bird.com ;;
bk_us1_*) BIRD_API_URL=https://us1.platform.bird.com ;;
*) printf 'Use a workspace key for a supported region.\n' >&2; exit 1 ;;
esacThe key supplies the workspace context. See regions if you receive a region mismatch.
Select the business and conversation
List businesses and conversations:
curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/business-accounts" \
-H "Authorization: Bearer $BIRD_API_KEY" | jq .
curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/conversations" \
-H "Authorization: Bearer $BIRD_API_KEY" | jq .
read -r -p "Bird business record ID: " BUSINESS_ID
read -r -p "Bird conversation record ID: " CONVERSATION_ID
BUSINESS=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/business-accounts/$BUSINESS_ID" \
-H "Authorization: Bearer $BIRD_API_KEY")
CONVERSATION=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/conversations/$CONVERSATION_ID" \
-H "Authorization: Bearer $BIRD_API_KEY")
printf '%s' "$BUSINESS" | jq -e '.status == "pending" or .status == "active"'
printf '%s' "$CONVERSATION" | jq -e --arg business "$BUSINESS_ID" \
'.status == "open" and .business_account_id == $business'This example is for an authorized test conversation; Testing status does not authorize public launch. Stop if either check returns false or a request fails. Select records from the same business. For more results, follow cursor pagination; a first page is not the complete inventory.
Review and send the reply
Build the request using apple_business_id as from and opaque_user_id as to:
APPLE_BUSINESS_ID=$(printf '%s' "$BUSINESS" | jq -er '.apple_business_id')
OPAQUE_USER_ID=$(printf '%s' "$CONVERSATION" | jq -er '.opaque_user_id')
REQUEST=$(jq -n --arg from "$APPLE_BUSINESS_ID" --arg to "$OPAQUE_USER_ID" \
'{from:$from,to:$to,text:{body:"We can help arrange your visit. Which day works for you?"}}')
printf '%s\n' "$REQUEST" | jq .Review the business, recipient, and text. The next request queues a real, potentially billable message:
REQUEST_ID=$(uuidgen)
RESPONSE=$(curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $REQUEST_ID" \
--data "$REQUEST")
printf '%s\n' "$RESPONSE" | jq .
MESSAGE_ID=$(printf '%s' "$RESPONSE" | jq -er '.id')A 202 response confirms acceptance for asynchronous processing. Retain REQUEST_ID and the unchanged body when retrying that logical request; generating another key can create another message. See idempotency.
Inspect processing and receive replies
Use Get message and List message events:
curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages/$MESSAGE_ID" \
-H "Authorization: Bearer $BIRD_API_KEY" | jq .
curl --fail-with-body -sS "$BIRD_API_URL/v1/amb/messages/$MESSAGE_ID/events" \
-H "Authorization: Bearer $BIRD_API_KEY" | jq .For asynchronous updates, configure webhooks for amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received, and the required conversation lifecycle events: amb.conversation_started, amb.conversation_closed, and amb.conversation_reopened. Verify signatures, deduplicate webhook deliveries, and tolerate out-of-order events. Fetch the message when reconciling an uncertain state.
parts lists the parts Bird sent an outbound message as, in order. Bird sets it when the send finishes as sent or send_failed. Get message, List messages, List conversation messages, and the amb.sent and amb.send_failed webhooks return it. A text with one link, sent with a quick reply, records four parts:
{
"parts": [
{ "kind": "text", "body": "Details at", "sent": true },
{
"kind": "link_preview",
"url": "https://example.com",
"title": "Compare plans",
"image_url": "https://example.com/images/plans.png",
"layout": "large",
"sent": true
},
{ "kind": "text", "body": "before you choose.", "sent": true },
{ "kind": "interactive", "sent": true }
]
}kind says what the part was. Tolerate values outside this list, because Bird can add kinds:
text: has itsbody, andattachmentsas positions in the message'stext.attachments.link_preview: a link from the text, which Bird sends as its own rich link card. It has theurl, thetitleandimage_urlBird read from the page when it sent the part, and the card'slayout.rich_link: the message's ownrich_link. Read the card's content there. The part adds the card'slayout. When the message'srich_linkhasrich_link_construct, as with a Location template, Apple builds the card. The part then has atitleand animage_urland nolayout: the title Apple returned for the card, or the linked page's title when Apple returned none, and the image that page offers. Either can be absent.interactive: the message's owninteractive.
The part that had the message's subject also has subject. A message can also go out as one rich_link or interactive part, which then has any text the message had in its own body and attachments.
sent is true when Bird saw Apple accept the part. It is not a device delivery or read receipt. After a failed send, the failed part and the parts after it are false. A false part may still have arrived, so do not resend on sent alone.
layout is the layout Apple's sizing rules give the image Bird sent: icon, square, or large. Bird cuts a title longer than 512 bytes to that length and leaves out an image_url longer than 2,048 bytes. image_url is the page's own image address, and Bird keeps no copy of the image it sent. The page can stop serving that address later. Apple builds a rich_link_construct card on the device, so the image there can differ from the page's, and the part has no layout, because Bird sends no image for it. title, image_url, and layout can be absent, for example when an earlier attempt of a retried send sent the part.
A message has no parts when it is a received or rejected message, or is still sending. An older message has none, and neither does a failed send where Bird could not split the text and sent nothing, such as a text with more than 20 links. Treat a missing parts as unknown. The Get message reference defines each field.
For amb.received, inspect the incoming content and match the conversation to your pending customer task. Process native answers using the sent identifiers where available; a time-picker reply can contain a selected label. Check the booking, order, or case system before taking an irreversible action or confirming its result.
Extend the message content
The Send message reference defines text, rich_link, and interactive content. Interactive messages include quick replies, lists, time pickers, forms, and custom iMessage apps. Bird sends each web address in text content as its own rich link. See which addresses become rich links. link_previews.layout sets how those previews show their image. Only a text sent on its own can set link_previews. Beside rich_link or interactive, Bird refuses it with 422. A rich_link image takes the same choice in rich_link.rich_link_data.assets.image.layout: use icon for a logo, so it appears small beside the title instead of as a full-width card. Use native-message design guidance for the customer experience.
To ask a customer to sign in with your identity provider, use customer sign-in. The send endpoint does not accept authentication content.
For Apple-generated previews, use the supported dashboard link workflow. Media source URLs are fetched during processing and can fail after acceptance; use the media requirements.
CLI or MCP installations that expose bird amb or the corresponding amb_* tools use the same addressing and status semantics. Check the installed command or tool schema before using it; this walkthrough depends directly on the public HTTP contract.
Resolve errors
A 404 can indicate an unknown conversation or the wrong workspace. A 403 requires the operation's scope. A closed conversation or unsupported native interaction can return 422; the customer must reopen a closed conversation.
Typing indicators use the amb_typing rate-limit policy; message submissions use amb_send. Their capacity is separate, so a typing indicator does not consume your message-sending capacity. Pace requests using the RateLimit-Policy and RateLimit response headers. For 429, follow Retry-After and the shared rate-limit guidance.
After acceptance, inspect message events and statuses for a processing or billing failure. Sent is Apple gateway acceptance; it does not provide a device-delivery or read receipt. Measure business outcomes separately.