用途:在把新接入的渠道(WhatsApp、Telegram、Instagram、Messenger、邮箱、电话号码)接入代码时,或需要决定向 API 传哪个 sender ID 时使用本技能。
两层模型:Account 是与服务商的连接(WhatsApp Business 账户、Facebook 主页、Instagram 账户、Telegram 机器人、邮箱域名、电话号码),在仪表盘或通过合作伙伴邀请连接;Sender 是路由账户的 API 句柄,即 Zavu-Sender 的值,承载 webhook 与 AI 智能体,通过 GET /v1/senders 获取。计费针对账户(WhatsApp 账户、渠道连接、电话号码),Sender 免费。连接账户后会自动生成一个以其命名的 Sender,项目首个 Sender 成为默认。
查找发送者:GET /v1/senders 返回每个 Sender 的 channels 数组,表示实际可用的渠道;空数组表示尚不能发送。省略 Zavu-Sender 使用默认 Sender,指定时在发送参数对象中传 'Zavu-Sender': "sender_12345"。
激活渠道:计划已包含的渠道连接后自动启用;会产生费用的渠道默认不激活,发送会被拒绝,需在仪表盘或通过 API 激活,例如:curl -X POST https://api.zavu.dev/v1/senders/sender_12345/channels/telegram/activate -H "Authorization: Bearer $ZAVU_API_KEY"。{channel} 可为 whatsapp、telegram、instagram、messenger、email;SMS、单向 SMS 和语音按条计费,无需激活(返回 400)。chargedCents 表示本次扣费,重复调用不会重复收费。错误包括 402 insufficient_balance、403 plan_limit_reached、409 channel_not_connected、409 connection_not_ready。POST /v1/senders/{senderId}/channels/{channel}/deactivate 可关闭渠道而不断开账户,已付月份不退款,当月重新激活免费。仅支持正式 API 密钥。
各渠道接线:WhatsApp 自动创建;Messenger/Instagram 自动创建;Telegram 通过 POST /v1/senders/{senderId}/telegram 附加机器人令牌;邮箱域名用 emailAddress 附加;零配置可用 enableSmsOneway: true 启用单向 SMS(收件人无法回复,发往 +1 号码仍需 10DLC 活动);电话号码通过 PATCH /v1/phone-numbers/{id} 传 senderId 路由以启用 SMS,加 enableVoice 启用语音。一个 Sender 可同时承载多个渠道。
限制:Sender 属于单个项目,账户最多被一个 Sender 路由;webhook 按 Sender 配置并作用于其所有渠道;AI 智能体按 Sender 附加,但只响应 triggerOnChannels 中列出的渠道,未列出的渠道消息会被丢弃(记录为 status: "filtered"),除非有意排除否则用 ["*"]。免费计划含两个连接槽(其中一个可为 WhatsApp 账户),付费计划按连接每月收费,创建 Sender 不收费。