解读一次失败
失败消息包含两项信息:运营商返回的原始代码,以及我们映射出的易懂原因。原始代码因运营商而异;原因在各地保持一致,便于你据此采取行动。控制面板会按原因对失败分组,并在每个原因旁显示原始代码;导出文件中每条消息都带有运营商代码;API 的消息对象同时包含两者,即 failure_reason 和 carrier_code,旁边还有 created_at 和 sent_at 时间戳。你的系统会通过 message.failed Webhook 实时获知每次失败。
失败消息已交给运营商,只是运营商无法送达,因此会像任何发送尝试一样计费;发送前被我们拒绝的消息属于已拒绝,绝不计费。逐条消息记录保留 90 天,群发任务摘要永久保留;如果想在更长时间范围内比较失败情况,请导出明细。
消息可能停在哪里
任何时刻,一条消息都处于少数几种状态之一,状态之间的区别决定了你要付多少钱以及下一步该做什么。完整定义见 API 参考。
| 状态 | 含义 | 是否计费 |
|---|---|---|
| 排队中(queued) | 已接受,正在等待发送时间、发送时段或轮到它发送 | 暂未计费 |
| 已拒绝(rejected) | 发送前被拒绝,例如号码无效或内容被过滤器拦截 | 绝不计费 |
| 已发送(sent) | 已交给运营商 | 是,在此时计费 |
| 已送达(delivered) | 手机已确认收到 | 已在发送时计费 |
| 失败(failed) | 运营商无法送达;附有原因和代码 | 是,因为已经发送 |
| 已过期(expired) | 在送达前有效期已结束 | 是,只计一次 |
| 测试(test) | 使用测试密钥提交:经过验证和计价,从不发送 | 绝不计费 |
十二个原因
- 未知号码。该号码未分配给任何人:输错、从未发放或已注销。请删除它;它永远无法送达。报告可以一键从名单中删除所有未知号码。
- 用户不在线。手机关机或不在服务区,并且在网络于有效期(默认 48 小时)内尝试送达期间始终无法联系。可在之后的群发任务中重试。
- 手机或存储空间已满。手机拒收了消息,通常是因为存储空间不足。在现代手机上很少见;请稍后重试。
- 被运营商过滤器拦截。运营商标记了内容或发件人。检查该目的地的发件人规则,在严格路由上避免使用短链接,并重新检查文本中是否有网络钓鱼用语。
- 携号转网号码。号码已转至其他运营商,而消息发到了原运营商。携号转网数据会逐步更新;重试通常能够送达。
- 漫游期间无法联系。用户正在境外,所用网络不接受该消息。稍后重试,或接受本次损失。
- 用户线路受限。线路已暂停,通常是欠费所致。出现两次后删除该号码。
- 免打扰名单。设有全国登记制度的市场(例如印度和尼日利亚)会拦截发给登记号码的推广流量。事务性流量可以通过;营销流量不能。
- 发件人不适用于该路由。运营商拒绝了发件人本身。这种情况很少见,因为运营商拒绝名称时,消息会回退到数字发件人,报告也会注明。如果你看到这个原因,请将发件人与目的地国家或地区页面上的规则进行比较。
- 已过期。运营商持续重试期间,有效期已经结束。状态显示为已过期而非失败;不会二次计费。较短的有效期适合验证码,按设计会让这种结果更常见。
- 目的地无法访问。运营商范围的问题,通常会显示在状态页面上。等事件结束后再重新发送。
- 运营商拒绝但未提供原因。有些运营商对所有情况都只返回一个通用代码。路由每天都会根据实测送达效果进行审查;如果某家运营商反复出现该代码,请把几个消息 ID 发给客服。
删除、重试或更改
十二个原因可以归结为三种行动。
- 删除:未知号码立即删除,线路受限的号码在第二次出现后删除。再次向它们发送,只会换来更多失败。
- 稍后重试:适用于用户不在线、手机存储已满、漫游、携号转网、消息已过期和运营商故障。网络通常已经重试过,因此立即重发很少有帮助;请把这些号码纳入下一次群发任务,或者在消息很重要时于几小时后重发。
- 做出更改:适用于过滤器拦截、免打扰失败和发件人无效。同样的文本、同样的发件人、发给同样的号码,会以同样的方式失败:请更改发件人、措辞或受众。把促销重新标记为事务性并不是解决办法,会被视为滥用。
任何重发都是一条新消息,一旦交给运营商就会再次计费。这与重试一个超时的 API 请求不同:使用相同的 Idempotency-Key 重复该请求,你会拿回原始结果,而不会产生第二条消息。
在代码中处理失败
如果你通过 API 发送,请让 Webhook 驱动你的响应,而不是轮询。把自己的标识符放进 reference(最多 128 个字符,会在响应和 Webhook 中原样返回),这样每个 message.failed 事件都能直接对应到某个用户或订单。然后根据易懂原因分支处理,而不是根据因运营商而异的原始代码:
- 注册或验证码遇到未知号码:请用户检查输入的号码,而不是再提供一次重发。
- 紧急消息遇到临时性原因:暂停一段时间后提供一次重发,并限制尝试次数。
- 被过滤器拦截:通知人工处理。自动重发相同文本只会重复被拦截,而且每次都会计费。
无论如何,都要把 carrier_code 与事件一起保存。客服需要它来追查某家运营商上的模式。
值得采取行动的模式
单次失败只是噪声,占比才是信号。先按原因阅读失败情况,再按目的地和运营商阅读,然后与上次发给同一名单的结果进行比较。
- 未知号码占比上升说明名单正在老化。在报告中一键清理,然后查看这些号码的来源。
- 某家运营商的过滤占比上升说明内容或发件人在那里遭到标记:更换发件人类型或去掉短链接,然后在该网络的手机上再次测试。
- 失败集中在某一次导入,说明问题出在其来源:没有校验的表单、合作伙伴名单或旧的导出文件。
- 某国所有运营商的失败突然同时上升是路由问题,属于我们的职责:它会出现在状态页面上,通常在你发现之前。
想快速读完一整份报告,请参阅两分钟读懂送达报告。
预防可避免的失败
有几类失败可以在发送前阻止,而此时它们不会产生任何费用。
- 在导入时清理文件。导入器会将号码规范化为 E.164、合并重复项并列出无效行,这些行绝不会发送或计费。如果文件使用本地格式,请设置默认国家;其余内容请参阅准备联系人名单。
- 让发件人与目的地匹配。发件人 ID 指南解释了三类规则,以及每类规则在手机上显示什么。
- 按过滤器的标准撰写。品牌放在开头几个字,链接使用自己的域名,不要制造虚假紧迫感,不要模仿银行或运营商。
- 将有效期设为消息的有效寿命。验证码设为十分钟,因为过期后才送达的验证码只会变成客服工单;群发任务使用默认的 48 小时。
- 使用测试密钥集成。它会像正式密钥一样验证请求并计价,因此格式错误的号码会在任何消息发送或计费之前暴露出来。
哪些情况不算失败
已发送但没有已送达并不代表失败。大多数目的地会返回手机回执,但少数只返回运营商确认,在这些目的地,已发送就是最终的成功状态;有些运营商还会延迟返回回执或分批返回。国家或地区页面会说明适用哪种情况,送达报告页面则介绍了如何解读回执。已送达表示手机已收到消息,并不表示有人已经阅读。排队中表示正在按设计等待发送时段或发送时间。已拒绝同样不是失败:它是平台拒绝发送一条本会失败的消息,同时拒绝向你收费。
有内容不清楚或已经过时?请在支持页面告诉我们;修正内容会更新到指南中,同时更新修订日期。
