sent-profile-provisioning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sent Profile Provisioning

Sent配置文件预配

This skill is the execution counterpart to profile architecture: once the tenancy boundary is decided, it drives the API calls, the completion callback, the campaign registration, and the user administration that make a profile able to send. Design the boundary with

sender-profile-architect

first; provision it here.

本技能是配置文件架构的执行环节：一旦确定租户边界，它将驱动API调用、完成回调、活动注册以及用户管理操作，使配置文件具备发送能力。请先使用

sender-profile-architect

设计边界，再在此处进行预配。

Provisioning sequence

预配流程

Confirm the credential.
```
POST /v3/profiles
```
requires an organization key with
```
admin
```
. Profile-scoped keys cannot create profiles, and a profile key that sends
```
x-profile-id
```
receives
```
403
```
.
Decide inheritance and sharing before the call. These flags shape compliance posture and are awkward to unwind later.
Create the profile, validating the payload with
```
"sandbox": true
```
first when the shape is uncertain. Use a different idempotency key for the live create because a successful sandbox response is cached for 24 hours.
Attach or inherit WhatsApp via exactly one of the three supported paths.
Register campaigns for US SMS under the profile.

Complete the profile with

POST /v3/profiles/{profileId}/complete

and a reachable

webHookUrl

Reconcile status from the callback, or by polling if the callback is missed.
Invite users with least-privilege roles.

确认凭证。
```
POST /v3/profiles
```
接口需要具备
```
admin
```
权限的组织密钥。配置文件级别的密钥无法创建配置文件，携带
```
x-profile-id
```
的配置文件密钥会返回
```
403
```
错误。
调用前确定继承与共享设置。这些标志会影响合规状态，后续修改较为繁琐。
创建配置文件，当不确定请求体格式时，先使用
```
"sandbox": true
```
验证请求体。正式创建时需使用不同的幂等键，因为成功的沙箱响应会被缓存24小时。
通过以下三种支持路径之一关联或继承WhatsApp。
为配置文件下的美国短信注册活动。
调用
POST /v3/profiles/{profileId}/complete
完成配置文件，并提供可访问的
```
webHookUrl
```
。
通过回调协调状态，若错过回调则通过轮询获取。
邀请用户并分配最小权限角色。

Create payload essentials

创建请求体要点

name

is the only required field. The consequential optional fields group into identity, sharing, inheritance, billing, WhatsApp, and brand.

json

{
  "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": "ops@example.com",
    "phone": "+14155550100",
    "address": "1 Example Way, Springfield"
  },
  "sandbox": true
}

short_name

must be 3 to 11 characters of letters, numbers, and spaces with at least one letter. Inheritance flags default to true, so a profile created with no flags consumes the organization's contacts, templates, brand, and campaigns. The example opts into contact and template isolation explicitly while inheriting the organization's compliance registrations. Sharing flags expose this profile's resources outward; inheritance flags consume the organization's resources inward. They are independent directions and are frequently confused.

Create permits

name

alone, but completion also requires

short_name

description

, profile KYC information, and any required campaign or channel setup. When

inherit_tcr_brand

is true, the API rejects a

brand

object in the create request even though the profile still needs its own KYC submission; complete that KYC through the dashboard before calling the completion endpoint.

billing_model

accepts

profile

organization

, or

profile_and_organization

. Any model that includes

profile

requires

billing_contact

when none exists, and

payment_details

is only accepted for those models. Card fields are forwarded to the payment processor and must never be logged, echoed, or persisted anywhere in the application.

Field-by-field rules, error codes, and the update-only fields are in references/profile-lifecycle.md.

name

是唯一必填字段。重要的可选字段分为身份、共享、继承、计费、WhatsApp和品牌六大类。

json

{
  "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": "ops@example.com",
    "phone": "+14155550100",
    "address": "1 Example Way, Springfield"
  },
  "sandbox": true
}

short_name

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

创建配置文件时仅需提供

name

即可，但完成配置还需要

short_name

、

description

、配置文件KYC信息，以及任何必要的活动或渠道设置。当

inherit_tcr_brand

为true时，API会拒绝创建请求中的

brand

对象，尽管配置文件仍需提交自身的KYC信息；请在调用完成端点前通过控制台完成KYC提交。

billing_model

支持

profile

、

organization

或

profile_and_organization

。任何包含

profile

的计费模型在无计费联系人时需要提供

billing_contact

，且仅这些模型接受

payment_details

