> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Zavu SDKs Overview

> Official Zavu SDKs for TypeScript, Python, Ruby, Go and PHP. Send SMS, WhatsApp, Email and Voice messages with one unified, well-typed API.

<Warning>
  **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](/authentication#frontend-integration) for the proxy pattern.
</Warning>

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

## Available SDKs

<CardGroup cols={3}>
  <Card title="TypeScript" icon="js" href="/sdks/typescript/overview">
    TypeScript/JavaScript SDK for Node.js
  </Card>

  <Card title="Python" icon="python" href="/sdks/python/overview">
    Python SDK with sync and async support
  </Card>

  <Card title="Ruby" icon="gem" href="/sdks/ruby/overview">
    Ruby SDK for Rails, Sinatra, and more
  </Card>

  <Card title="Go" icon="golang" href="/sdks/go/overview">
    Go SDK with strong typing
  </Card>

  <Card title="PHP" icon="php" href="/sdks/php/overview">
    PHP SDK for Laravel, Symfony, and more
  </Card>

  <Card title="CLI" icon="terminal" href="/guides/functions/cli">
    Command-line interface for Zavu
  </Card>
</CardGroup>

## 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  |

<Info>
  Nothing is blocked by a gap. Every endpoint is reachable over REST, and the
  [CLI](/guides/cli/overview) mirrors the API resource by resource. Where a page
  below shows a `cURL` or `CLI` tab instead of your language, that is why.
</Info>

## Installation

<CodeGroup>
  ```bash TypeScript theme={null}
  npm add @zavudev/sdk
  # or
  bun add @zavudev/sdk
  ```

  ```bash Python theme={null}
  pip install zavudev
  # or
  uv add zavudev
  ```

  ```bash Ruby theme={null}
  gem install zavudev
  # or add to Gemfile
  gem "zavudev"
  ```

  ```bash Go theme={null}
  go get github.com/zavudev/sdk-go
  ```

  ```bash PHP theme={null}
  composer require zavudev/sdk
  ```

  ```bash CLI theme={null}
  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
  ```
</CodeGroup>

## Basic Usage

<CodeGroup>
  ```typescript TypeScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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}")
  ```

  ```ruby Ruby theme={null}
  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}"
  ```

  ```go Go theme={null}
  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 PHP theme={null}
  <?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";
  ```

  ```bash CLI theme={null}
  zavudev messages send --to "+14155551234" --text "Hello from Zavu!"
  ```
</CodeGroup>

## Common Operations

### Send a Message

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await zavu.messages.send({
    to: "+14155551234",
    text: "Your code is 123456",
    channel: "sms",
  });
  ```

  ```python Python theme={null}
  result = zavu.messages.send(
      to="+14155551234",
      text="Your code is 123456",
      channel="sms"
  )
  ```

  ```ruby Ruby theme={null}
  result = client.messages.send_(
    to: "+14155551234",
    text: "Your code is 123456",
    channel: "sms"
  )
  ```

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

  ```php PHP theme={null}
  $result = $client->messages->send([
      'to' => '+14155551234',
      'text' => 'Your code is 123456',
      'channel' => 'sms',
  ]);
  ```

  ```bash CLI theme={null}
  zavudev messages send --to "+14155551234" --text "Your code is 123456" --channel sms
  ```
</CodeGroup>

### Send with Template

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await zavu.messages.send({
    to: "+14155551234",
    messageType: "template",
    content: {
      templateId: "tpl_abc123",
      templateVariables: {
        "1": "John",
        "2": "12345",
      },
    },
  });
  ```

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

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

  ```go Go theme={null}
  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",
          },
      },
  })
  ```

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

  ```bash cURL theme={null}
  # `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" }
      }
    }'
  ```
</CodeGroup>

### Get Message Status

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await zavu.messages.retrieve("msg_abc123");
  console.log("Status:", result.message.status);
  ```

  ```python Python theme={null}
  result = zavu.messages.retrieve(message_id="msg_abc123")
  print(f"Status: {result.message.status}")
  ```

  ```ruby Ruby theme={null}
  result = client.messages.retrieve(message_id: "msg_abc123")
  puts "Status: #{result.message.status}"
  ```

  ```go Go theme={null}
  result, err := client.Messages.Get(context.TODO(), "msg_abc123")
  fmt.Println("Status:", result.Message.Status)
  ```

  ```php PHP theme={null}
  $result = $client->messages->retrieve(['messageId' => 'msg_abc123']);
  echo "Status: " . $result->message->status . "\n";
  ```

  ```bash CLI theme={null}
  zavudev messages get msg_abc123
  ```
</CodeGroup>

### List Messages

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await zavu.messages.list({
    status: "delivered",
    limit: 50,
  });

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

  ```python Python theme={null}
  result = zavu.messages.list(
      status="delivered",
      limit=50
  )

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

  ```ruby Ruby theme={null}
  result = client.messages.list(
    status: "delivered",
    limit: 50
  )

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

  ```go Go theme={null}
  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)
  }
  ```

  ```php PHP theme={null}
  $result = $client->messages->list([
      'status' => 'delivered',
      'limit' => 50,
  ]);

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

  ```bash CLI theme={null}
  zavudev messages list --status delivered --limit 50
  ```
</CodeGroup>

## Error Handling

<CodeGroup>
  ```typescript TypeScript theme={null}
  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);
    }
  }
  ```

  ```python Python theme={null}
  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}")
  ```

  ```ruby Ruby theme={null}
  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
  ```

  ```go Go theme={null}
  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)
      }
  }
  ```

  ```php PHP theme={null}
  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";
  }
  ```
</CodeGroup>

## CLI

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

```bash theme={null}
# 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](/guides/functions/cli).