waba-embedded-signup

WABA 入驻和嵌入式注册

请区分三种集成路径。把它们都称为“嵌入式注册”会导致错误的 API 设计和不安全的凭据处理。

三种路径

路径	起始位置	配置文件行为
组织嵌入式注册	Sent 控制面板	通过 Meta 托管流程连接组织的 WABA。Sent 没有用于启动此流程的公开端点。
组织 WABA 继承	POST /v3/profiles	省略 whatsapp_business_account；子级会继承组织已连接的 WABA。
子配置文件专用 WABA	POST /v3/profiles	提供 whatsapp_business_account.waba_id 和 .access_token；phone_number_id 为可选项。

如果省略凭据且组织没有已连接的 WABA，创建配置文件会返回 422。直接提供 WABA 凭据是配置文件创建功能，不是公开的“嵌入式注册端点”。

身份验证

使用以下任一方式：

• 在 x-api-key 中使用配置文件专属密钥；或
• 在 x-api-key 中使用组织密钥，并在为现有子配置文件操作时提供 x-profile-id。

只有组织密钥可以使用 x-profile-id；配置文件密钥会收到 403。x-sender-id 是 v1/v2 中使用的旧术语。

路径 A：组织嵌入式注册

1. 获授权的组织管理员打开 Sent 控制面板中的 WhatsApp 连接流程。
2. 托管的 Meta 嵌入式注册界面会收集 Meta 授权信息以及 WABA/号码选项。
3. 创建继承组织 WABA 的子配置文件之前，确认组织显示已连接 WABA。
4. 记录非机密标识符，并审计完成操作的人员。

不要在 Sent 的公开 API 中虚构 POST /embedded-signup 或令牌交换端点。如果要在 Sent 控制面板之外构建自己的 Meta 技术服务提供商集成，请遵循 Meta 当前的文档，并将该系统与 Sent API 契约分开。

Meta 浏览器 postMessage 事件使用 event 字段以及嵌套的数据/会话信息。不要将它们改写为 Sent webhook 的 sub_type 信封。

路径 B：继承组织 WABA

省略 whatsapp_business_account：

{
  "name": "Tenant Support",
  "description": "Synthetic child profile",
  "short_name": "SUPPORT",
  "inherit_templates": true,
  "billing_model": "organization",
  "sandbox": true
}

仅在组织 WABA 已连接后使用此方式。继承意味着租户共享该 WABA 边界；请确认这与租户/品牌架构相符。

路径 C：专用 WABA 凭据

{
  "name": "Dedicated Tenant",
  "whatsapp_business_account": {
    "waba_id": "123456789012345",
    "phone_number_id": "987654321098765",
    "access_token": "<injected secret>"
  },
  "sandbox": true
}

waba_id 和 access_token 为必填项。phone_number_id 为可选项：省略时，当前契约描述了入驻期间的配置和注册流程。

令牌需要具备适用的 WhatsApp Business 消息发送和管理权限。请从密钥管理器注入令牌。切勿记录令牌、回显令牌、将其写入测试固件、返回给浏览器、包含在支持输出中，或将其保留在通用配置文件存储中。Sent 不会在 API 响应中返回令牌。

完成配置文件

使用必需的 webHookUrl 调用 POST /v3/profiles/{profileId}/complete：

{
  "webHookUrl": "https://example.com/webhooks/profile-complete",
  "sandbox": true
}

• 202 表示后台处理已启动；该响应中没有最终状态。
• 200 可能表示配置文件已完成，并且当前示例使用小写的 completed。
• 完成回调可能报告 COMPLETED、SUBMITTED 或 failed。

请将完成回调视为独立的集成接口。其信封使用 event，而非 sub_type：

{
  "event": "COMPLETED",
  "profile_id": "00000000-0000-0000-0000-000000000000",
  "timestamp": "2026-08-09T12:00:00Z"
}

保留未知的事件字符串。使用 Sent 为回调端点指定的机制验证真实性，并确保处理具有幂等性。

验证运行就绪状态

• Profile WABA ID 与预期业务一致。
• 所选号码映射到预期 Profile。
• 模板共享／继承方式符合预期。
• 可以使用 sandbox: true 创建测试模板。
• 完成回调可访问且具备幂等性。
• 返回的消息 ID 会在 Webhook 处理前，按租户／Profile 存储。
• 日志中不包含令牌和付款值。

对于普通消息和模板 Webhook，请遵循 Sent 当前的事件参考文档；这些事件与 Meta 浏览器事件和 Profile 完成回调彼此独立。

故障路由

故障	后续操作
未提供凭据时出现 422	连接组织 WABA，或提供专用凭据。
使用 Profile 密钥和 x-profile-id 时出现 403	移除 x-profile-id，或使用已授权的组织密钥。
WABA／号码错误	在完成前停止操作，并修正 Profile 映射。
令牌已过期／权限范围不足	安全地替换令牌；排查问题时切勿打印令牌。
完成状态仍为已提交	检查前置条件和回调证据；不要仅凭 202 就认定最终失败。

请使用 references/waba-embedded-signup-spec.md、references/waba-onboarding-runbook.md 和 references/whatsapp-sender-profile-mapping.md。使用 sender-profile-architect 处理租户边界，使用 waba-template-author 创建第一个模板。