。卡片字段会转发至支付处理器，绝不能在应用中记录、回显或持久化存储。

字段规则、错误码以及仅支持更新的字段请参考references/profile-lifecycle.md。

Inheritance decisions

继承决策

Flag	`true` means	Consequence
`inherit_tcr_brand`	Use the organization's registered brand	A `brand` object in the same request is rejected
`inherit_tcr_campaign`	Use the organization's campaigns	Those campaigns are read-only for this profile; creating one returns a validation error
`inherit_contacts`	Read the organization's contacts	No contact isolation between tenants
`inherit_templates`	Read the organization's templates	No template isolation between tenants

An inherited brand with

inherit_tcr_campaign: false

is a supported and common pattern: shared legal identity, dedicated messaging use cases per tenant.

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

继承品牌且

inherit_tcr_campaign: false

是一种受支持的常见模式：共享法律身份，每个租户拥有独立的消息使用场景。

WhatsApp: exactly three paths

WhatsApp：三种路径可选

Organization Embedded Signup, performed in the Sent Dashboard. No public endpoint starts this flow.
Child-profile inheritance — omit
```
whatsapp_business_account
```
once the organization has a WABA.
Dedicated profile credentials — supply
```
whatsapp_business_account
```
with
```
waba_id
```
and
```
access_token
```
, optionally
```
phone_number_id
```
.

Supplying credentials on

POST /v3/profiles

is not an Embedded Signup endpoint. Omitting

whatsapp_business_account

when the organization has no WABA configured returns

; complete organization Embedded Signup or supply valid direct credentials. Use

waba-embedded-signup

for the operational signup flow.

组织嵌入式注册，在Sent控制台中执行。无公开端点可启动此流程。
子配置文件继承——组织已有WABA时，省略
```
whatsapp_business_account
```
字段。
专用配置文件凭证——提供包含
```
waba_id
```
和
```
access_token
```
的
```
whatsapp_business_account
```
，可选提供
```
phone_number_id
```
。

在

POST /v3/profiles

中提供凭证并非嵌入式注册端点。当组织未配置WABA时省略

whatsapp_business_account

会返回

错误；请完成组织嵌入式注册或提供有效的直接凭证。使用

waba-embedded-signup

处理操作注册流程。

Completion and status

完成与状态

POST /v3/profiles/{profileId}/complete

requires

webHookUrl

json

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

means processing started and carries no final status. A

means the profile was already complete and its body carries a status. The callback body is

{profileId, success, status, timestamp}

and is delivered once with no retry, so the receiver must be live before the call and the flow must degrade to polling

GET /v3/profiles/{profileId}

. This callback is separate from subscribed Sent webhooks and is not documented as carrying the webhook HMAC headers; use a unique callback path tied to the provisioning record, reject unknown profile ids, and treat polling as the authoritative recovery path.

Profile status vocabulary differs by surface: the create response demonstrates lowercase

incomplete

, the completion

demonstrates lowercase

completed

, the completion callback uses

COMPLETED

SUBMITTED

, and

failed

, and

GET /v3/profiles/{id}

documents

approved

submitted

processing

, and

failed

. Do not assert a closed enum, do not lowercase-normalize into a fixed set, and record which surface produced each value. Compare statuses case-insensitively and preserve unknown strings.

POST /v3/profiles/{profileId}/complete

需要

webHookUrl

。

json

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

状态码表示处理已启动，但不包含最终状态。

状态码表示配置文件已完成，响应体中包含状态信息。回调体为

{profileId, success, status, timestamp}

，且仅推送一次，无重试机制，因此接收方必须在调用前处于可用状态，若回调失败则需降级为轮询

GET /v3/profiles/{profileId}

接口。此回调与已订阅的Sent webhook相互独立，且文档未说明其携带webhook HMAC头；请使用与预配记录绑定的唯一回调路径，拒绝未知的profileId，并将轮询作为权威的恢复方式。

配置文件状态的表述因场景而异：创建响应中使用小写的

incomplete

，完成接口的

响应中使用小写的

completed

，完成回调中使用

COMPLETED

、

SUBMITTED

和

failed

，而

GET /v3/profiles/{id}

接口文档中使用

approved

、

submitted

、

processing

和

failed

。请勿断言固定的枚举值，请勿将所有状态统一转为小写，需记录每个状态的来源场景。比较状态时不区分大小写，并保留未知字符串。

Campaigns per profile

配置文件专属活动

Campaign management lives under the profile:

