# 回复 Apple Messages 对话

向已发起 Apple Messages for Business 对话的客户发送文本回复，然后检查消息结果。

## 前提条件

您的工作区需要一个活跃的 Apple 商业帐户以及一个由客户发起的已打开对话。支持 AMB 的 CLI 和 SDK 包尚未发布。这些命令需要包含 `bird amb` 的构建版本；继续之前请检查 `bird amb --help`。在包含这些命令的包发布之前，请使用 [API 参考文档](/docs/api/reference/create-amb-message)或 Apple Messages 控制台。请对托管您工作区的区域进行身份验证。

使用安装了 `jq` 和 `uuidgen` 的 Bash。为该工作区验证 CLI。您的凭据需要 `amb:read` 来检查对话和消息，需要 `amb:write` 来发送，以及需要 `amb_management:read` 来检查商业帐户。使用一个已有的测试对话，并确保您有权联系其接收方。

## 1. 选择商家和对话

```sh
bird amb business-accounts list
bird amb conversations list
```

在提示处，粘贴您从这些列表中选择的记录 ID：

```sh
read -r -p "Business record ID: " BUSINESS_ID
read -r -p "Conversation record ID: " CONVERSATION_ID
bird amb business-accounts get "$BUSINESS_ID"
bird amb conversations get "$CONVERSATION_ID"
```

验证帐户是否活跃、对话是否已打开，以及其 `business_account_id` 是否与所选记录匹配。提取发送请求所需的 Apple 标识符：

```sh
APPLE_BUSINESS_ID=$(bird amb business-accounts 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')
```

电话号码无法替代不透明的客户标识符用于普通回复。

## 2. 预览回复

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

该命令仅打印请求而不发送。检查商家、收件人和消息文本。要查看完整的请求结构，请运行 `bird amb send --example`。通过 `--body-file` 传入的 JSON 文件可以携带可选字段，例如类别、标签或语言区域。

## 3. 发送已审核的消息

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

该命令会生成一个请求标识符，并将响应 ID 保存到 `MESSAGE_ID`。发送会将一条计费消息加入队列进行异步处理。如果需要重试，请复用 `REQUEST_ID`；不要为同一请求再次运行 `uuidgen`。

## 4. 检查处理结果

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

`sent` 记录的是 Apple 网关的接受状态，并不能证明消息已送达设备或客户已阅读。发送失败或结果不确定时，需要先排查原因再提交下一条消息。您的预订、订单或其他业务操作必须等待其自身的确认结果。

如需异步更新，请通过 [webhooks](/docs/guides/webhooks) 订阅 `amb.accepted`、`amb.sent`、`amb.send_failed`、`amb.rejected`、`amb.received` 或会话生命周期事件。验证签名并按 webhook ID 去重。事件可能乱序到达。

## 使用 MCP 完成相同的交互

MCP 提供相应的工具：`amb_business_accounts_list`、`amb_business_accounts_get`、`amb_conversations_list`、`amb_conversations_get`、`amb_send`、`amb_get` 和 `amb_list_events`。向 `amb_send` 传入相同的 `from`、`to` 和 `content` 对象，重试请求时还需加上 `idempotency_key`。在授权工具调用之前，请核实接收方和内容是否正确。

如果工具不存在，请检查服务器版本以及连接所授予的权限范围。

## 请求限制

Apple Messages 默认为每个组织每分钟 10 个请求。回复、输入指示器和附件准备在同一区域内的所有工作区和凭据之间共享该配额。您的方案或经批准的客户限额可以提高该值；如需增加请联系支持团队。请联系组织管理员或支持团队确认您的实际限额。当请求返回 `429` 时，请等待 `Retry-After` 间隔后再重试。

## 故障排查

如果渠道返回未找到响应，请检查该资源是否属于已验证的工作区。如果权限被拒绝，请检查凭据的渠道作用域。商业帐户必须处于活跃状态且对话已打开，才能接收回复；抑制规则也可能阻止发送。

如果处理环节拒绝了已接受的请求，请检查其事件和计费配置。发送的网关结果与客户的业务结果是分开的。不要从成功的 API 响应推断消息已送达。

## 后续步骤

阅读 [Apple Messages 集成指南](/docs/guides/apple-messages/api)了解原生消息交换和异步业务结果，或阅读[注册指南](/docs/guides/apple-messages/registration)以准备另一个商家。

## 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)