viber 官方对 bot 的免费消息额度设为每月 10,000 条 chatbot-initiated 消息（含 broadcast_message），超出后将返回 status=23 错误；该限制未在公开文档显式标注，但已在 viber 商业条款中明确说明。
viber 官方对 bot 的免费消息额度设为每月 10,000 条 chatbot-initiated 消息（含 broadcast_message），超出后将返回 status=23 错误；该限制未在公开文档显式标注，但已在 viber 商业条款中明确说明。
在使用 Viber REST Bot API 进行大规模消息分发（如 /pa/broadcast_message 接口）时，开发者常遇到如下响应：
{
"status": 23,
"status_message": "maximum free messages from Bot exceeded.",
"message_token": "5748679331176400537",
"chat_hostname": "SN-CHAT-02_"
}
该错误并非临时故障或调用频率问题，而是触达了 Viber 对 Bot 账户的月度免费消息配额上限——即每个 Bot 在每个自然月内最多可免费发送 10,000 条由 Bot 主动发起的消息（chatbot-initiated messages），涵盖：
-
broadcast_message（群发） -
postback响应（非用户触发的主动推送） -
text,rich_media,keyboard等任意类型主动下发消息
⚠️ 注意事项：
- ✅ 配额按日历月（1–31 日）重置，非滚动 30 天；
- ❌ 用户主动发送的消息（如用户点击菜单、输入文本触发的 reply）不计入此配额；
- ❌ 消息是否成功送达不影响计数——只要 API 调用成功返回
status=0或有效message_token，即视为已消耗 1 条配额； - ? Viber 未提供实时配额查询接口，需自行记录每月发送总量（建议在服务端持久化
sent_count+reset_date）； - ? 若需更高频触达，须联系 Viber 商务团队开通付费通道（按量计费，价格依区域与合约而定）。
示例：统计本月已发送消息数（伪代码，建议集成至消息网关层）
# 假设使用 Redis 记录
import redis
r = redis.Redis()
def increment_monthly_counter(bot_id: str) -> int:
key = f"viber:quota:{bot_id}:{datetime.now().strftime('%Y-%m')}"
return r.incr(key)
# 发送前校验
current = increment_monthly_counter("your_bot_id")
if current > 10000:
raise Exception("Monthly free quota exhausted. Switch to paid plan or wait for reset.")
总结：虽然 Viber 开发者文档尚未在 /broadcast_message 页面明示该限制，但其《Terms & Conditions》及商务支持口径均确认 10,000 条/月为默认免费阈值。建议所有生产级 Bot 项目将配额管理纳入基础监控体系，避免突发性发送失败影响用户触达体验。
