Sign inGet Started

通过 Apple Messages API 回复

使用公共 Bird API 向已有的 Apple Messages 对话发送文本回复,然后检查处理状态并接收客户回复。

准备工作区和凭据

完成仪表板首次对话快速入门,连接商家并打开测试对话。草稿状态的商家可以在获批前发送测试消息。普通回复使用客户的 Apple 不透明标识符,不能用电话号码代替。

创建具有 amb:read、amb:write 和 amb_management:read 权限的工作区 API 密钥。使用 Bash 以及 curl、jq 和 uuidgen。在同一个 Bash 脚本或 shell 中运行以下代码块。请求或验证失败时,错误设置会停止此流程。请将凭据放在环境变量中,不要写入源文件:

代码示例
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 ;;
esac

密钥提供工作区上下文。如果出现区域不匹配,请参阅区域。

选择商家和对话

列出商家和对话:

代码示例
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'

本示例用于已授权的测试对话;草稿状态不代表可以公开上线。如果任一检查返回 false 或请求失败,请停止操作。选择属于同一商家的记录。如需更多结果,请按游标分页操作;第一页不是完整列表。

检查并发送回复

构建请求,将 apple_business_id 用作 from,将 opaque_user_id 用作 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,content:{type:"text",body:"We can help arrange your visit. Which day works for you?"}}')
printf '%s\n' "$REQUEST" | jq .

检查商家、接收者和文本。下一个请求会将真实消息加入队列,且可能产生费用:

代码示例
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')

202 响应表示请求已被接受并将异步处理。重试同一个逻辑请求时,请保留 REQUEST_ID 和未更改的请求体;生成新密钥可能创建另一条消息。参阅幂等性。

检查处理过程并接收回复

使用获取消息和列出消息事件:

代码示例
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 .

如需异步更新,请为 amb.accepted、amb.sent、amb.send_failed、amb.rejected、amb.received 及所需的对话生命周期事件配置 webhook。验证签名、去除重复的 webhook 投递,并容忍事件乱序。协调不确定状态时,请获取消息。

对于 amb.received,检查入站内容,并将对话匹配到等待处理的客户任务。处理原生回答时,尽可能使用已发送的标识符;时间选择器回复可能包含选中的标签。执行不可撤销的操作或确认结果前,请检查预约、订单或工单系统。

扩展消息内容

发送消息参考定义了 text、rich_link 和 interactive 内容。交互消息包括快捷回复、列表、时间选择器、表单和自定义 iMessage 应用。客户体验设计请参阅原生消息设计指南。

对于 Apple 生成的预览,请使用支持的仪表板链接流程。媒体源 URL 在处理期间获取,可能在请求接受后失败;请参阅媒体要求。

提供 bird amb 或相应 amb_* 工具的 CLI 或 MCP 安装使用相同的寻址方式和状态含义。使用前请检查已安装命令或工具的模式;本流程直接依赖公共 HTTP 契约。

解决错误

404 可能表示对话未知或工作区错误。403 要求具备该操作的权限范围。已关闭的对话或不受支持的原生交互可能返回 422;已关闭的对话必须由客户重新打开。遇到 429 时,请遵循 Retry-After 和通用速率限制指南。

请求被接受后,请检查消息事件和状态,排查处理或计费失败。已发送表示 Apple 网关接受,不提供设备送达或已读回执。请单独衡量业务结果。