zavu-rules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zavu API Context

Zavu API 上下文

Zavu is a unified multi-channel messaging API. One API to send messages via SMS, WhatsApp, Telegram, Email, Instagram, and Voice with ML-powered intelligent routing.

Zavu是一款统一的多渠道消息API。通过一个API即可借助ML驱动的智能路由，发送短信（SMS）、WhatsApp、Telegram、邮件、Instagram及语音消息。

SDK Ecosystem

SDK生态系统

Language	Package	Install
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

语言	包	安装方式
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

TypeScript Init

TypeScript初始化

typescript

import Zavudev from '@zavudev/sdk';

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

typescript

import Zavudev from '@zavudev/sdk';

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

Python Init

Python初始化

python

import os
from zavudev import Zavudev

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

python

import os
from zavudev import Zavudev

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

Python Async

Python异步初始化

python

from zavudev import AsyncZavudev

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

python

from zavudev import AsyncZavudev

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

Go Init

Go初始化

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

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

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

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

Ruby Init

Ruby初始化

ruby

require "zavudev"

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

ruby

require "zavudev"

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

PHP Init

PHP初始化

php

use Zavudev\Client;

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

php

use Zavudev\Client;

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

Authentication

认证

Environment variable:
```
ZAVUDEV_API_KEY
```
Key prefixes:
```
zv_live_
```
(production),
```
zv_test_
```
(sandbox)
Header:
```
Authorization: Bearer <api_key>
```
Sender override header:
```
Zavu-Sender: <sender_id>
```

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

Core Conventions

核心约定

Phone numbers: Always E.164 format (
```
+14155551234
```
)

Channels:

auto

sms

sms_oneway

whatsapp

telegram

email

instagram

voice

Message types:

text

image

video

audio

document

sticker

location

contact

buttons

list

reaction

template

Pagination: Cursor-based. All list endpoints return
```
{ items: [...], nextCursor: string | null }
```
Idempotency: Use
```
idempotencyKey
```
on send to prevent duplicate messages

电话号码：始终采用E.164格式（
```
+14155551234
```
）

渠道：

auto

、

sms

、

sms_oneway

、

whatsapp

、

telegram

、

email

、

instagram

、

voice

消息类型：

text

、

image

、

video

、

audio

、

document

、

sticker

、

location

、

contact

、

buttons

、

list

、

reaction

、

template

分页：基于游标。所有列表接口返回
```
{ items: [...], nextCursor: string | null }
```
幂等性：发送消息时使用
```
idempotencyKey
```
防止重复发送

Error Handling

错误处理

TypeScript

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);
  }
}

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

python

from zavudev import Zavudev, APIError

try:
    zavu.messages.send(to="+14155551234", text="Hello")
except APIError as e:
    print(e.status_code, e.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)

Key Business Rules

核心业务规则

WhatsApp 24h window: Free-form messages require an open conversation window (user messaged you in last 24h). Use template messages to initiate conversations outside the window.
Email requires KYC: Complete identity verification in the dashboard before sending emails.
URL verification: SMS/email messages containing URLs require those URLs to be pre-verified via
```
/v1/urls
```
.
URL shorteners blocked: bit.ly, t.co, etc. are always blocked. Use full destination URLs.
Smart routing: Channel
```
auto
```
uses ML to pick the best channel based on cost, deliverability, and contact preferences.
Fallback: If WhatsApp fails, messages can automatically fall back to SMS (enabled by default).

WhatsApp 24小时窗口：自由格式消息要求对话窗口处于开放状态（用户在过去24小时内给您发过消息）。若超出该窗口，需使用模板消息发起对话。
邮件发送需完成KYC：在控制台完成身份验证后才能发送邮件。
URL验证：包含URL的短信/邮件消息，其URL需通过
```
/v1/urls
```
接口预先验证。
URL短链接被禁用：bit.ly、t.co等短链接工具始终被禁用，请使用完整目标URL。
智能路由：
```
auto
```
渠道会基于成本、送达率及联系人偏好，通过ML选择最优渠道。
降级策略：若WhatsApp发送失败，消息会自动降级为SMS发送（默认启用）。

MCP Server

MCP服务器

For direct API execution from AI assistants:

bash

claude mcp add --transport stdio zavudev_sdk_api \
  --env ZAVUDEV_API_KEY=$ZAVUDEV_API_KEY -- npx -y @zavudev/sdk-mcp

Tools available:

search_docs

(search API docs),

execute

(run TypeScript against authenticated client).

如需从AI助手直接执行API：

bash

claude mcp add --transport stdio zavudev_sdk_api \
  --env ZAVUDEV_API_KEY=$ZAVUDEV_API_KEY -- npx -y @zavudev/sdk-mcp

可用工具：

search_docs

（搜索API文档）、

execute

（通过已认证客户端运行TypeScript代码）。

CLI

The

zavudev/cli

package provides terminal access to all API operations.

zavudev/cli

包提供了所有API操作的终端访问能力。

Rate Limits

速率限制

Check

X-RateLimit-Remaining

header. Use

.withResponse()

(TS) or

.with_raw_response()

(Python) to access response headers.

查看

X-RateLimit-Remaining

请求头。使用

.withResponse()

（TypeScript）或

.with_raw_response()

（Python）获取响应头。

Message Statuses

消息状态

queued

sending

sent

delivered

read

(success path)

queued

sending

failed

(failure path)

received

(inbound messages)

pending_url_verification

(message with URLs awaiting verification)

queued

sending

sent

delivered

read

（成功路径）

queued

sending

failed

（失败路径）

received

（ inbound消息）

pending_url_verification

（包含待验证URL的消息）