通过 Sent API 完成 Sender Profile…

当需要通过 Sent API 创建和配置 Sender Profile（含继承/共享、计费、WhatsApp、10DLC 活动、完成回调与用户角色管理）时使用。

适用场景

解决思路

1. 确认凭证：POST /v3/profiles 需要具备 admin 权限的组织密钥；profile 级密钥无法创建 profile，且发送 x-profile-id 的 profile 密钥会收到 403。
2. 在调用前先决定继承与共享标志，这些标志决定合规姿态且事后难以撤销。
3. 创建 profile：当载荷结构不确定时，先用 "sandbox": true 校验载荷；正式创建时使用不同的幂等键，因为成功的 sandbox 响应会被缓存 24 小时。
4. 通过三种受支持路径中的恰好一种来附加或继承 WhatsApp。
5. 在 profile 下为美国 SMS 注册 campaigns。
6. 用 POST /v3/profiles/{profileId}/complete 和可访问的 webHookUrl 完成 profile。
7. 从回调中核对状态，若回调丢失则通过轮询核对。
8. 以最小权限角色邀请用户。
9. 创建载荷中 name 是唯一必填字段；其余重要可选字段分为身份、共享、继承、计费、WhatsApp 和品牌几组。
10. short_name 必须为 3 到 11 个字符，仅含字母、数字和空格，且至少包含一个字母。
11. 继承标志默认为 true，因此不带任何标志创建的 profile 会消耗组织的 contacts、templates、brand 和 campaigns；示例显式选择联系人和模板隔离，同时继承组织的合规注册。
12. 共享标志向外暴露本 profile 的资源；继承标志向内消耗组织的资源；两者是独立方向，常被混淆。
13. 创建时只允许 name，但完成时还需要 short_name、description、profile KYC 信息以及任何必需的 campaign 或渠道设置。
14. 当 inherit_tcr_brand 为 true 时，API 会拒绝创建请求中的 brand 对象，尽管 profile 仍需要自己的 KYC 提交；在调用完成端点前通过 dashboard 完成该 KYC。
15. billing_model 接受 profile、organization 或 profile_and_organization；任何包含 profile 的模型在不存在 billing_contact 时都需要 billing_contact，且 payment_details 仅在这些模型下被接受。
16. 卡字段会被转发给支付处理方，绝不能在任何应用位置记录、回显或持久化。
17. 继承决策：inherit_tcr_brand 为 true 表示使用组织注册的品牌，同一请求中的 brand 对象会被拒绝。
18. 继承决策：inherit_tcr_campaign 为 true 表示使用组织的 campaigns，这些 campaigns 对本 profile 只读，创建会返回校验错误。
19. 继承决策：inherit_contacts 为 true 表示可读取组织的 contacts，租户之间无联系人隔离。
20. 继承决策：inherit_templates 为 true 表示可读取组织的 templates，租户之间无模板隔离。
21. 继承品牌但 inherit_tcr_campaign: false 是受支持且常见的模式：共享法律身份，每个租户有专用消息用例。
22. WhatsApp 路径一：在 Sent Dashboard 中执行 Organization Embedded Signup；没有公开端点可启动此流程。
23. WhatsApp 路径二：子 profile 继承——组织已有 WABA 后省略 whatsapp_business_account。
24. WhatsApp 路径三：专用 profile 凭证——提供 whatsapp_business_account 及 waba_id 和 access_token，可选 phone_number_id。
25. 在 POST /v3/profiles 上提供凭证不是 Embedded Signup 端点；当组织未配置 WABA 时省略 whatsapp_business_account 会返回 422；需完成组织 Embedded Signup 或提供有效的直接凭证。
26. 完成与状态：POST /v3/profiles/{profileId}/complete 需要 webHookUrl。
27. 202 表示处理已开始且不携带最终状态；200 表示 profile 已完成且响应体携带状态。
28. 回调体为 {profileId, success, status, timestamp}，仅投递一次且不重试，因此接收方必须在调用前就绪，流程必须降级为轮询 GET /v3/profiles/{profileId}。
29. 该回调独立于订阅的 Sent webhooks，且未记录为携带 webhook HMAC 头；使用与配置记录绑定的唯一回调路径，拒绝未知 profile id，并将轮询视为权威恢复路径。
30. Profile 状态词汇因界面而异：创建响应示例为小写 incomplete，完成 200 示例为小写 completed，完成回调使用 COMPLETED、SUBMITTED 和 failed，GET /v3/profiles/{id} 记录 approved、submitted、processing 和 failed。
31. 不要断言封闭枚举，不要小写归一化为固定集合，并记录每个值来自哪个界面；以大小写不敏感方式比较状态并保留未知字符串。
32. Campaign 管理位于 profile 下：GET|POST /v3/profiles/{profileId}/campaigns 和 PUT|DELETE /v3/profiles/{profileId}/campaigns/{campaignId}；没有独立的 brand 端点，专用 brand 随 profile 一起创建。
33. Campaign 载荷中 messagingUseCaseUs 接受十三个值之一，sampleMessages 包含 1 到 5 条、每条最多 1,024 字符，数字 volume 字符串低于 2,000 选择低量层，2,000 及以上选择标准层；campaign 状态为 SENT_CREATED、ACTIVE 和 EXPIRED。
34. 用户与角色：五个操作管理访问权限——GET /v3/users、POST /v3/users（邀请）、GET /v3/users/{userId}、PATCH /v3/users/{userId}（角色）和 DELETE /v3/users/{userId}；这些均未通过 MCP 暴露。
35. 可分配角色为 admin、billing 和 developer；owner 对创建账户隐式存在且从不出现在列表中；变更操作需要 admin。
36. 角色检查针对拥有 API 密钥的邮箱解析，仅对所有者或具有允许角色的活跃用户通过——invited、suspended 和 rejected 用户会失败；组织级访问会级联到子 profile。
37. 邀请在七天后过期，邀请已存在用户会返回 409。
38. 在任何用户变更前，先读取当前状态，然后与操作者明确确认；API 拒绝更改自己的角色、降级最后一个 admin、移除自己或移除最后一个 admin，但先检查能产生清晰解释而非校验错误。
39. 没有端点可列出、创建或撤销 API 密钥；密钥管理是 dashboard 操作；轮换流程为创建新密钥、部署、用 GET /v3/me 验证，然后禁用或删除旧密钥——仅在密钥泄露时才先删除。
40. 多租户配置：webhook 事件从不携带应用的租户标识；在首次发送前，持久化 message_id -> {tenant, profile, logical_send_id, channel} 和 receiving_number -> {tenant, profile}。
41. 不要从 account_id 推断租户归属，因为许多租户 profile 可共享一个组织。
42. 每个环境配置一个 webhook 注册，以免失败的低环境接收方自动禁用生产。
43. 边界：隔离、凭证和爆炸半径设计决策使用 sender-profile-architect；WhatsApp 注册流程使用 waba-embedded-signup；品牌审核和 campaign 策略使用 sms-10dlc-registration；订阅消息事件接收方使用 sent-webhook-engineer；profile 完成回调使用本技能中独立的验证与轮询指南。

适用边界 · 注意事项

• 尚未决定租户边界/隔离设计时（应先用 sender-profile-architect 做设计决策）。
• 需要执行 WhatsApp Embedded Signup 操作流程时（应使用 waba-embedded-signup）。
• 需要品牌审核与 10DLC campaign 策略选择时（应使用 sms-10dlc-registration）。