Zavu SDKs Overview

Server-side only — Zavu SDKs are designed for server-side environments (Node.js, Python, Ruby, Go, PHP). Never use them in browser/frontend code as this exposes your API key. See Frontend Integration for the proxy pattern.

Use our official SDKs to integrate Zavu into your application with minimal code.

Available SDKs

TypeScript

TypeScript/JavaScript SDK for Node.js

Python

Python SDK with sync and async support

Ruby

Ruby SDK for Rails, Sinatra, and more

Go

Go SDK with strong typing

PHP

PHP SDK for Laravel, Symfony, and more

CLI

Command-line interface for Zavu

Quick Comparison

Feature	TypeScript	Python	Ruby	Go	PHP
Package	`@zavudev/sdk`	`zavudev`	`zavudev`	`github.com/zavudev/sdk-go`	`zavudev/sdk`
Min Version	Node 18+	Python 3.9+	Ruby 3.0+	Go 1.21+	PHP 8.1+
Async	Native Promises	asyncio support	Threads	Goroutines	—
Types	Full TypeScript	Type hints	—	Strong typing	—

Coverage

The SDKs are generated from the API spec and do not all move at the same speed. TypeScript tracks the spec most closely. Before you build against a resource, check that your language has it.

Resource	TypeScript	Python	Ruby	Go	PHP
Messages, templates, senders, agents	Yes	Yes	Yes	Yes	Yes
Contacts, broadcasts, phone numbers	Yes	Yes	Yes	Yes	Yes
Introspect, addresses, regulatory documents	Yes	Yes	Yes	Yes	Yes
Invitations, URL verification, sub-accounts	Yes	No	Yes	No	No
Balance, account, functions, 10DLC	Yes	No	Yes	No	No
Voice calls	No	No	No	No	No

Nothing is blocked by a gap. Every endpoint is reachable over REST, and the CLI mirrors the API resource by resource. Where a page below shows a cURL or CLI tab instead of your language, that is why.

Installation

npm add @zavudev/sdk
# or
bun add @zavudev/sdk

pip install zavudev
# or
uv add zavudev

gem install zavudev
# or add to Gemfile
gem "zavudev"

go get github.com/zavudev/sdk-go

composer require zavudev/sdk

npx zavudev@latest --version
# or install it globally: npm install -g zavudev
# or grab a standalone binary from
# https://github.com/zavudev/zavu-cli/releases

Basic Usage

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'], // This is the default and can be omitted
});

const result = await zavu.messages.send({
  to: "+14155551234",
  text: "Hello from Zavu!",
});

console.log("Message ID:", result.message.id);

import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),  # This is the default and can be omitted
)

result = zavu.messages.send(
    to="+14155551234",
    text="Hello from Zavu!"
)

print(f"Message ID: {result.message.id}")

require "zavudev"

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

result = client.messages.send_(
  to: "+14155551234",
  text: "Hello from Zavu!"
)

puts "Message ID: #{result.message.id}"

package main

import (
	"context"
	"fmt"

	"github.com/zavudev/sdk-go"
	"github.com/zavudev/sdk-go/option"
)

func main() {
	client := zavudev.NewClient(
		option.WithAPIKey(os.Getenv("ZAVUDEV_API_KEY")),
	)

	result, err := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
		To:   zavudev.String("+14155551234"),
		Text: zavudev.String("Hello from Zavu!"),
	})
	if err != nil {
		panic(err)
	}

	fmt.Println("Message ID:", result.Message.ID)
}

<?php

use Zavudev\Client;

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

$result = $client->messages->send([
    'to' => '+14155551234',
    'text' => 'Hello from Zavu!',
]);

echo "Message ID: " . $result->message->id . "\n";

zavudev messages send --to "+14155551234" --text "Hello from Zavu!"

Common Operations

Send a Message

const result = await zavu.messages.send({
  to: "+14155551234",
  text: "Your code is 123456",
  channel: "sms",
});

result = zavu.messages.send(
    to="+14155551234",
    text="Your code is 123456",
    channel="sms"
)

result = client.messages.send_(
  to: "+14155551234",
  text: "Your code is 123456",
  channel: "sms"
)

result, err := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
    To:      zavudev.String("+14155551234"),
    Text:    zavudev.String("Your code is 123456"),
    Channel: zavudev.String("sms"),
})

$result = $client->messages->send([
    'to' => '+14155551234',
    'text' => 'Your code is 123456',
    'channel' => 'sms',
]);

zavudev messages send --to "+14155551234" --text "Your code is 123456" --channel sms

Send with Template

const result = await zavu.messages.send({
  to: "+14155551234",
  messageType: "template",
  content: {
    templateId: "tpl_abc123",
    templateVariables: {
      "1": "John",
      "2": "12345",
    },
  },
});

