sender-profile-architect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sender profile architect

Sender Profile 架构师

Overview

概述

Use this skill to decide how a customer should map brands, tenants, departments, and channels onto Sent Sender Profiles. A Sender Profile is the durable boundary for sender identity and channel configuration. The Sent dashboard shows each profile with display name, brand description,

x-sender-id

, and SMS/WhatsApp configuration status. The v3 API exposes profile creation, listing, retrieval, update, deletion, and completion.

Good profile architecture prevents three recurring failures: messages sent from the wrong brand, compliance resources shared across incompatible use cases, and webhook/event data that cannot be routed back to the correct tenant.

使用此技能来确定客户应如何将品牌、租户、部门和渠道映射到Sent Sender Profile上。Sender Profile是发件人身份和渠道配置的持久边界。Sent控制台会显示每个配置文件的显示名称、品牌描述、

x-sender-id

以及SMS/WhatsApp配置状态。v3 API支持配置文件的创建、列出、检索、更新、删除和完成操作。

合理的配置文件架构可避免三类常见故障：从错误品牌发送消息、合规资源在不兼容场景间共享、Webhook/事件数据无法路由回正确租户。

When to use

使用场景

Use this skill when the user asks how to create Sender Profiles, split one customer into multiple senders, model a marketplace or ISV, isolate brands, route webhooks, reason about account-level API key blast radius, complete profile setup, or safely offboard a tenant. Use it whenever the request mentions

x-sender-id

, Sender Profile, profile completion, multi-tenant messaging, brand hierarchy, SMS/WhatsApp/RCS sender setup, or webhook routing.

Do not use this skill to decide 10DLC use cases in detail, write WhatsApp template copy, onboard RCS approval, or analyze delivery failures. Hand those to the related skills once the profile boundary is clear.

当用户询问如何创建Sender Profile、将单个客户拆分为多个发件人、建模市场或ISV、隔离品牌、路由Webhook、评估账户级API密钥影响范围、完成配置文件设置或安全下线租户时，使用此技能。只要请求中提及

x-sender-id

、Sender Profile、配置文件完成、多租户消息、品牌层级、SMS/WhatsApp/RCS发件人设置或Webhook路由，就可以使用该技能。

请勿使用此技能详细确定10DLC用例、编写WhatsApp模板文案、完成RCS审批或分析投递失败问题。在明确配置文件边界后，将这些任务交给相关技能处理。

Profile boundary principle

配置文件边界原则

Create a separate Sender Profile when the sender identity, compliance evidence, webhook routing, operational ownership, or channel readiness must be isolated. Reuse a profile when the same legal/brand identity sends the same class of traffic and should share compliance posture and operational controls.

Split signal	Create separate profiles when	Reuse a profile when
Brand identity	The recipient sees different brand names or support contacts.	The recipient sees one brand across all messages.
Compliance	10DLC brand/campaign, opt-in source, or use case differs materially.	Compliance evidence and use case are the same.
Channel configuration	SMS, WhatsApp, or RCS resources belong to different brands or regions.	Channels represent one sender identity.
Webhook routing	Events must land in different tenant queues or data stores.	One team owns all events and reconciliation.
Lifecycle	One sender may be paused, restricted, or offboarded independently.	Senders always launch, pause, and retire together.

当发件人身份、合规证据、Webhook路由、运营所有权或渠道就绪状态需要隔离时，创建独立的Sender Profile。当同一法律/品牌身份发送同类流量且应共享合规态势和运营控制时，复用同一配置文件。

拆分信号	需创建独立配置文件的场景	可复用配置文件的场景
品牌身份	收件人看到不同的品牌名称或支持联系方式。	收件人在所有消息中看到同一品牌。
合规要求	10DLC品牌/活动、选择加入来源或用例存在实质性差异。	合规证据和用例完全相同。
渠道配置	SMS、WhatsApp或RCS资源属于不同品牌或地区。	所有渠道代表同一发件人身份。
Webhook路由	事件必须进入不同的租户队列或数据存储。	同一团队负责所有事件和对账工作。
生命周期	某个发件人可能被独立暂停、限制或下线。	所有发件人始终同步启动、暂停和停用。

