# 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](/docs/api/reference/create-amb-message) 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

```sh
bird amb businesses list
bird amb conversations list
```

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

```sh
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:

```sh
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

```sh
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

```sh
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

```sh
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](/docs/guides/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](/docs/guides/apple-messages/api) for native exchanges and asynchronous business outcomes, or [registration guidance](/docs/guides/apple-messages/registration) to prepare another business.

## Related resources

- [Webhooks done right: reliable delivery events](/learn/basics/webhooks-done-right-reliable-delivery-events) (video)
- [How do I verify a webhook signature?](/explained/platform/how-do-i-verify-a-webhook-signature) (answer)
- [Apple Messages for Business](/apple-messages-api) (product)
- [Operate messaging reliably](/learn/paths/reliability) (course)

[Get an implementation brief](/learn/workspace?topic=webhooks)