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

每行显示选择和发送模板所需的字段:
- 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);
}for template in client.sms_templates.list(scope="system"):
print(template.id, template.slug)for tpl, err := range client.SmsTemplates.List(context.Background(), bird.SMSTemplateListParams{
Scope: "system",
}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(tpl.Id, *tpl.Slug)
}foreach ($bird->smsTemplates->list(['scope' => 'system']) as $template) {
echo $template->getId(), ' ', $template->getSlug(), "\n";
}bird sms templates listcurl "https://eu1.platform.bird.com/v1/sms/templates?category=authentication" \
-H "Authorization: Bearer bk_eu1_..."模板摘要包含标识、类别、状态、可用语言以及草稿/正式版本引用,但省略源文本和变量。通过 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;仅在重试同一请求时复用该键。
- 使用 POST /v1/sms/templates 和 {"slug":"order-shipped","category":"transactional"} 创建模板。201 响应包含 id 和 draft_version_id;模板以空白英文草稿开始。保存这两个 ID 以供后续调用。
- 使用 PUT /v1/sms/templates/{id}/versions/{draft_version_id}/languages/en 和 {"text":"Your order {{ order_number }} has shipped."} 保存文本。200 响应包含 draft_revision。
- 使用 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" } },
});client.sms.send(
to="+14155550100",
template="bird_otp_verification",
parameters={"code": "123456"},
)msg, err := client.Sms.Send(context.Background(), bird.SmsSendParams{
To: "+14155550100",
Template: "bird_otp_verification",
Parameters: map[string]any{"code": "123456"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id)$message = $bird->sms->send(
to: '+14155550100',
template: 'bird_otp_verification',
parameters: ['code' => '123456'],
);
echo $message->getId(), ' ', $message->getStatus();bird sms send \
--parameters '{"code":"123456"}' \
--template bird_otp_verification \
--to +14155550100curl -X POST "https://eu1.platform.bird.com/v1/sms/messages" \
-H "Authorization: Bearer bk_eu1_..." \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550100",
"template": {
"slug": "bird_otp_verification_ttl",
"language": "en",
"parameters": { "code": "481920", "ttl": "10" }
}
}'slug 是模板在目录中的句柄(也可以通过 id 来标识模板)。language 选择本地化正文;省略则使用模板的默认语言。parameters 按变量名为模板的每个变量提供值。缺少必需变量、传入未声明的键、值不符合变量约束,或序列化后超过 16 KB 的 parameters 对象,均会被拒绝并返回 422。
202 响应包含所选 from、模板类别、模板和版本 ID、源哈希以及请求/解析后的语言。身份验证消息文本以 **REDACTED** 返回。已接受的消息会保留渲染内容和所选版本,即使你之后发布、回滚或删除模板也不受影响。
发送的其他一切(收件人、标签、元数据、目的地允许列表和异步 202 模型)与自由文本发送的工作方式完全相同。
后续步骤
- 发送 SMS:在发送载荷中添加 template 字段。
- SMS 日志:查找已发送的消息并跟踪其生命周期。
- 事件:接收每条消息的投递事件。
- 使用模板发送 SMS:一个从终端发送预审批模板的视频
相关资源
继续查阅此主题的文档、指南和示例。资源为英文。