Process

流程

1. Draw the recipient-visible sender model

1. 绘制收件人可见的发件人模型

Start with what the recipient sees, not with internal account hierarchy. Ask: “Would the recipient reasonably think these messages came from the same sender?” If the answer is no, use separate profiles.

Example. A healthcare ISV serves three clinic chains. Each chain has its own patient-facing brand, privacy policy, and support phone. Create one profile per clinic chain. Do not put all clinics behind a single ISV profile just because the same platform sends the messages.

从收件人的视角出发，而非内部账户层级。询问：“收件人是否会合理认为这些消息来自同一发件人？”如果答案是否定的，则使用独立配置文件。

示例：某医疗ISV服务三家连锁诊所。每家诊所都有自己的面向患者的品牌、隐私政策和支持电话。为每家连锁诊所创建一个配置文件。不要仅仅因为使用同一平台发送消息，就将所有诊所放在单个ISV配置文件下。

2. Map each profile to channel readiness

2. 将每个配置文件映射到渠道就绪状态

For each proposed profile, list SMS, WhatsApp, and RCS readiness separately. Sent’s channel setup guidance covers production setup for all three channels and recommends using the same phone number across SMS, WhatsApp, and RCS where possible. That recommendation does not override compliance or brand isolation.

Channel	Profile-level questions	Follow-up skill
SMS	Is US A2P involved? Which brand/campaign and opt-in evidence apply?	`sms-10dlc-registration`
WhatsApp	Which WABA/phone number identity maps to this brand? Are templates approved?	`waba-embedded-signup` , `waba-template-author`
RCS	Has Sent initiated setup and carrier approval for this profile? Is SMS fallback ready?	`rcs-agent-onboarding`

针对每个拟议的配置文件，分别列出SMS、WhatsApp和RCS的就绪状态。Sent的渠道设置指南涵盖了这三个渠道的生产环境设置，并建议在可能的情况下，在SMS、WhatsApp和RCS中使用同一电话号码。该建议不会覆盖合规或品牌隔离要求。

渠道	配置文件层级问题	后续技能
SMS	是否涉及美国A2P？适用哪个品牌/活动和选择加入证据？	`sms-10dlc-registration`
WhatsApp	哪个WABA/电话号码身份与此品牌匹配？模板是否已获批？	`waba-embedded-signup` , `waba-template-author`
RCS	Sent是否已为此配置文件启动设置和运营商审批？SMS回退是否就绪？	`rcs-agent-onboarding`

3. Create or update the Sent profile

3. 创建或更新Sent配置文件

Use Sent’s profile API where API access is appropriate, or the dashboard when the user is operating manually. The verified v3 API includes:

Operation	Endpoint	Use
Create profile	`POST /v3/profiles`	Create a sender boundary for a brand, department, tenant, or use case.
List profiles	`GET /v3/profiles`	Audit existing profile boundaries before creating duplicates.
Retrieve profile	`GET /v3/profiles/{profileId}`	Inspect detailed profile configuration.
Update profile	`PATCH /v3/profiles/{profileId}`	Change profile configuration/settings.
Delete profile	`DELETE /v3/profiles/{profileId}`	Soft-delete a profile after traffic, webhooks, and credentials are drained.
Complete setup	`POST /v3/profiles/{profileId}/complete`	Validate prerequisites and start the profile completion workflow.

Use idempotency keys on create/update/complete calls when the integration might retry. The OpenAPI exposes an optional

Idempotency-Key

header for those operations.

在适合API访问的场景下使用Sent的配置文件API，在用户手动操作时使用控制台。已验证的v3 API包括：

