哪些完全相同
一个账户只有一份余额、一张费率表和一套报告。无论消息从编辑器还是从脚本发出,费用都相同,会出现在同一列表中,并触发同样的 Webhook。决定送达的一切也都是共用的:每个目的地的唯一路由、各国的发件人规则、编码规则(单条消息为 160 个 GSM-7 字符或 70 个 Unicode 字符,最多 6 个部分)、计费点(消息在交给运营商时计费,已拒绝的消息绝不计费),以及从排队中到已送达的各种状态。选择取决于工作流程,与价格或质量无关。
决定选择的五个问题
| 问题 | 控制面板 | API |
|---|---|---|
| 由什么触发发送? | 一个人,拿着一份名单和一条消息 | 你系统中的一个事件:注册、订单、告警 |
| 号码存放在哪里? | 文件中:CSV、TXT 或 XLSX | 你的数据库中 |
| 谁来撰写文本? | 人工撰写,使用 {column} 占位符 | 你的代码,为每位收件人生成 |
| 何时必须发出? | 立即、在固定时刻,或在当地时间段内 | 事件发生后几秒内,或在 send_at 指定的时间 |
| 谁来读取结果? | 人,在实时报告中 | 你的系统,通过 Webhook |
答案分布在两侧很正常。这就是下文介绍的混合方式,也是大多数账户最终采用的方式。
控制面板何时更适合
一次群发任务就是一个文件、一段文本和一个日期。编辑器会完成原本需要脚本手动处理的工作:
- 导入。支持 CSV、TXT 或 XLSX,文件最大 50 MB,每个群发任务最多 1,000,000 个号码。号码会规范化为 E.164,本地格式可使用默认国家;规范化后合并重复项;无效行会列出,绝不发送,也绝不计费。
- 文本。支持
{first_name}等占位符;计数器会显示编码、分段数和渲染后最长的数据行,并指出导致切换为 Unicode 的字符,可一键替换弯引号、长破折号、省略号字符和特殊空格。 - 费用预览按目的地列出,在扣费之前显示。
- 时间安排。可以立即发送、在固定时刻发送,或在每个目的地的当地时间段内发送,时段内仍适用免打扰时段;可以按每分钟条数限速,或分散到若干小时内发送,并可暂停和恢复。
营销团队、客服团队以及每周只发送几次群发任务的用户,通常不需要更多功能。费率在群发任务的整个周期内锁定,因此分三天限速发送的任务,按预览时使用的费率计费。准备联系人名单指南详细介绍了导入流程。
API 何时更适合
验证码、告警、收据,以及由你系统中的事件触发的任何消息,都应通过 API 发送:每条消息一个请求,使用 Idempotency-Key 确保重试安全,使用 Webhook 让系统知道哪些消息已送达,并设置你自己的 reference,它会在响应和 Webhook 中原样返回。从自有数据管道群发时使用批量端点,每个请求最多 1,000 条消息。格式错误的请求会被整体拒绝;否则,无效条目会连同错误一起作为已拒绝返回,有效条目则进入队列,响应中会列出 batch_id、accepted、rejected、total_price 以及各条消息。关于批量拒绝还有更多内容。
与编辑器相比,有两点差异很重要。API 从不改写文本:它会返回 encoding 和 segments,编辑器原本会提示替换的弯撇号,需要你自己发现。另外,时间按每条消息设置:send_at 用于固定时刻,带当地开始和结束时间的 window 用于按当地时间送达,validity 决定消息可以等待多久;批量请求还可以设置 pace,按每分钟条数或分散到若干小时内发送。OpenAPI 描述以及 cURL、Python、Node、PHP 和 Go 的 SDK 示例能缩短首次集成的时间;请从快速入门开始。
同时使用两者
大多数账户都会这样做。以下是三种典型形态:
- 网店。订单确认和发货通知由订单系统通过 API 发出;每月促销则基于客户导出文件,从控制面板发送。
- 软件产品。登录验证码和故障告警通过 API 发送,各自使用独立的密钥;版本发布公告从控制面板发送。
- 诊所。次日的预约提醒每晚作为一个批次发出;临时停诊通知在发生时于控制面板中输入并发送。
三条规则能让它们互不干扰。为 API 消息设置 campaign 标签,使其在报告中像控制面板群发任务一样归组。每个系统使用独立密钥,撤销其中一个不会中断其他系统。还要约定由谁负责关注共用余额,避免失控的脚本拖住营销团队安排在明天的群发任务。
密钥、权限与允许名单
密钥是 Bearer 令牌:sk_live_ 用于真实流量,sk_test_ 用于开发。每个密钥的权限可以是发送、读取或两者兼具,也可以限制为 IP 允许名单;来自其他地址的请求会收到 401。没有单独的开发者套餐或审批步骤:从控制面板发送消息的同一个账户可以创建密钥,一分钟后就能从代码发送。
- 每个系统一个密钥。验证码服务、订单系统和报表任务各自持有自己的密钥。每秒 50 个请求的限制按密钥计算,因此群发任务不会耗尽验证码所需的额度。
- 最小权限。仪表板需要读取,通知程序需要发送,很少有系统两者都需要。
- 为固定地址设置允许名单。出站地址稳定的服务器应加入允许名单;对于地址会变化的函数,则依靠权限范围和谨慎的存储。
- 正式密钥只留在服务器上。随移动应用或网页分发的密钥任何人都能提取,因此请从后端发送。
- 先用测试密钥。它们会像正式密钥一样验证、计价和响应,返回测试状态并触发签名 Webhook,但不会发送任何消息,也不产生费用。
设置标签,让报告对齐
两个字段就能完成这项工作。campaign 最多 64 个字符,代表分组:标签相同的消息在报告中归在一起,就像一次控制面板群发任务。reference 最多 128 个字符,代表单条记录:你的订单号、预约 ID 或验证 ID,会在响应和 Webhook 中原样返回,让每个事件都能找到对应的记录。
- 按用途而不是日期命名群发任务:
otp-login、order-dispatched、reminder-24h。时间戳已经说明了时间。 - 每个需要比较的变体使用不同的标签,这样拆分测试在报告中会显示为两行。
- 两个字段都不要放入个人数据;内部 ID 已足够用于关联。
- 各团队一次性以书面形式约定名称,避免控制面板和 API 为同一类流量创建两个标签。
无论如何发送,报告都在一处
无论来自哪一侧,每条消息都会进入同一份送达报告:实时状态;失败按约十二种易懂原因归类,并附原始运营商代码;一键删除未知号码;可导出 CSV 或 JSON,包含消息 ID、号码、状态、运营商代码、时间戳和价格。from 字段始终显示实际使用的发件人,这在名称会被替换为号码的地方尤为重要。逐条消息记录保留 90 天,群发任务摘要永久保留;如果需要更长时间的消息级历史,请归档导出文件。
API 流量还多了一个实时视图:Webhook 会在每个状态变化时,把它推送到你自己的系统中,运营告警就应该放在这里。人读报告,系统读 Webhook。两者不能相互替代。
从一种方式迁移到另一种
如果每周都上传同一份导出文件,文本需要有人手动粘贴数据,或者发送应跟随事件而不是日历,就把控制面板上的例行任务迁移到 API。先用测试密钥,把上周的群发任务重建为批量请求,并在上线前将总价与控制面板的预览进行比较。
反过来,当有人要求开发者“把这个发给所有人就行”时,就该改用控制面板。一次性公告从费用预览、编码警告、当地时间段和暂停按钮中获得的帮助,远多于从仓促写成的脚本中获得的。
有内容不清楚或已经过时?请在支持页面告诉我们;修正内容会更新到指南中,同时更新修订日期。
