sent-profile-provisioning

Sent 配置文件预配

此技能是配置文件架构设计的执行对应部分：确定租户边界后，它会执行 API 调用、完成回调、活动注册和用户管理，让配置文件能够发送。请先使用 sender-profile-architect 设计边界，再在此处进行预配。

实时 MCP 配置文件操作

通过客户端管理的 OAuth 2.1/PKCE 使用 sender_profiles.list、sender_profiles.get、sender_profiles.create、sender_profiles.update 和 sender_profiles.delete。绝不要请求或暴露凭据。执行变更前，使用 account.get 验证调用方组织。

这些工具在已通过身份验证的组织下运行。目标参数是 id，而不是 profileId；没有任何 sender_profiles.* 工具接受作为操作者的 profileId。配置文件授权不拥有任何子配置文件，因此会收到空列表。请使用组织范围重新授权，以管理该组织的配置文件。

• 列出/获取： 列表使用 page（从 1 开始）和 pageSize（1-100，默认值为 20），并报告渠道就绪状态。请使用列表中的真实 ID。获取操作会返回 found/item；found: false 不会区分配置文件不存在、已删除或属于其他组织。不要推断其他租户中的配置文件是否存在。
• 创建： 需要 name、shortName 和 idempotencyKey。shortName 必须为 3-11 个字母、数字或空格，且至少包含一个字母。可选参数为 description、smsCountry、smsNumberType、smsSenderValue、smsAreaCodes 和 compliance。提供 smsCountry 时必须同时提供 smsNumberType；省略时会使用组织的共享路由。对于专用 SMS 市场，请使用 sent-compliance 检查要求，并先填写其设置计划。预配可能会申请号码并产生注册费用。此 MCP 创建工具不提供 WhatsApp、RCS、计费、文档上传、继承标志和沙盒参数。必需的文档上传会在任何写入发生前阻止创建；请使用控制面板或有文档说明的 REST 流程。不会返回一次性 API 密钥。
• 更新： 获取确切目标，然后提供 id 和 name、shortName、description 中发生变更的字段。省略的字段保持不变；显式设置 description: null 会清除描述。名称和短名称不能清空。必须至少提供一个字段。不要将省略的字段填为 null，也不要假定此操作会更新渠道配置。
• 删除： 获取并预览目标。说明删除可能会断开 WhatsApp 连接、释放号码并禁用实时路由。提供 id 和非空的 idempotencyKey。deleted: false 表示没有删除任何匹配的自有配置文件，但不能证明其他租户的配置文件存在。

每次创建、更新或删除操作前，都要预览组织、确切目标或载荷及副作用，然后在调用前立即要求明确确认。变更会使确认失效。每次重试都需要新的预览和确认。

创建和删除使用持久化回执。对于同一预期操作，请重复使用原始密钥和参数；超时或操作仍在进行时，不要生成新密钥。先检查列表/获取结果以及返回的回执指引。将密钥用于不同参数时会被拒绝。如果中断的预配或拆除需要处理，请停止操作并在控制面板中核对，而不要自动重试或更换密钥。只有在核对完现有结果后，新密钥才可授权单独的操作。请验证返回的配置文件及渠道就绪状态；仅创建配置文件并不能获得发送权限。

MCP 不提供配置文件完成、活动管理、用户管理或市场添加工具。对于这些任务，请使用控制面板或单独记录的 REST 工作流；不要虚构工具。

更广泛的 REST 工作流

以下 /v3/profiles 指南描述的是旧版 REST 生命周期及其回调，并非 sender_profiles.* 的参数。对于新的 REST 配置文件创建，请查阅当前 /v3/sender-profiles API 参考；切勿将路径、snake_case REST 字段或旧版完成语义机械地替换到 MCP 调用中。

配置流程

