viber官方对bot发送的主动消息（如broadcast_message）设定了严格的免费额度——每月仅10,000条，超出后将返回“maximum free messages from bot exceeded”错误（status 23），本文详解配额规则、验证方法及合规实践建议。
viber官方对bot发送的主动消息（如broadcast_message）设定了严格的免费额度——每月仅10,000条，超出后将返回“maximum free messages from bot exceeded”错误（status 23），本文详解配额规则、验证方法及合规实践建议。
在使用 Viber REST Bot API 进行批量消息推送（如调用 https://chatapi.viber.com/pa/broadcast_message）时，若突然收到如下响应：
{
"status": 23,
"status_message": "maximum free messages from Bot exceeded.",
"message_token": "5748679331176400537",
"chat_hostname": "SN-CHAT-02_"
}
这并非接口异常或认证失效，而是明确触发了 Viber 的月度免费消息配额上限。
? 核心规则：10,000 条/自然月（非滚动30天）
根据 Viber 官方技术文档（虽未在公开 API 文档首页显式标注，但在 Viber Business FAQ 及 Partner Portal 后台说明中确认）：
- 每个已认证的 Bot 账户享有 每月 10,000 条 chatbot-initiated messages（机器人主动发起的消息） 免费额度；
- “主动发起”特指：Bot 在用户未于24小时内发送新消息的前提下，通过
/broadcast_message、/send_message（withreceiver）等接口发起的推送； - 配额按自然月重置（即每月1日00:00 UTC 重置），不累计、不结转；
- 用户主动发起的会话内回复（within 24h window）不计入此配额，属“服务消息”范畴，无数量限制。
✅ 如何验证当前用量？
Viber 未提供公开的实时用量查询API，但可通过以下方式主动监控：
-
启用 Webhook 日志：在 Bot 设置中开启
message_status回调，记录每条成功发送消息的message_token和时间戳，本地聚合统计； -
服务端计数器：在调用
/broadcast_message前，维护一个 Redis 或数据库计数器，按YYYY-MM分桶累加发送量； - 检查 Partner Portal：登录 Viber Business Portal → Your Bot → Analytics → “Messages Sent”，部分企业级账户可见近30天趋势图（需开通高级分析权限）。
⚠️ 注意事项与最佳实践
- ❌ 不要依赖“分批发送”规避限制：即使拆分为 300 条/批次，只要当月累计超 10,000 条，后续请求仍会失败；
- ✅ 优先使用「事件驱动」替代广播：对订阅用户，引导其点击菜单按钮或关键词触发交互，利用 24 小时窗口期实现零成本触达；
- ✅ 合理规划广播节奏：例如将营销通知集中于每月上旬发送，预留缓冲量应对紧急通知；
- ? 若业务需更高频触达，须联系 Viber 商务团队开通付费套餐（按量计费，价格依区域与消息类型而异，通常 $0.005–$0.015/条）。
总结
Viber 的 10,000 条/月免费配额是硬性限制，而非临时策略。开发者应将其视为关键基础设施约束，在架构设计初期即纳入监控与降级方案（如自动切换至 WhatsApp/Telegram 备用通道）。忽视该限制将直接导致用户触达中断，影响运营连续性。务必定期审计消息日志，确保在配额耗尽前获得预警。
