Authentication

API Keys

All API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer zv_live_xxxxxxxxxxxxxxxxxxxxxxxx

Key Types

Prefix	Environment	Usage
`zv_live_`	Production	Real messages, real costs
`zv_test_`	Sandbox	WhatsApp only, to your team’s own phones, from Zavu’s sandbox number

A test key delivers real messages. It does not simulate anything: the message goes to WhatsApp and arrives on the handset. What makes it safe is who it can reach, not whether it sends.A zv_test_ key ignores your senders entirely and sends WhatsApp from Zavu’s shared sandbox number, only to a phone belonging to someone on your team. Any other channel is refused with 400, an unlisted recipient with 403, and POST /v1/calls with 400. Use it to exercise the API before you have a WhatsApp Business Account of your own; use a zv_live_ key for everything else.See Sending limits.

Creating API Keys

Your account is created with a live key already in it. It is on the dashboard home, masked, with a button to show it and a button to copy it — there is nothing to create before your first call. To create another (one per machine, or one per environment):

Log in to your Zavu Dashboard
Navigate to API Keys
Click Create API Key
Give it a descriptive name (e.g., “Production Server”, “Development”)
Copy the key

A key can be shown again from the API Keys screen whenever you need it, so losing the tab you created it in does not lose the key. Keys created before this was possible are the exception: only their prefix is stored, and the way back is to create a new one. Revoking a key stops it authenticating and stops it being shown.

Using API Keys

In HTTP Requests

Include the key in the Authorization header:

curl https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

In SDKs

import Zavudev from '@zavudev/sdk';

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

import os
from zavudev import Zavudev

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

require "zavudev"

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

import (
	"os"
	"github.com/zavudev/sdk-go"
	"github.com/zavudev/sdk-go/option"
)

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

<?php
$client = new Zavudev\Client(apiKey: getenv('ZAVUDEV_API_KEY'));

Optional Headers

Header	Description	Example
`Zavu-Sender`	Override the default sender	`snd_abc123`
`Idempotency-Key`	Prevent duplicate sends	`order-12345-confirmation`

Zavu-Sender Header

Override the default sender for a specific request:

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Zavu-Sender: snd_abc123" \
  -H "Content-Type: application/json" \
  -d '{"to": "+56912345678", "text": "Hello!"}'

Idempotency Keys

Prevent duplicate message sends due to network retries:

curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+56912345678",
    "text": "Your order #12345 has shipped!",
    "idempotencyKey": "order-12345-shipped"
  }'

If you retry this request with the same idempotencyKey, you’ll receive a 409 Conflict with the original message instead of sending a duplicate.

Security Best Practices

Never expose your API keys in client-side code, public repositories, or browser applications.

Do’s

Store keys in environment variables
Use different keys for development and production
Rotate keys periodically (every 90 days recommended)
Use the minimum permissions needed
Monitor key usage in your dashboard

Don’ts

Don’t commit keys to version control
Don’t share keys via email or chat
Don’t use production keys in development
Don’t embed keys in mobile apps or frontends

Frontend Integration

The Zavu API uses secret API keys that must never be exposed in client-side code. If you include your key in a browser app, anyone can open DevTools and steal it. Instead, use the Backend-for-Frontend (BFF) pattern: your frontend calls your own server endpoint, and your server calls the Zavu API.

Server-side proxy examples

// app/api/send-message/route.ts
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev(); // reads ZAVUDEV_API_KEY from env

export async function POST(request: Request) {
  const { to, text } = await request.json();

  const result = await zavu.messages.send({ to, text });
  return Response.json(result);
}

import express from 'express';
import Zavudev from '@zavudev/sdk';

const app = express();
app.use(express.json());

const zavu = new Zavudev(); // reads ZAVUDEV_API_KEY from env

app.post('/api/send-message', async (req, res) => {
  const { to, text } = req.body;

  const result = await zavu.messages.send({ to, text });
  res.json(result);
});

from fastapi import FastAPI
from pydantic import BaseModel
from zavudev import Zavudev

app = FastAPI()
zavu = Zavudev()  # reads ZAVUDEV_API_KEY from env

class MessageRequest(BaseModel):
    to: str
    text: str

@app.post("/api/send-message")
async def send_message(req: MessageRequest):
    result = zavu.messages.send(to=req.to, text=req.text)
    return result

require "sinatra"
require "sinatra/json"
require "zavudev"

client = Zavudev::Client.new # reads ZAVUDEV_API_KEY from env

post "/api/send-message" do
  body = JSON.parse(request.body.read)
  result = client.messages.send_(to: body["to"], text: body["text"])
  json result
end

package main

import (
	"encoding/json"
	"net/http"

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

var client = zavudev.NewClient() // reads ZAVUDEV_API_KEY from env

func sendMessage(w http.ResponseWriter, r *http.Request) {
	var req struct {
		To   string `json:"to"`
		Text string `json:"text"`
	}
	json.NewDecoder(r.Body).Decode(&req)

	result, _ := client.Messages.Send(r.Context(), zavudev.MessageSendParams{
		To:   zavudev.String(req.To),
		Text: zavudev.String(req.Text),
	})
	json.NewEncoder(w).Encode(result)
}

func main() {
	http.HandleFunc("/api/send-message", sendMessage)
	http.ListenAndServe(":3000", nil)
}

<?php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

$client = new Zavudev\Client(); // reads ZAVUDEV_API_KEY from env

Route::post('/api/send-message', function (Request $request) use ($client) {
    $result = $client->messages->send([
        'to' => $request->input('to'),
        'text' => $request->input('text'),
    ]);
    return response()->json($result);
});

Frontend example

React

async function sendMessage(to: string, text: string) {
  const res = await fetch('/api/send-message', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ to, text }),
  });
  return res.json();
}

Add your own authentication and validation to the proxy endpoint. The examples above are simplified for clarity.

Key Permissions

API keys can be scoped to specific permissions:

Permission	Description
`*`	Full access to all resources
`messages:send`	Send messages
`messages:read`	Read message status and history
`templates:read`	Read templates
`templates:write`	Create and update templates
`contacts:read`	Read contact information
`contacts:write`	Create and update contacts

Revoking Keys

If a key is compromised:

Go to Settings → API Keys
Find the compromised key
Click Revoke
Create a new key
Update your applications

Revoked keys are immediately invalidated and cannot be restored.

Error Responses

Status	Error	Description
`401`	`unauthorized`	Missing or invalid API key
`403`	`forbidden`	Key lacks required permissions
`429`	`rate_limit_exceeded`	Too many requests

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Authentication

API Keys

Key Types

Creating API Keys

Using API Keys

In HTTP Requests

In SDKs

Optional Headers

Zavu-Sender Header

Idempotency Keys

Security Best Practices

Do’s

Don’ts

Frontend Integration

Server-side proxy examples

Frontend example

Key Permissions

Revoking Keys

Error Responses

​API Keys

​Key Types

​Creating API Keys

​Using API Keys

​In HTTP Requests

​In SDKs

​Optional Headers

​Zavu-Sender Header

​Idempotency Keys

​Security Best Practices

​Do’s

​Don’ts

​Frontend Integration

​Server-side proxy examples

​Frontend example

​Key Permissions

​Revoking Keys

​Error Responses

API Keys

Key Types

Creating API Keys

Using API Keys

In HTTP Requests

In SDKs

Optional Headers

Zavu-Sender Header

Idempotency Keys

Security Best Practices

Do’s

Don’ts

Frontend Integration

Server-side proxy examples

Frontend example

Key Permissions

Revoking Keys

Error Responses