用途:指导通过 Sent 完成 WhatsApp Business Account(WABA)接入,核心是把三条集成路径分清,避免都叫作“Embedded Signup”而导致错误的 API 设计与不安全的凭证处理。
主要能力与三条路径:一、组织 Embedded Signup,在 Sent 仪表板由组织管理员发起托管的 Meta 流程,公开 Sent API 中没有启动该流程的端点。二、组织 WABA 继承,调用 POST /v3/profiles 时省略 whatsapp_business_account,子配置文件继承组织已连接的 WABA。三、子配置文件专用 WABA,同样调用 POST /v3/profiles,提供 whatsapp_business_account.waba_id 与 .access_token,phone_number_id 可选;省略凭证且组织无已连接 WABA 时返回 422。
使用方式与限制:认证用 x-api-key 中的配置文件密钥,或组织密钥加 x-profile-id(仅组织密钥可用,配置文件密钥会得 403);x-sender-id 为 v1/v2 旧术语。完成配置文件需 POST /v3/profiles/{profileId}/complete 并带必填 webHookUrl;202 表示后台已开始处理,回调可报告 COMPLETED、SUBMITTED 或失败,回调信封用 event 而非 sub_type。access_token 应来自密钥管理器,不得记录、回显或返回浏览器。
验证要点:核对 WABA ID 与号码映射、模板共享意图、回调可达且幂等、返回的消息 ID 在 webhook 处理前已落库。失败路由涵盖 422、403、WABA/号码错误、令牌失效与 completion 仍为 submitted 的处理。详见 references/waba-embedded-signup-spec.md 等参考文件。