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

# SDKs Overview

> Official Zavu SDKs for popular languages

<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="https://github.com/stainless-sdks/zavudev-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               | —             |

## 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}
  go install github.com/stainless-sdks/zavudev-cli/cmd/zavudev@latest
  ```
</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 CLI theme={null}
  zavudev messages send \
    --to "+14155551234" \
    --message-type template \
    --content.template-id tpl_abc123 \
    --content.template-variables.1 John \
    --content.template-variables.2 12345
  ```
</CodeGroup>

### Get Message Status

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

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

  ```ruby Ruby theme={null}
  result = client.messages.get(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->get(['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 from your terminal:

```bash theme={null}
# Install
go install github.com/stainless-sdks/zavudev-cli/cmd/zavudev@latest

# Set API key
export ZAVUDEV_API_KEY=zv_live_xxx

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

# List messages
zavudev messages list --limit 10

# Get help
zavudev --help
```