1. 确认凭据。 POST /v3/profiles 需要具有 admin 权限的组织密钥。配置文件级密钥无法创建配置文件；携带 x-profile-id 的配置文件密钥会收到 403。
2. 在调用前决定继承和共享设置。 这些标志会影响合规状况，之后也很难撤销。
3. 创建配置文件，如果不确定请求数据的格式，可先使用 "sandbox": true 验证。正式创建时请使用不同的幂等键，因为成功的沙盒响应会缓存 24 小时。
4. 通过恰好一种受支持的路径附加或继承 WhatsApp。
5. 在配置文件下注册用于美国 SMS 的活动。
6. 使用 POST /v3/profiles/{profileId}/complete 完成配置文件，并提供可访问的 webHookUrl。
7. 从回调中核对状态；如果错过回调，则通过轮询核对。
8. 以最小权限角色邀请用户。

创建请求数据要点

name 是唯一必填字段。影响较大的可选字段分为身份信息、共享、继承、计费、WhatsApp 和品牌几类。

{
  "name": "Northwind Retail",
  "short_name": "Northwind",
  "description": "Retail brand tenant",
  "allow_contact_sharing": false,
  "allow_template_sharing": false,
  "inherit_contacts": false,
  "inherit_templates": false,
  "inherit_tcr_brand": true,
  "inherit_tcr_campaign": true,
  "billing_model": "profile",
  "billing_contact": {
    "name": "Ada Ops",
    "email": "[email protected]",
    "phone": "+14155550100",
    "address": "1 Example Way, Springfield"
  },
  "sandbox": true
}

short_name 必须为 3 到 11 个字符，由字母、数字和空格组成，且至少包含一个字母。继承标志默认值为 true，因此不设置标志创建的配置文件会使用组织的联系人、模板、品牌和活动。此示例明确选择隔离联系人和模板，同时继承组织的合规注册信息。共享标志用于向外开放此配置文件的资源；继承标志用于从组织向内使用资源。二者方向独立，常常被混淆。

创建时只需提供 name，但完成配置文件还需要 short_name、description、配置文件 KYC 信息，以及所需的活动或渠道设置。当 inherit_tcr_brand 为 true 时，即使配置文件仍需提交自己的 KYC 信息，API 也会拒绝创建请求中的 brand 对象；请在调用完成端点前，通过控制面板完成该 KYC。

billing_model 可接受 profile、organization 或 profile_and_organization。任何包含 profile 的模式在尚无账单联系人时都需要提供 billing_contact，且只有这些模式才接受 payment_details。卡片字段会转发给支付处理商，绝不可在应用的任何位置记录、回显或持久化。

字段规则、错误代码和仅限更新的字段，详见 references/profile-lifecycle.md。

继承决策

标志	true 表示	后果
inherit_tcr_brand	使用组织已注册的品牌	同一请求中的 brand 对象会被拒绝
inherit_tcr_campaign	使用组织的活动	这些活动对此配置文件只读；创建活动会返回验证错误
inherit_contacts	读取组织的联系人	不同租户之间的联系人不隔离
inherit_templates	读取组织的模板	不同租户之间的模板不隔离

继承品牌但设置 inherit_tcr_campaign: false 是一种受支持且常见的模式：共享法定身份，为每个租户配置专属的消息用途。

WhatsApp：恰好有三种路径

1. 在 Sent Dashboard 中执行组织嵌入式注册。没有任何公共端点会启动此流程。
2. 子配置文件继承 — 组织拥有 WABA 后，省略 whatsapp_business_account。
3. 专用配置文件凭据 — 提供包含 waba_id 和 access_token 的 whatsapp_business_account，也可以选择提供 phone_number_id。

在 POST /v3/profiles 中提供凭据并不是嵌入式注册端点。如果组织未配置 WABA，省略 whatsapp_business_account 会返回 422；请完成组织嵌入式注册，或提供有效的直接凭据。使用 waba-embedded-signup 执行实际注册流程。

完成与状态

POST /v3/profiles/{profileId}/complete 要求提供 webHookUrl。

{
  "webHookUrl": "https://provisioning.example.com/callbacks/profile-complete",
  "sandbox": false
}

202 表示处理已开始，不包含最终状态。200 表示配置文件已完成，其响应正文包含状态。回调正文为 {profileId, success, status, timestamp}，且仅发送一次，不会重试，因此调用前接收端必须处于运行状态，并且流程必须能够降级为轮询 GET /v3/profiles/{profileId}。此回调与已订阅的 Sent webhook 分开，文档未说明它会携带 webhook HMAC 标头；请使用与配置记录关联的唯一回调路径，拒绝未知的配置文件 ID，并将轮询作为权威恢复路径。