操作	端点	用途
创建配置文件	`POST /v3/profiles`	为品牌、部门、租户或用例创建发件人边界。
列出配置文件	`GET /v3/profiles`	在创建重复配置文件前审核现有配置文件边界。
检索配置文件	`GET /v3/profiles/{profileId}`	检查详细的配置文件配置。
更新配置文件	`PATCH /v3/profiles/{profileId}`	修改配置文件配置/设置。
删除配置文件	`DELETE /v3/profiles/{profileId}`	在流量、Webhook和凭证清空后软删除配置文件。
完成设置	`POST /v3/profiles/{profileId}/complete`	验证先决条件并启动配置文件完成工作流。

当集成可能重试时，在创建/更新/完成调用中使用幂等键。OpenAPI为这些操作提供了可选的

Idempotency-Key

头。

4. Attach compliance and channel prerequisites before completion

4. 在完成前附加合规和渠道先决条件

The profile completion endpoint validates prerequisites such as profile data, brand, campaigns, and channel connections. For US A2P SMS, create or attach Sent brand and campaign resources before completing the profile. The verified brand/campaign endpoints are

/v3/brands

and

/v3/brands/{brandId}/campaigns

Do not invent field names such as

tcr_brand_id

waba_phone_id

unless the actual API response includes them. Store Sent IDs returned by the API and any returned provider identifiers separately, with clear names.

Example data model.

text

sender_profiles
- sent_profile_id            -- Sent Profile.id (UUID)
- x_sender_id                -- per-profile, v2 legacy; useful for dashboard cross-ref
- name                       -- Sent Profile.name
- short_name                 -- Sent Profile.short_name
- description                -- Sent Profile.description
- sent_status                -- mirrors Sent Profile.status: incomplete|pending_review|approved|rejected
- status_app_level           -- finer-grained internal lifecycle (do not conflate with sent_status)
- sms_ready_app_level
- whatsapp_ready_app_level
- rcs_ready_app_level

sender_profile_resources
- sent_profile_id
- channel
- sent_resource_id           -- e.g., /v3/brands/{brandId}, /v3/brands/{brandId}/campaigns/{id}
- provider_resource_type     -- e.g., tcr_brand, tcr_campaign, waba, waba_phone, rbm_agent
- provider_resource_id
- status_last_seen_at

配置文件完成端点会验证配置文件数据、品牌、活动和渠道连接等先决条件。对于美国A2P SMS，在完成配置文件前创建或附加Sent品牌和活动资源。已验证的品牌/活动端点为

/v3/brands

和

/v3/brands/{brandId}/campaigns

。

除非实际API响应中包含相关字段，否则不要自行发明字段名，如

tcr_brand_id

或

waba_phone_id

。将API返回的Sent ID和任何返回的提供商标识符分开存储，并使用清晰的名称。

示例数据模型

text

sender_profiles
- sent_profile_id            -- Sent Profile.id (UUID)
- x_sender_id                -- 每个配置文件独有，v2遗留特性；便于控制台交叉引用
- name                       -- Sent Profile.name
- short_name                 -- Sent Profile.short_name
- description                -- Sent Profile.description
- sent_status                -- 镜像Sent Profile.status: incomplete|pending_review|approved|rejected
- status_app_level           -- 更细粒度的内部生命周期（不要与sent_status混淆）
- sms_ready_app_level
- whatsapp_ready_app_level
- rcs_ready_app_level

sender_profile_resources
- sent_profile_id
- channel
- sent_resource_id           -- 例如：/v3/brands/{brandId}, /v3/brands/{brandId}/campaigns/{id}
- provider_resource_type     -- 例如：tcr_brand, tcr_campaign, waba, waba_phone, rbm_agent
- provider_resource_id
- status_last_seen_at

5. Design webhook routing around Sent event evidence

5. 基于Sent事件证据设计Webhook路由

Sent’s v3 webhook API supports creating/listing webhooks, retrieving event types, viewing webhook events, testing a webhook, toggling status, and rotating signing secrets. Use those endpoints to verify configuration and delivery before blaming channel infrastructure.

Route inbound events by stable identifiers present in the Sent payload. If the exact event payload fields are not documented for the customer’s account, log full events in a secure staging environment and derive the routing map from observed Sent fields rather than assumed provider keys.