result = zavu.messages.send(
    to="+14155551234",
    message_type="template",
    content={
        "template_id": "tpl_abc123",
        "template_variables": {
            "1": "John",
            "2": "12345",
        },
    }
)

result = client.messages.send_(
  to: "+14155551234",
  message_type: "template",
  content: {
    template_id: "tpl_abc123",
    template_variables: {
      "1" => "John",
      "2" => "12345",
    },
  }
)

result, err := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
    To:          zavudev.String("+14155551234"),
    MessageType: zavudev.String("template"),
    Content: &zavudev.MessageContentParams{
        TemplateID: zavudev.String("tpl_abc123"),
        TemplateVariables: map[string]string{
            "1": "John",
            "2": "12345",
        },
    },
})

$result = $client->messages->send([
    'to' => '+14155551234',
    'messageType' => 'template',
    'content' => [
        'templateId' => 'tpl_abc123',
        'templateVariables' => [
            '1' => 'John',
            '2' => '12345',
        ],
    ],
]);

# `zavudev messages send` covers text on any channel. Template sends carry a
# nested `content` object, so use the API directly for those.
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "messageType": "template",
    "content": {
      "templateId": "tpl_abc123",
      "templateVariables": { "1": "John", "2": "12345" }
    }
  }'

Get Message Status

const result = await zavu.messages.retrieve("msg_abc123");
console.log("Status:", result.message.status);

result = zavu.messages.retrieve(message_id="msg_abc123")
print(f"Status: {result.message.status}")

result = client.messages.retrieve(message_id: "msg_abc123")
puts "Status: #{result.message.status}"

result, err := client.Messages.Get(context.TODO(), "msg_abc123")
fmt.Println("Status:", result.Message.Status)

$result = $client->messages->retrieve(['messageId' => 'msg_abc123']);
echo "Status: " . $result->message->status . "\n";

zavudev messages get msg_abc123

List Messages

const result = await zavu.messages.list({
  status: "delivered",
  limit: 50,
});

for (const message of result.items) {
  console.log(message.id);
}

result = zavu.messages.list(
    status="delivered",
    limit=50
)

for message in result.items:
    print(message.id)

result = client.messages.list(
  status: "delivered",
  limit: 50
)

result.items.each { |message| puts message.id }

result, err := client.Messages.List(context.TODO(), zavudev.MessageListParams{
    Status: zavudev.String("delivered"),
    Limit:  zavudev.Int(50),
})

for _, message := range result.Items {
    fmt.Println(message.ID)
}

$result = $client->messages->list([
    'status' => 'delivered',
    'limit' => 50,
]);

foreach ($result->items as $message) {
    echo $message->id . "\n";
}

zavudev messages list --status delivered --limit 50

Error Handling

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

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

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

import os
from zavudev import Zavudev, APIError

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

try:
    zavu.messages.send(to="invalid", text="Hello")
except APIError as e:
    print(f"API Error: {e.status_code} - {e.message}")

require "zavudev"

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

begin
  client.messages.send_(to: "invalid", text: "Hello")
rescue Zavudev::APIError => e
  puts "API Error: #{e.status} - #{e.message}"
end

result, err := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
    To:   zavudev.String("invalid"),
    Text: zavudev.String("Hello"),
})
if err != nil {
    var apiErr *zavudev.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("API Error: %d - %s\n", apiErr.StatusCode, apiErr.Message)
    }
}

use Zavudev\Client;
use Zavudev\APIError;

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

try {
    $client->messages->send(['to' => 'invalid', 'text' => 'Hello']);
} catch (APIError $e) {
    echo "API Error: " . $e->status . " - " . $e->getMessage() . "\n";
}

CLI

The Zavu CLI lets you interact with the API and deploy Zavu Functions from your terminal:

# No install needed: npx runs the current version
npx zavudev@latest --version

# Authenticate (opens browser, picks a project)
npx zavudev login

# Send a message
npx zavudev messages send --to "+14155551234" --text "Hello from CLI!"

# List messages
npx zavudev messages list --limit 10

# Get help
npx zavudev --help

Full reference: CLI reference.

Getting Started

Build agents

Send & receive

Operate

Developer tools

Zavu SDKs Overview

Available SDKs

TypeScript

Python

Ruby

Go

PHP

CLI

Quick Comparison

Coverage

Installation

Basic Usage

Common Operations

Send a Message

Send with Template

Get Message Status

List Messages

Error Handling

CLI

​Available SDKs

TypeScript

Python

Ruby

Go

PHP

CLI

​Quick Comparison

​Coverage

​Installation

​Basic Usage

​Common Operations

​Send a Message

​Send with Template

​Get Message Status

​List Messages

​Error Handling

​CLI

Available SDKs

Quick Comparison

Coverage

Installation

Basic Usage

Common Operations

Send a Message

Send with Template

Get Message Status

List Messages

Error Handling

CLI