在 Sent 上接入 WhatsApp Business…

用于 Sent 中 WABA 连接、Meta Embedded Signup、子 profile 继承或专用凭据、号码映射、完成回调与 onboarding 故障排查。

适用场景

解决思路

1. 保持三条集成路径彼此独立：组织 Embedded Signup、组织 WABA 继承、专用子 profile WABA；不要把它们都称为 Embedded Signup，否则会导致错误 API 设计和不安全凭据处理。
2. 路径 1 组织 Embedded Signup 从 Sent dashboard 开始：它通过托管 Meta 流程连接组织 WABA；没有公开的 Sent endpoint 可启动该流程。
3. 路径 2 组织 WABA 继承通过 POST /v3/profiles 开始：省略 whatsapp_business_account，子 profile 继承组织已连接的 WABA。
4. 路径 3 专用子 profile WABA 通过 POST /v3/profiles 开始：提供 whatsapp_business_account.waba_id 和 whatsapp_business_account.access_token；phone_number_id 可选。
5. 如果省略凭据且组织没有已连接 WABA，profile 创建返回 422；直接 WABA 凭据是 profile-creation 功能，不是公开的 Embedded Signup endpoint。
6. 认证使用任一方式：在 x-api-key 中放 profile-specific key；或为已有子 profile 操作时，在 x-api-key 中放 organization key 并加 x-profile-id。
7. 只有 organization key 可使用 x-profile-id；profile key 会收到 403；x-sender-id 是 legacy v1/v2 术语。
8. 执行路径 A 第 1 步：授权组织管理员打开 Sent dashboard 的 WhatsApp connection flow。
9. 执行路径 A 第 2 步：托管 Meta Embedded Signup UI 收集 Meta 授权以及 WABA/number 选择。
10. 执行路径 A 第 3 步：在创建继承型子 profile 前，确认组织已显示 connected WABA。
11. 执行路径 A 第 4 步：记录非 secret identifiers，并审计是谁完成了该操作。
12. 不要虚构 POST /embedded-signup 或 token-exchange endpoint 作为 Sent 公共 API。
13. 如果要在 Sent dashboard 之外构建自己的 Meta Tech Provider integration，遵循 Meta 当前文档，并保持该系统与 Sent API contract 分离。
14. Meta 浏览器 postMessage events 使用 event 字段以及嵌套的 data/session 信息；不要把它们改写为 Sent webhook 的 sub_type envelopes。
15. 执行路径 B：在 POST /v3/profiles 中省略 whatsapp_business_account；请求体可使用 name、description、short_name、inherit_templates、billing_model、sandbox 等字段。
16. 仅在组织 WABA 已连接后使用路径 B；继承意味着租户共享该 WABA boundary，需确认这符合租户/品牌架构。
17. 执行路径 C：在 POST /v3/profiles 中提供 whatsapp_business_account 对象，包含 waba_id 和 access_token，可选 phone_number_id；请求体还可包含 name、sandbox 等字段。
18. 路径 C 中 waba_id 和 access_token 必填；phone_number_id 可选：省略时，当前 contract 描述为在 onboarding 期间进行 provisioning 和 registration。
19. 路径 C 的 token 需要适用的 WhatsApp Business messaging 和 management permissions。
20. 从 secret manager 注入 token；绝不 log、echo、写入 fixtures、返回给浏览器、包含在 support output、或保留在一般 profile storage 中；Sent 不会在 API 响应中返回该 token。
21. 完成 profile：调用 POST /v3/profiles/{profileId}/complete，并提供必填字段 webHookUrl；请求体可包含 webHookUrl 和 sandbox。
22. 理解完成响应：202 表示后台处理已开始，该响应中没有最终状态；200 可能表示 profile 已经 complete，并且当前表现为小写 completed。
23. 完成回调可报告 COMPLETED、SUBMITTED 或 failed。
24. 把完成回调视为独立 integration surface；其 envelope 使用 event，而不是 sub_type，字段可包含 event、profile_id、timestamp。
25. 保留未知 event strings；使用 Sent 为 callback endpoint 文档化的机制验证真实性，并使处理具备 idempotent。
26. 验证运行就绪：确认 profile WABA ID 匹配预期业务。
27. 验证运行就绪：确认所选 number 映射到预期 profile。
28. 验证运行就绪：确认 template sharing/inheritance 是有意为之。
29. 验证运行就绪：确认可用 sandbox: true 创建 test template。
30. 验证运行就绪：确认 completion callback 可到达且 idempotent。
31. 验证运行就绪：在 webhook 处理前，将返回的 message IDs 存储到对应 tenant/profile。
32. 验证运行就绪：确认 logs 中不存在 tokens 和 payment values。
33. 对于普通 message 和 template webhooks，遵循 Sent 当前 events reference；它们与 Meta browser events 和 profile-completion callbacks 不同。
34. 故障路由：凭据省略导致 422 时，连接组织 WABA 或提供专用凭据。
35. 故障路由：profile key 加 x-profile-id 导致 403 时，移除 x-profile-id 或使用已授权的 organization key。
36. 故障路由：WABA/number 错误时，在 completion 前停止并更正 profile mapping。
37. 故障路由：token 过期或 scope 不足时，安全替换它；诊断时绝不打印它。
38. 故障路由：completion 仍为 submitted 时，检查 prerequisite 和 callback evidence；不要从 202 假定最终失败。
39. 参考 references/waba-embedded-signup-spec.md、references/waba-onboarding-runbook.md、references/whatsapp-sender-profile-mapping.md。
40. 使用 sender-profile-architect 处理 tenant boundaries，使用 waba-template-author 处理第一个 template。

适用边界 · 注意事项

• 不适用于未使用 Sent 平台或不需要 Meta/WhatsApp Business WABA 接入的场景。
• 不适用于自建 Meta Tech Provider integration；应遵循 Meta 当前文档，并保持与 Sent API contract 分离。
• 不适用于普通 message/template webhooks 或 Meta 浏览器 postMessage events；应分别按 Sent events reference 或 Meta 文档处理。