套餐与配额

成本口径：先分清两笔钱

接入 Whaleal SMS 会涉及两笔完全独立的费用，务必先跟团队对齐，避免对外说错：

费用	付给谁	怎么算
短信费	底层供应商（Twilio / Vonage / Infobip…）	由供应商直接按你自己的账号资费计费。平台不经手、不加价、不抽成
平台订阅费	Whaleal SMS	按渠道数档位收，不按短信条数

也就是说：平台没有「按条平台税」。你发 1 万条还是 100 万条，订阅费不变 —— 分档差异只在渠道数、提交速率和日志保留期。

四档套餐

档位	月付	年付	渠道数	提交速率	日志保留	发送量
免费版 FREE	$0	$0	1	10 QPS	7 天	不限
成长版 GROWTH	$19	$180	3	50 QPS	7 天	不限
专业版 PRO	$49	$480	10	100 QPS	30 天	不限
旗舰版 ULTRA	$199	$2,000	不限	500 QPS	90 天	不限

• 年付约省两个月；付费走 Stripe Checkout，支持国际信用卡（Visa / Mastercard / Amex 等）
• 免费版不是试用版，是长期可用的档位（1 条渠道 / 10 QPS），适合个人项目与产品评估
• 所有档位发送量均不限量、不设软上限、没有超额账单；服务条款中的公平使用政策只约束滥用行为

档位与配额的权威真值是平台后端配置。任何文档、报价单上的数字与该配置冲突时，以配置为准。

渠道数怎么算

按供应商账户数计，不按号码数计。

同一家账号下的多个发信号码（Sender）也只算 1 条渠道 —— 这些 Sender 会全部参与平台的加权轮询。所以：

• Twilio 一个账号 + 5 个号码 = 1 条渠道
• Twilio + Vonage + 阿里云 = 3 条渠道（成长版够用）

超出档位上限时无法再添加渠道，需要先升级。

提交速率（QPS）

限速是租户级的，单发、批量、定时任务、开放 API 统一计入同一个池子，按固定 1 秒窗口计数。

档位	QPS
FREE	10
GROWTH	50
PRO	100
ULTRA	500

超限返回 HTTP 429 + code = 42900，客户端要做指数退避重试。

除套餐限速外，网关还有一层按客户端 IP 的兜底限流，同样返回 429 + 42900，但 msg 以 edge rate limit exceeded 开头。看到这个前缀说明是边缘层拦的（异常流量保护），不是你的套餐用满了 —— 这两者要分开排查。

工程建议：客户端自己做一层令牌桶，把速率压在档位之下，而不是靠撞 429 来限速。批量发送时按 1000 / QPS 秒的间隔发包，或并用一个并发受控的发送队列。

用量对账：两个口径必然不等

curl https://smsapi.whaleal.com/open/v1/usage \
  -H "Authorization: Bearer sk_xxxxxxxx"

字段	回答的问题	用途
messageCount	我提交了几次请求	排障、对账"业务侧发了几单"
billedSegments	账单上有几条	预算控制、与供应商账单核对

这两个数一定不等，原因有三：

1. 长短信分段 —— 超过单条长度的短信，一条会算多条（segments 大于 1）
2. 未受理不计费 —— providerMessageId 为 null 的提交未真正发出，不计入 billedSegments
3. 编码口径 —— 不同编码（GSM7 / UCS2 / UTF8 / GBK）的单条容量不同，同样长度的文案分段数不同

对账的正确姿势：

1. 业务侧落库每次发送的 messageId、encoding、segments
2. 用 billedSegments 与供应商账单核对（这才是真正的钱）
3. 用 messageCount 与业务系统发送次数核对（确认没有丢发）
4. 两个数差异大 → 去看是不是长短信占比高、或大量提交未被供应商受理

为什么要靠平台回传的 encoding / segments，而不是自己算？ 因为平台不存正文，你可以自己写一个分段计算器 —— 但你的计算器要与各家供应商的实际口径完全一致才算得对，而这正是容易出错的地方。发送响应与状态回调里回传的值，就是这条实际生效的口径。

升级、降级与宽限

操作	生效时间
升级	立即生效
降级 / 取消	当前计费周期结束时生效，到期前可继续使用原套餐
扣款失败	有 7 天宽限期；宽限期后冻结配额

降级前请先确认渠道数不会超出目标档位上限，否则多余渠道无法保留。

怎么选档位

你的情况	建议
评估、个人项目、只有一家通道	FREE（1 渠道 / 10 QPS）
生产环境双通道灾备（主 + 备）	GROWTH（3 渠道够用）
多业务线 + 多渠道，或需要 30 天日志	PRO
渠道数超过 10、需要高提交速率或 90 天日志	ULTRA

不确定的话，从 FREE 开始 —— 加渠道才需要升级，发信量不影响。

---

上一篇：状态回调接入 · 下一篇：常见问题