不同界面上的配置文件状态词汇各不相同：创建响应展示小写的 incomplete，完成操作的 200 响应展示小写的 completed，完成回调使用 COMPLETED、SUBMITTED 和 failed，而 GET /v3/profiles/{id} 文档中列出 approved、submitted、processing 和 failed。不要断言状态是封闭枚举，不要将状态统一转换为小写后与固定集合比对，并记录每个值来自哪个界面。比较状态时忽略大小写，并保留未知字符串。

每个配置文件的营销活动

营销活动管理位于配置文件下：GET|POST /v3/profiles/{profileId}/campaigns 和 PUT|DELETE /v3/profiles/{profileId}/campaigns/{campaignId}。没有独立的品牌端点；创建配置文件时会同时创建专用品牌。

{
  "campaign": {
    "name": "Northwind order notifications",
    "description": "Order and delivery notifications for opted-in Northwind customers.",
    "type": "App",
    "useCases": [
      {
        "messagingUseCaseUs": "ACCOUNT_NOTIFICATION",
        "sampleMessages": [
          "Northwind: Your order 12345 has shipped. Reply STOP to opt out."
        ]
      }
    ],
    "volume": "1500",
    "messageFlow": "Customers opt in at checkout before notifications begin.",
    "privacyPolicyLink": "https://example.com/privacy",
    "termsAndConditionsLink": "https://example.com/terms"
  }
}

messagingUseCaseUs 接受 13 个值之一，sampleMessages 包含 1 至 5 条内容，每条最多 1,024 个字符；数值字符串 volume 小于 2,000 时选择低流量级别，达到或超过 2,000 时选择标准级别。营销活动状态为 SENT_CREATED、ACTIVE 和 EXPIRED。使用 sms-10dlc-registration 选择用途并遵循示例文案政策。

用户与角色

有五种操作可用于管理访问权限：GET /v3/users、POST /v3/users（邀请）、GET /v3/users/{userId}、PATCH /v3/users/{userId}（角色）和 DELETE /v3/users/{userId}。MCP 不提供这些操作。可分配的角色为 admin、billing 和 developer；创建账户的用户隐式拥有 owner 角色，该角色不会出现在列表中。修改操作需要 admin 权限。

角色检查会根据拥有 API 密钥的电子邮件地址进行判定，仅在该用户是所有者或拥有允许角色的活跃用户时通过 — invited、suspended 和 rejected 用户均无法通过。组织级访问权限会级联到子配置文件。邀请会在 7 天后过期，邀请现有用户会返回 409。

执行任何用户修改操作前，请先读取当前状态，然后明确征得操作人员的确认。API 会拒绝更改你自己的角色、将最后一位管理员降级、移除自己或移除最后一位管理员，但提前检查可给出清晰说明，而不是返回验证错误。完整的角色矩阵和密钥卫生规则见 references/users-and-roles.md。

没有可用于列出、创建或撤销 API 密钥的端点；密钥管理需要在控制面板中进行。轮换密钥的流程是：创建新密钥、部署、使用 GET /v3/me 验证，然后停用或删除旧密钥 — 仅在密钥已泄露时才先删除旧密钥。

多租户配置说明

Webhook 事件不会携带应用的租户标识符。首次发送之前，请持久化 message_id -> {tenant, profile, logical_send_id, channel} 和 receiving_number -> {tenant, profile}。不要根据 account_id 推断租户归属，因为多个租户配置文件可能共用同一个组织。每个环境配置一个 webhook 注册，这样较低环境中的接收器发生故障时，不会自动停用生产环境。

边界

隔离、凭据和影响范围的设计决策使用 sender-profile-architect；WhatsApp 注册流程使用 waba-embedded-signup；品牌审核和营销活动政策使用 sms-10dlc-registration；订阅消息事件的接收器使用 sent-webhook-engineer。配置文件完善回调使用此技能中单独的验证和轮询指南。