Example. If a marketplace needs tenant-specific queues, route first by Sent profile or sender identifier if present in the event. Fall back to a mapping table from Sent message ID to tenant/profile created at send time. Avoid making provider IDs the only routing key.

Sent的v3 Webhook API支持创建/列出Webhook、检索事件类型、查看Webhook事件、测试Webhook、切换状态和轮换签名密钥。在归咎于渠道基础设施之前，使用这些端点验证配置和投递情况。

通过Sent payload中存在的稳定标识符路由入站事件。如果客户账户的事件payload字段未被记录，则在安全的 staging 环境中记录完整事件，并从观察到的Sent字段而非假设的提供商密钥推导路由映射。

示例：如果市场需要租户特定队列，首先通过事件中存在的Sent配置文件或发件人标识符进行路由。如果没有，则使用发送时创建的Sent消息ID到租户/配置文件的映射表作为备选。避免将提供商ID作为唯一路由键。

6. Model profile lifecycle as an application state machine

6. 将配置文件生命周期建模为应用状态机

Sent exposes profile APIs and completion behavior, but your application may need richer internal states. Label them as application states so future agents do not mistake them for Sent enums.

Application state	Meaning	Exit condition
`draft`	Profile data is being collected.	Required identity and owner fields are present.
`compliance_pending`	Brand/campaign/channel evidence is being prepared.	Required compliance resources exist or have been submitted.
`completion_started`	`/v3/profiles/{profileId}/complete` returned accepted/started behavior.	Webhook/callback or follow-up status indicates completion result.
`active`	Profile is approved for intended channels.	Traffic is allowed and test sends pass.
`restricted`	One or more channels is blocked, paused, or missing approval.	Root cause resolved and profile retested.
`retiring`	Sends are drained and webhooks/credentials are being removed.	No active sends, subscriptions, or credentials remain.

Sent提供了配置文件API和完成行为，但你的应用可能需要更丰富的内部状态。将这些状态标记为应用状态，以便后续代理不会将其误认为Sent枚举值。

应用状态	含义	退出条件
`draft`	正在收集配置文件数据。	已提供必需的身份和所有者字段。
`compliance_pending`	正在准备品牌/活动/渠道证据。	必需的合规资源已存在或已提交。
`completion_started`	`/v3/profiles/{profileId}/complete` 返回已接受/已启动状态。	Webhook/回调或后续状态指示完成结果。
`active`	配置文件已获批准可用于目标渠道。	允许发送流量且测试发送通过。
`restricted`	一个或多个渠道被阻止、暂停或未获得批准。	已解决根本原因并重新测试配置文件。
`retiring`	正在停止发送并移除Webhook/凭证。	无活跃发送、订阅或凭证残留。

7. Plan tenant offboarding before the first send

7. 在首次发送前规划租户下线流程

Offboarding is easiest when profile boundaries are clean. To retire a profile, stop new sends, drain in-flight messages, export relevant message/activity evidence, disable or reroute webhooks, revoke or rotate credentials, delete/soft-delete the profile when safe, and retain compliance records according to the customer’s policy.

当配置文件边界清晰时，下线操作最容易。要停用一个配置文件，请停止新发送、清空在途消息、导出相关消息/活动证据、禁用或重新路由Webhook、撤销或轮换凭证、在安全时删除/软删除配置文件，并根据客户政策保留合规记录。

Common rationalizations to avoid

需要避免的常见误区

Do not use one profile for every tenant just because it is easy. Over-splitting creates unnecessary compliance and operational work.

Do not use one shared profile for distinct recipient-visible brands. Under-splitting creates wrong-sender and compliance-contamination failures.

Do not treat internal tenant ID as a substitute for Sender Profile ID. The application can map tenant ID to profile ID, but outbound sends and webhook reconciliation need Sent identifiers.

Do not hardcode provider identifiers as routing keys before verifying Sent webhook payloads. Sent’s event shape is the integration contract.

