zavu-rules

Zavu API 上下文

Zavu 是一个统一的多渠道消息 API。通过一个 API，即可通过 SMS、WhatsApp、Telegram、Email、Instagram 和 Voice 发送消息，并自动选择渠道和进行故障回退。

SDK 生态系统

语言	软件包	安装
TypeScript	@zavudev/sdk	npm add @zavudev/sdk
Python	zavudev	pip install zavudev
Go	github.com/zavudev/sdk-go	go get github.com/zavudev/sdk-go
PHP	zavudev/sdk-php	Composer
Ruby	zavudev/sdk-ruby	RubyGems

工具

工具	用途	安装
zavu CLI	从终端与 API 交互；管理 Zavu Functions（在 Zavu Cloud 上运行的无服务器 TypeScript）	npx zavudev@latest（无需安装），或 npm install -g zavudev
@zavudev/functions	Zavu Functions 的运行时软件包。提供 defineAgent、defineTool、defineFunction 声明式 API。	已预装在函数运行时中 — import { defineAgent } from "@zavudev/functions"（无需安装）。

CLI 是 Zavu Functions 的主要接口：运行在 Zavu Cloud 上的无服务器 TypeScript，可让你在代码中声明 AI Agent 和工具处理程序。完整内容请参阅 functions 技能。

TypeScript 初始化

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'],
});

Python 初始化

import os
from zavudev import Zavudev

zavu = Zavudev(api_key=os.environ.get("ZAVUDEV_API_KEY"))

Python 异步

from zavudev import AsyncZavudev

zavu = AsyncZavudev(api_key=os.environ.get("ZAVUDEV_API_KEY"))

Go 初始化

import "github.com/zavudev/sdk-go"

client := zavudev.NewClient(os.Getenv("ZAVUDEV_API_KEY"))

Ruby 初始化

require "zavudev"

client = Zavudev::Client.new(api_key: ENV["ZAVUDEV_API_KEY"])

PHP 初始化

use Zavudev\Client;

$client = new Client(apiKey: getenv('ZAVUDEV_API_KEY'));

身份验证

• 环境变量：ZAVUDEV_API_KEY
• 密钥前缀：zv_live_（生产环境）、zv_test_（沙盒）
• 标头：Authorization: Bearer <api_key>
• 发送方覆盖标头：Zavu-Sender: <sender_id>

核心约定

• 电话号码：始终使用 E.164 格式（+14155551234）
• 渠道：auto、sms、sms_oneway、whatsapp、telegram、email、instagram、messenger、voice
• 消息类型：text、image、video、audio、document、sticker、location、contact、buttons、list、cta_url、request_contact_info、location_request、reaction、template
• 分页：基于游标。所有列表端点均返回 { items: [...], nextCursor: string | null }
• 幂等性：发送消息时使用 idempotencyKey，以防止重复发送

错误处理

TypeScript

import Zavudev, { APIError } from '@zavudev/sdk';

try {
  await zavu.messages.send({ to: "+14155551234", text: "Hello" });
} catch (error) {
  if (error instanceof APIError) {
    console.error(error.status, error.message);
  }
}

Python

from zavudev import Zavudev, APIError

try:
    zavu.messages.send(to="+14155551234", text="Hello")
except APIError as e:
    print(e.status_code, e.message)

核心业务规则

1. WhatsApp 24 小时窗口：发送自由格式消息需要对话窗口处于开放状态（用户在过去 24 小时内给你发过消息）。若要在窗口关闭后发起对话，请使用模板消息。
2. 验证可提高限额，但并非发送许可：账户从开通的第一分钟起就可以通过所有渠道向任意目的地发送消息。身份验证、已保存的付款方式、已结算的押金或付费套餐会提高每日限额；额度用尽后会返回 429 daily_limit_exceeded。商业验证（KYB）是注册 10DLC 的前提，而所有美国和加拿大（+1）SMS 目的地都需要注册 10DLC（403 ten_dlc_required）；发送消息不需要任何渠道具备此条件，sms_oneway 也不例外。发送前会读取每条 sms、sms_oneway、email 和 voice 消息，并可能短暂暂缓审核（状态仍为 queued）或拒绝（失败消息上显示 RISK_BLOCKED、RISK_REJECTED、RISK_REVIEW_EXPIRED）；反复遭拒会导致账户发送功能被停用（403 sending_suspended）。请参阅 send-message 技能。
3. URL 验证：包含 URL 的 SMS、单向 SMS 和语音消息必须先验证 URL（通过 /v1/urls 预先验证；未知 URL 会使消息处于 pending_url_verification 状态，等待检查）。Email、WhatsApp、Telegram、Instagram 和 Messenger 消息不会接受检查。
4. 屏蔽 URL 缩短服务：bit.ly、t.co 等始终会被屏蔽。请使用完整的目标 URL。
5. 渠道 auto：按固定的优先顺序，选择发送方已配置且接收方地址可接收消息的第一个渠道。此模式不考虑费用。仅当广播使用渠道 smart 发送时，才会按联系人进行基于费用的渠道选择。
6. 回退：如果 WhatsApp 发送失败，文本消息和模板消息可以回退到 SMS。当 Zavu 选择渠道时（未指定 channel 或设为 auto），默认开启；显式设置 channel 时，默认关闭，除非设置 fallbackEnabled: true。
7. 语音 Agent：当 Agent 的 voice 配置中 enabled: true 时，可以接听和拨打电话。通过 /v1/calls 发起外呼，并从 /v1/calls/{callId} 获取转录内容。需要有效密钥。请参阅 ai-agent 技能。

MCP 服务

用于从 AI 助手直接执行 API：

claude mcp add zavudev --scope user \
  -e ZAVUDEV_API_KEY=$ZAVUDEV_API_KEY -- npx -y @zavudev/sdk-mcp

可用工具：search_docs（搜索 API 文档）、execute（通过已验证的客户端运行 TypeScript）。

CLI

zavudev/cli 软件包提供对所有 API 操作的终端访问。

速率限制

检查 X-RateLimit-Remaining 标头。使用 .withResponse()（TS）或 .with_raw_response()（Python）访问响应标头。

消息状态

queued -> sending -> sent -> delivered -> read（成功路径） queued -> sending -> failed（失败路径） received（入站消息） pending_url_verification（包含 URL、等待验证的消息）