zavu-rules

Zavu API コンテキスト

Zavu は統合型のマルチチャネルメッセージング API です。1 つの 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 エージェントとツールハンドラーをコード内で宣言できます。詳細については 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. 認証によって上限は引き上げられますが、送信許可が付与されるわけではありません：アカウントは、作成後すぐにすべてのチャネルから任意の送信先へメッセージを送信できます。本人確認、支払い方法の登録、デポジットの決済、または有料プランにより、1日の上限が引き上げられます。上限に達すると 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 に保留されます）。メール、WhatsApp、Telegram、Instagram、Messenger のメッセージは確認されません。
4. URL 短縮サービスはブロックされます：bit.ly、t.co などは常にブロックされます。完全な送信先 URL を使用してください。
5. チャネル auto：送信者が設定しているチャネルのうち、受信者のアドレスで受信できる最初のチャネルを、固定の優先順位に従って選択します。コストは考慮されません。コストに基づく連絡先ごとの選択は、チャネル smart で送信するブロードキャストでのみ利用できます。
6. フォールバック：WhatsApp で失敗した場合、テキストメッセージとテンプレートメッセージはSMSにフォールバックできます。Zavu がチャネルを選択する場合（channel を省略または auto に設定）はデフォルトで有効です。channel を明示的に設定した場合はデフォルトで無効ですが、fallbackEnabled: true にすると有効になります。
7. 音声エージェント：エージェントの 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 ヘッダーを確認してください。レスポンスヘッダーにアクセスするには、（TS）.withResponse() または（Python）.with_raw_response() を使用してください。

メッセージのステータス

queued -> sending -> sent -> delivered -> read（成功時） queued -> sending -> failed（失敗時） received（受信メッセージ） pending_url_verification（確認待ちの URL を含むメッセージ）