Sign inGet Started

SMS 模板

模板是一条可复用的消息,通过引用发送,同时提供一次性验证码或订单号等值。Bird 的内置 system 模板涵盖身份验证和事务性消息。工作区模板创作处于 API 预览阶段;仪表板继续显示内置目录。
模板提供用于目的地合规检查的消息类别。内置模板还会为目的地选择发送方,因此你可以省略 from。工作区模板需要你自己的发送方,与自由文本发送一样。

在控制面板中浏览模板

SMS 下的 Templates 页面列出了内置模板。可按名称搜索或按状态和类别筛选。
SMS Templates 选项卡:搜索框上方有 Status 和 Category 筛选器,下方是模板表格,每行显示名称、Active 状态、类别、EN 语言标签和 System 范围,列包括 Name、Status、Category、Language、Scope 和 Updated。
每行显示选择和发送模板所需的字段:
  • Name:模板的显示名称及其 slug(例如 bird_order_confirmation)。slug 是发送时传递的标识,创建后固定不变。
  • Status:内置模板为 Active,可直接发送。工作区模板在发布前为 Draft,发布后变为 Active。将此共享状态字段视为开放集合。
  • Category:应用于从模板发送的消息的内容分类(transactional、marketing 或 authentication)。
  • Language:模板已有的语言,以 BCP 47 标签表示。当模板被本地化为多种语言时,前几种显示为标签,其余以 +N 溢出显示。
  • Scope:Bird 的内置模板为 System。Workspace 标识你通过 API 预览创作的模板。
  • Updated:模板最后一次更改的时间。内置模板不显示日期。

模板包含什么

除名称、类别和语言外,每个模板还定义了发送时填充的变量。变量具有 key、type、required 标志和人类可读的 constraint。内置模板有类型化插槽;工作区模板推断通用 text 插槽并接受标量参数值。sensitive 变量会在存储的消息内容中被替换。传输队列仍携带投递所需的文本。提供每个必需变量,不要传入未声明的键。
模板以一种或多种语言入库,其 default_language 是发送未指定语言时所用的语言。请求模板未入库的语言时,Bird 会回退:先回退到同一语言的更宽泛形式,再回退到默认语言,因为 SMS 模板将 on_missing_language 默认为 fallback。内置模板使用 language_source_required: false。工作区模板可要求指定语言或设置 on_missing_language: fail;这些策略立即生效,而内容和默认语言的更改在发布时生效。

从 API 列出模板

GET /v1/sms/templates 返回游标分页的模板摘要页。使用 starting_after 跟随 next_cursor,直到其为 null;一页并非完整目录。读取模板需要具有 sms_management 作用域的 API 密钥,该作用域与发送使用的 sms 作用域不同。按 scope、category、status 或 language 筛选,或使用 q 搜索:
for await (const tpl of bird.smsTemplates.list({ scope: "system" })) {
  console.log(tpl.id, tpl.slug);
}
模板摘要包含标识、类别、状态、可用语言以及草稿/正式版本引用,但省略源文本和变量。通过 GET /v1/sms/templates/{template_ref} 按 slug 或 ID 获取模板。使用其 draft_version_id 查看可编辑的工作区内容,或使用其 live_version_id 查看发送所用的内容。新的工作区模板在发布前没有正式版本。
通过 GET /v1/sms/templates/{template_ref}/versions/{version_id} 读取所选版本。响应包含变量和按语言键索引的内容映射。要获取单一语言,追加 /languages/{language}。列表的 language 过滤器匹配已发布的内容;仅存在于草稿中的语言不匹配。
内置模板暴露一个只读版本。其稳定 ID 标识目录条目;其内容哈希区分源更新。已发布的工作区版本保留不可变历史。版本列表同样使用游标分页并省略源文本。

API 预览中的工作区创作

使用具有 sms_management 写入权限的 API 密钥。将 JSON 请求发送到你密钥的区域 API 主机,带上 Authorization: Bearer <API_KEY> 和 Content-Type: application/json。为每次变更操作使用独立的 Idempotency-Key;仅在重试同一请求时复用该键。
  1. 使用 POST /v1/sms/templates 和 {"slug":"order-shipped","category":"transactional"} 创建模板。201 响应包含 id 和 draft_version_id;模板以空白英文草稿开始。保存这两个 ID 以供后续调用。
  2. 使用 PUT /v1/sms/templates/{id}/versions/{draft_version_id}/languages/en 和 {"text":"Your order {{ order_number }} has shipped."} 保存文本。200 响应包含 draft_revision。
  3. 使用 POST /v1/sms/templates/{id}/versions/{draft_version_id}/submit 发布,将该修订版作为 {"expected_revision":1} 传入(用返回值替换 1)。带有 valid: true 的 200 响应标识已发布版本。422 表示草稿内容无效;修复返回的语言问题后使用新的幂等键重新提交。
发布要求每种语言都有非空文本且变量一致。发布同步生效,无需提供商审批。API 还支持预览、复制、将草稿重置为正式内容以及回滚到已发布版本。仪表板编辑不可用。
在更新模板设置或回滚之前,先读取当前修订版。语言保存也可以包含修订守卫;过期的守卫返回 409。预览使用所选版本和参数来报告渲染文本、解析后的语言、编码和分段数,在发送前可供确认。

使用模板发送

设置发送的 template 对象,而非 text。省略 category 和 media_urls。对于下面的内置模板,也省略 from。工作区模板需要 from 且必须有已发布版本。
内置身份验证模板还会选择共享发送方品牌:bird_otp_verification_ttl 使用 Authifly,而 bird_otp_verification_ttl_bird_verify 使用 Bird Verify。目的地决定发送方显示为品牌名称、短码还是电话号码。
发送内置模板:
await bird.sms.send({
  to: "+14155550100",
  template: { slug: "bird_otp_verification", parameters: { code: "123456" } },
});
slug 是模板在目录中的句柄(也可以通过 id 来标识模板)。language 选择本地化正文;省略则使用模板的默认语言。parameters 按变量名为模板的每个变量提供值。缺少必需变量、传入未声明的键、值不符合变量约束,或序列化后超过 16 KB 的 parameters 对象,均会被拒绝并返回 422。
202 响应包含所选 from、模板类别、模板和版本 ID、源哈希以及请求/解析后的语言。身份验证消息文本以 **REDACTED** 返回。已接受的消息会保留渲染内容和所选版本,即使你之后发布、回滚或删除模板也不受影响。
发送的其他一切(收件人、标签、元数据、目的地允许列表和异步 202 模型)与自由文本发送的工作方式完全相同。

后续步骤

  • 发送 SMS:在发送载荷中添加 template 字段。
  • SMS 日志:查找已发送的消息并跟踪其生命周期。
  • 事件:接收每条消息的投递事件。
  • 使用模板发送 SMS:一个从终端发送预审批模板的视频