Zavu API Context

SDK Ecosystem

@zavudev/sdk

npm add @zavudev/sdk

zavudev

pip install zavudev

github.com/zavudev/sdk-go

go get github.com/zavudev/sdk-go

zavudev/sdk-php

zavudev/sdk-ruby

TypeScript Init

import Zavudev from '@zavudev/sdk';

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

Python Init

import os
from zavudev import Zavudev

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

Python Async

from zavudev import AsyncZavudev

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

Go Init

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

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

Ruby Init

require "zavudev"

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

PHP Init

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>

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

Error Handling

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)

Key Business Rules

1. 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.
2. Email requires KYC: Complete identity verification in the dashboard before sending emails.
3. URL verification: SMS/email messages containing URLs require those URLs to be pre-verified via

   /v1/urls

   .
4. URL shorteners blocked: bit.ly, t.co, etc. are always blocked. Use full destination URLs.
5. Smart routing: Channel

   auto

   uses ML to pick the best channel based on cost, deliverability, and contact preferences.
6. Fallback: If WhatsApp fails, messages can automatically fall back to SMS (enabled by default).

MCP Server

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

search_docs

execute

CLI

zavudev/cli

Rate Limits

X-RateLimit-Remaining

.withResponse()

.with_raw_response()

Message Statuses

queued

sending

sent

delivered

read

queued

sending

failed

received

pending_url_verification