Do not rotate webhook secrets casually. Secret rotation immediately invalidates the old secret, so coordinate with the receiving endpoint.

不要仅仅因为简单就为每个租户使用一个配置文件。过度拆分会产生不必要的合规和运营工作。

不要为不同的收件人可见品牌使用同一个共享配置文件。拆分不足会导致发件人错误和合规模糊问题。

不要将内部租户ID作为Sender Profile ID的替代。应用可以将租户ID映射到配置文件ID，但 outbound 发送和Webhook对账需要Sent标识符。

在验证Sent Webhook payload之前，不要将提供商标识符硬编码为路由键。Sent的事件格式是集成契约。

不要随意轮换Webhook密钥。密钥轮换会立即使旧密钥失效，因此需要与接收端点协调。

Verification checklist

验证清单

Related skills

Suggested bundled references and scripts

建议的捆绑参考资料和脚本

File	Type	Purpose
`references/multi-tenancy-patterns.md`	Architecture reference	Keep detailed routing, rate-limit, idempotency, and offboarding patterns outside the skill body.
`references/sender-profile-data-model.md`	Schema reference	Provide recommended application tables and mapping fields for Sent profile integrations.
`references/profile-boundary-examples.md`	Worked examples	Show ISV, marketplace, multi-brand enterprise, and department-level profile splits.

文件	类型	用途
`references/multi-tenancy-patterns.md`	架构参考	在技能主体之外保存详细的路由、速率限制、幂等性和下线模式。
`references/sender-profile-data-model.md`	架构参考	为Sent配置文件集成提供推荐的应用表和映射字段。
`references/profile-boundary-examples.md`	示例参考	展示ISV、市场、多品牌企业和部门级配置文件拆分案例。

Unverified claims to confirm or remove

需确认或移除的未验证声明

API keys are issued per customer account (not per profile);
```
x-sender-id
```
is per-profile and visible in the dashboard but is v2 legacy for routing — v3 uses
```
x-api-key
```
alone. Design key blast-radius around the account, not the profile.
Sent's profile
```
status
```
enum is
```
incomplete | pending_review | approved | rejected
```
. If your application tracks finer-grained internal lifecycle states (e.g.
```
partially_active
```
,
```
restricted
```
,
```
restoring
```
), they should not be conflated with the Sent profile
```
status
```
field — label them as application states.
Provider-specific routing keys for WhatsApp/RCS/SMS (e.g.,
```
phone_number_id
```
,
```
agentId
```
, TCR campaign ID) should not be required as primary routing keys unless observed in Sent event payloads or docs. The verified v3 webhook payload exposes
```
account_id
```
,
```
message_id
```
,
```
channel
```
,
```
inbound_number
```
,
```
outbound_number
```
,
```
template_id
```
— route on those plus a
```
message_id
```
→ profile map persisted at send time.

API密钥按客户账户颁发（而非每个配置文件）；
```
x-sender-id
```
为每个配置文件独有且在控制台可见，但属于用于路由的v2遗留特性 — v3仅使用
```
x-api-key
```
。围绕账户而非配置文件设计密钥影响范围。
Sent的配置文件
```
status
```
枚举值为
```
incomplete | pending_review | approved | rejected
```
。如果你的应用跟踪更细粒度的内部生命周期状态（如
```
partially_active
```
、
```
restricted
```
、
```
restoring
```
），请勿将其与Sent配置文件
```
status
```
字段混淆 — 将其标记为应用状态。
WhatsApp/RCS/SMS的提供商特定路由键（如
```
phone_number_id
```
、
```
agentId
```
、TCR活动ID）不应作为主要路由键，除非在Sent事件payload或文档中观察到相关内容。已验证的v3 Webhook payload暴露了
```
account_id
```
、
```
message_id
```
、
```
channel
```
、
```
inbound_number
```
、
```
outbound_number
```
、
```
template_id
```
— 基于这些字段加上发送时持久化的
```
message_id
```
→配置文件映射进行路由。