Reply to an Apple Messages conversation

Send a text reply to a customer who has opened an Apple Messages for Business conversation, then inspect the message outcome.

Prerequisites

Your workspace needs an approved Apple business and an open conversation started by its customer. CLI and SDK packages with AMB support are awaiting publication. These commands require a build that includes bird amb; check bird amb --help before continuing. Until a package with these commands is published, use the API reference or the Apple Messages dashboard. Authenticate for the region that hosts your workspace.

Use Bash with jq and uuidgen installed. Authenticate the CLI for that workspace. Your credential needs amb:read to inspect conversations and messages, amb:write to send and amb_management:read to inspect businesses. Use an existing test conversation with permission to contact its recipient.

1. Select the business and conversation

Codevoorbeeld

bird amb businesses list
bird amb conversations list

At the prompts, paste the record IDs you selected from those lists:

Codevoorbeeld

read -r -p "Business record ID: " BUSINESS_ID
read -r -p "Conversation record ID: " CONVERSATION_ID
bird amb businesses get "$BUSINESS_ID"
bird amb conversations get "$CONVERSATION_ID"

Verify that the business is approved, the conversation is open, and its business matches the selected record. Extract the Apple identifiers the send request uses:

Codevoorbeeld

APPLE_BUSINESS_ID=$(bird amb businesses get "$BUSINESS_ID" --format json | jq -er '.apple_business_id')
OPAQUE_USER_ID=$(bird amb conversations get "$CONVERSATION_ID" --format json | jq -er '.opaque_user_id')

A phone number cannot replace the opaque customer identifier for an ordinary reply.

2. Preview the reply

Codevoorbeeld

bird amb send --from "$APPLE_BUSINESS_ID" --to "$OPAQUE_USER_ID" \
  --content '{"type":"text","body":"Your order is ready."}' --dry-run

The command prints the request without sending it. Check the business, recipient and message text. To inspect the complete request shape, run bird amb send --example. A JSON file passed through --body-file can carry optional fields such as category, tags or locale.

3. Send the reviewed message

Codevoorbeeld

REQUEST_ID=$(uuidgen)
MESSAGE_ID=$(bird amb send --from "$APPLE_BUSINESS_ID" --to "$OPAQUE_USER_ID" \
  --content '{"type":"text","body":"Your order is ready."}' \
  --idempotency-key "$REQUEST_ID" --format json | jq -er '.id')
printf '%s\n' "$MESSAGE_ID"

The command generates a request identifier and saves the response ID in MESSAGE_ID. Sending queues a billable message for asynchronous processing. If you retry, reuse REQUEST_ID; do not run uuidgen again for that request.

4. Inspect the outcome

Codevoorbeeld

bird amb get "$MESSAGE_ID"
bird amb list-events "$MESSAGE_ID"

sent records acceptance by Apple's gateway. It does not establish device delivery or that the customer read the message. A failed or uncertain send needs investigation before another message is submitted. Your booking, order or other business action must wait for its own confirmed outcome.

For asynchronous updates, subscribe through webhooks to amb.accepted, amb.sent, amb.send_failed, amb.rejected, amb.received, or the conversation lifecycle events. Verify signatures and deduplicate deliveries by webhook ID. Events can arrive out of order.

Use MCP for the same exchange

MCP exposes the corresponding tools: amb_businesses_list, amb_businesses_get, amb_conversations_list, amb_conversations_get, amb_send, amb_get, and amb_list_events. Give amb_send the same from, to, and content object, plus idempotency_key when retrying a request. Review the exact recipient and content before authorizing the tool call.

If a tool is absent, check the server version and the scopes granted to your connection.

Request limits

Apple Messages defaults to 10 requests per minute per organization. Replies, typing indicators and attachment preparation share that allowance across your workspaces and credentials in a region. Your plan or an approved customer limit can raise it; contact support for an increase. Ask your organization administrator or support to confirm your effective limit. When a request returns 429, wait for the Retry-After interval before retrying.

Troubleshooting

If the channel returns a not-found response, check whether the resource belongs to the authenticated workspace. For a permission refusal, check the credential's channel scope. A business must be approved and the conversation open before it can receive a reply; suppressions can also block sending.

If processing rejects an accepted request, inspect its events and billing configuration. A send's gateway outcome and its customer's business outcome are separate. Do not infer delivery from a successful API response.

Next steps

Read the Apple Messages integration guide for native exchanges and asynchronous business outcomes, or registration guidance to prepare another business.

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsWebhooks done right: reliable delivery events Begrijp het conceptHow do I verify a webhook signature?Ontdek de mogelijkheidApple Messages for Business Volg het leerpadOperate messaging reliably

Probeer de oefening en ontvang een implementatieoverzicht