template-builder-ui

Sent 模板构建器 UI

围绕 Sent v3 的 definition 契约设计界面。UI 可以导入 Meta 素材，但其规范的保存和提交模型绝不能是 Meta 的 components[] 载荷。

产品模型

使用一个草稿对象，包含：

• 可选的 category 和 language；
• 必需的 definition.body.multiChannel；
• 可选的 sms、whatsapp 和 rcs 完整正文覆盖内容；
• 可选的 definition.header、footer、buttons、definitionVersion 和 authenticationConfig；
• creation_source、submit_for_review 和 sandbox 提交控制项。

不要公开名为 name、channels、body、header 或 buttons 的顶层创建字段。如果产品需要内部显示标签，请将其置于 Sent 创建载荷之外。

推荐的编辑流程

1. 收集意图并选择类别。
2. 编写 multiChannel 正文。
3. 将变量作为结构化实体插入。
4. 添加可选的按渠道覆盖内容。
5. 在支持的情况下添加页眉、页脚和按钮。
6. 查看实时预览和无障碍性。
7. 在本地验证，并使用 sandbox: true 验证。
8. 保存草稿，然后明确提交给服务提供商审核。

类别不应阻止用户开始输入，但在提交前必须显示，因为它会影响身份验证规则和 WhatsApp 政策审核。

变量体验

插入变量时，同时创建：

• 类似 {{0:variable}} 的占位符；以及
• 包含 id、name、type 和 props.sample 的对应实体。

变量移动时必须原子化地重新编号。绝不允许用户独立于实体表编辑占位符语法。对于裸露的 {{1}} 或没有定义的 ID，应显示明确的错误。

验证矩阵

应用 references/template-validation-matrix.md 中的精确规则，包括：

• 每个正文最多 1,024 个字符；
• 页眉和页脚最多 60 个字符；
• 页脚不得包含变量；
• 按钮总数最多 10 个；
• 按钮类型 QUICK_REPLY、URL、VOICE_CALL、PHONE_NUMBER 和 COPY_CODE 及各类型的限制；
• 不得臆造快速回复与 CTA 之间的互斥规则；
• authenticationConfig 和身份验证限制；
• 完整且可独立通过验证的渠道覆盖内容。

针对序列化后的 JSON 运行随附的 waba-template-author 代码检查工具。服务端验证仍是最终依据。

渠道预览

SMS

预览纯文本以及估算的 GSM/UCS-2 分段数。明确说明，分段估算会影响计费，但不是模板正文长度限制。

WhatsApp

预览页眉、正文、页脚和按钮。显示示例值、类别、语言以及对服务提供商审核的影响。

RCS

Sent 当前的 RCS 指南支持文本和最多四个建议选项。富媒体卡片、轮播和媒体附件属于路线图能力，不是 Sent 当前构建器的控件。对于不可用的功能，不要生成能力声明。

渠道路由属于发送流程，而非模板编辑器。如果模拟器中显示路由：

• 省略 channel 或使用 ["sent"] 表示自动路由和回退；
• ["rcs"] 表示固定使用 RCS，不进行跨渠道回退；
• 多个显式值表示广播，并会发送多条单独计费的消息。

绝不要将显式的 RCS 加 SMS 数组描述为按顺序回退。

保存和审核行为

使用 sandbox: true 进行验证。使用 submit_for_review: false 保存。将其切换为 true 之前，显示：

• 类别和语言；
• 使用示例值渲染的预览；
• 渠道覆盖内容；
• 按钮操作；
• 任何警告；
• 服务提供商审核属于外部状态变更这一事实。

保存时不要自动提交。

生命周期 UX

资源状态值目前包括 DRAFT、PENDING、APPROVED、REJECTED 和 PAUSED。请保留未知状态的渲染逻辑。

WhatsApp 模板 Webhook 事件使用 field: "templates"，没有 sub_type 或 event；状态为 payload.status。提供方的值可能包括 CATEGORY_UPDATED、DISABLED 及其他未来可能出现的字符串。请参阅 references/template-status-handling.md。

无障碍访问与故障恢复

• 将每条错误与相应字段和摘要关联起来。
• 不要仅依赖预览颜色。
• 验证失败后保留用户所做的编辑。
• 为高级用户保留原始 JSON 检查功能。
• 在转换前，将导入的 Meta JSON 标记为“Meta Cloud API source”。
• 为服务器规范化处理以及提供方驱动的类别／状态变更提供差异对比。

请使用 references/template-ui-wireflows.md了解状态转换。使用 waba-template-author 进行文案和政策判断，使用 sent-templates 执行现有资源操作，使用 rcs-agent-onboarding 评估 RCS 上线准备情况。