GET|POST /v3/profiles/{profileId}/campaigns

and

PUT|DELETE /v3/profiles/{profileId}/campaigns/{campaignId}

. There are no standalone brand endpoints; a dedicated brand is created with the profile.

json

{
  "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

accepts one of thirteen values,

sampleMessages

holds 1 to 5 entries of at most 1,024 characters each, and a numeric

volume

string below 2,000 selects the low-volume tier while 2,000 or above selects the standard tier. Campaign statuses are

SENT_CREATED

ACTIVE

, and

EXPIRED

. Use

sms-10dlc-registration

for use-case selection and sample-copy policy.

活动管理属于配置文件范畴：

GET|POST /v3/profiles/{profileId}/campaigns

和

PUT|DELETE /v3/profiles/{profileId}/campaigns/{campaignId}

。无独立的品牌端点；专用品牌会随配置文件一同创建。

json

{
  "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条消息，每条最多1024个字符；数值型

volume

字符串小于2000时选择低量层级，大于等于2000时选择标准层级。活动状态包括

SENT_CREATED

、

ACTIVE

和

EXPIRED

。请使用

sms-10dlc-registration

进行用例选择和示例文案策略制定。

Users and roles

用户与角色

Five operations administer access:

GET /v3/users

POST /v3/users

(invite),

GET /v3/users/{userId}

PATCH /v3/users/{userId}

(role), and

DELETE /v3/users/{userId}

. None is exposed through MCP. Assignable roles are

admin

billing

, and

developer

;

owner

is implicit for the creating account and never appears in the list. Mutations require

admin

Role checks resolve against the email that owns the API key and pass only for the owner or an active user with an allowed role —

invited

suspended

, and

rejected

users fail. Organization-level access cascades to child profiles. Invitations expire after seven days, and inviting an existing user returns

Before any user mutation, read the current state, then confirm explicitly with the operator. The API refuses to let you change your own role, demote the last admin, remove yourself, or remove the last admin, but checking first produces a clear explanation instead of a validation error. The full role matrix and key-hygiene rules are in references/users-and-roles.md.

There is no endpoint to list, create, or revoke API keys; key management is a dashboard operation. Rotation is create-new, deploy, verify with

GET /v3/me

, then disable or delete the old key — deleting first only when the key is compromised.

有五项操作用于管理访问权限：

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天后过期，邀请已存在的用户会返回

错误。

在进行任何用户修改操作前，请先读取当前状态，再与操作员确认。API不允许修改自身角色、降级最后一名管理员、移除自身或移除最后一名管理员，但提前检查可给出清晰的解释，而非返回验证错误。完整的角色矩阵和密钥安全规则请参考references/users-and-roles.md。

无端点可列出、创建或撤销API密钥；密钥管理是控制台操作。密钥轮换流程为：创建新密钥、部署、通过

GET /v3/me

验证，然后禁用或删除旧密钥——仅当密钥泄露时才先删除旧密钥。

Multi-tenant provisioning notes

多租户预配注意事项

Webhook events never carry your application's tenant identifier. Before the first send, persist

message_id -> {tenant, profile, logical_send_id, channel}

and

receiving_number -> {tenant, profile}

. Do not infer tenant ownership from

account_id

, since many tenant profiles can share one organization. Provision one webhook registration per environment so a failing lower-environment receiver cannot auto-disable production.

Webhook事件从不携带您应用的租户标识符。首次发送前，请持久化存储

message_id -> {tenant, profile, logical_send_id, channel}

和

receiving_number -> {tenant, profile}

映射关系。请勿通过

account_id

推断租户归属，因为多个租户配置文件可共享一个组织。为每个环境预配一个webhook注册，避免低环境接收方故障导致生产环境自动禁用。

Boundaries

边界划分

Use

sender-profile-architect

for the isolation, credential, and blast-radius design decision;

waba-embedded-signup

for the WhatsApp signup flow;

sms-10dlc-registration

for brand vetting and campaign policy; and

sent-webhook-engineer

for subscribed message-event receivers. Profile-completion callbacks use the separate verification and polling guidance in this skill.

请使用

sender-profile-architect

进行隔离、凭证和影响范围的设计决策；使用

waba-embedded-signup

处理WhatsApp注册流程；使用

sms-10dlc-registration

进行品牌审核和活动策略制定；使用

sent-webhook-engineer

处理已订阅的消息事件接收方。配置文件完成回调需遵循本技能中单独的验证和轮询指南。