mcpField
C
channel-setup

channel-setup

github.com/zavudev开发179 次安装2 天前更新
代码仓库

关于 channel-setup

channel-setup 是面向 Zavu 集成的技能，帮助开发者将已连接的消息渠道接入代码，并确定发送请求使用的 sender ID。它说明账户与 sender 的区别、渠道能力判断及激活方式。

主要功能

  1. 01解释账户与 sender 的区别
  2. 02通过 GET /v1/senders 查询发送能力
  3. 03说明 Zavu-Sender 的选择方式
  4. 04介绍渠道激活与停用 API
  5. 05列出各渠道的 sender 配置方法

适用场景

  1. 01为发送请求选择 sender
  2. 02确认 sender 已启用的渠道
  3. 03将已连接的渠道接入 API

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/zavudev/zavu-skills --skill channel-setup

安装后在 Claude Code 中输入/channel-setup确认已加载。

详细介绍

通道设置

适用场景

当你要将刚连接的通道（WhatsApp、Telegram、Instagram、Messenger、电子邮件、电话号码）接入代码，或决定要向 API 传递哪个发送方 ID 时，请使用此技能。

两层模型

Zavu 有两个新手常会混淆的对象：

层级含义所在位置
账户与服务提供商的连接：WhatsApp Business 账户、Facebook 专页、Instagram 账户、Telegram 机器人、电子邮件域名、电话号码在控制面板中连接（Accounts、Phone Numbers），或通过合作伙伴邀请连接
发送方用于路由账户的 API 标识：作为 Zavu-Sender 传递的内容，也是承载 webhook 和 AI Agent 的对象GET /v1/senders

**计费：**你需要为账户付费（WhatsApp 账户、通道连接、电话号码）。发送方免费——它们是将账户归入同一发送身份的视图。

**连接后始终会生成一个可用的发送方。**连接账户后，如果没有发送方引用该账户，Zavu 会自动创建一个以账户命名的发送方（WhatsApp 验证名称、专页名称或 @username）。项目中的第一个发送方会成为默认发送方。通过合作伙伴邀请进行的连接一直都是如此；现在所有连接方式也都采用这种方式。

查找要用于发送的发送方

GET /v1/senders 可以回答“我能用什么发送，以及从哪里发送？”。每个发送方的 channels 数组是判断其能力的依据——它根据实际配置计算，而不是推断得出：

{
  "id": "sender_12345",
  "name": "Acme Store",
  "channels": ["whatsapp", "sms", "voice"],
  "isDefault": true
}
  • channels 数组为空，表示该发送方目前无法发送任何内容（仅有电话号码并不会启用 SMS）。
  • channels 仅列出已连接且已启用的通道。已连接但处于关闭状态的账户不会列出，因为通过它发送的内容都会被拒绝。
  • 没有电话号码的发送方不会包含 phoneNumber：例如仅支持电子邮件的发送方，或仅使用 enableSmsOneway 创建的发送方。不要假设每个发送方都有电话号码。
  • 省略 Zavu-Sender 即使用项目的默认发送方。
  • 如需指定某个发送方，请在发送参数对象中将其 ID 作为请求头传递：'Zavu-Sender': "sender_12345"。

启用已连接的通道

新连接的 WhatsApp 账户、Telegram 机器人、Instagram 账户、Messenger 专页或电子邮件地址，如果已包含在套餐中，会在能够承载消息后自动启用。需要额外付费的通道则会从一开始就处于未启用状态；在启用前，通过它发送的内容都会被拒绝，因为启用通道会对该连接计费（参见“限制”）。查看发送方的 channels，了解自己属于哪种情况。可在控制面板中操作（Accounts、Activate），也可通过 API 按发送方和通道启用：

curl -X POST https://api.zavu.dev/v1/senders/sender_12345/channels/telegram/activate \
  -H "Authorization: Bearer $ZAVU_API_KEY"

{
  "sender": { "id": "sender_12345", "channels": ["telegram"] },
  "channel": "telegram",
  "activated": true,
  "chargedCents": 300,
  "monthlyCents": 300
}
  • {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（嵌入式注册或邀请）自动创建；账户激活后，channels 会包含 whatsappchannel: "whatsapp"
Messenger 公共主页 / Instagram 账户自动创建，名称取自公共主页 / @用户名channel: "messenger" / "instagram"
Telegram 机器人通过 POST /v1/senders/{senderId}/telegram 关联（机器人令牌来自 @BotFather）channel: "telegram"
电子邮件域名（已验证）创建或更新发送方时，通过 emailAddress 关联channel: "email"
暂无（零配置即可开始）在 POST /v1/senders 或 PATCH /v1/senders/{senderId} 中设置 enableSmsOneway: true——无需号码或凭据，立即生效；收件人无法回复。向美国或加拿大的 (+1) 号码发送消息仍需获批的 10DLC 活动，与使用 sms 时一样channel: "sms_oneway"
电话号码将其路由至某个发送方（使用 senderId 执行 PATCH /v1/phone-numbers/{id}）——这样才会启用 SMS；添加 enableVoice 即可拨打电话channel: "sms" / "voice"

一个发送方可以同时承载多个渠道——这正是关键：一个 Zavu-Sender，涵盖所有渠道。

限制

  • 一个发送方只属于一个项目；一个账户最多只能路由到一个发送方。
  • Webhook 按发送方配置，并适用于该发送方承载的所有渠道。
  • AI Agent 按发送方关联，但只会响应其自身 triggerOnChannels 中指定的渠道。发送方收到的某个渠道若未列入该列表，消息会在 Agent 看到之前被丢弃——不会回复，也不会报错；Playground 仍会响应，因为它会绕过此筛选。丢弃记录可通过 GET /v1/senders/{senderId}/agent/executions 查看：返回结果中会包含该记录，且 status: "filtered"，errorMessage 中会注明渠道。除非你有意排除某个渠道，否则请使用 ["*"]。
  • 免费套餐包含两个连接名额（其中一个可以是 WhatsApp 账户）；付费套餐可按每个连接的月费增加连接。创建发送方始终免费。

评论

支持 Markdown