Ruby SDK Overview

Server-side only — This SDK is designed for server-side environments (Rails, Sinatra, background jobs). Never use it in browser/frontend code as this exposes your API key. See Frontend Integration for the proxy pattern.

Coverage. This SDK tracks the API closely. Voice calls are the one area not generated in any SDK yet: use the CLI or the REST API for those. Note that send is taken by Object#send in Ruby, so the generated method is messages.send_. See the coverage table.

The official Zavu SDK for Ruby provides an idiomatic Ruby interface to the Zavu API.

Installation

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

Requirements

Ruby 3.0 or higher

Quick Start

require "zavudev"

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

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

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

Configuration

Initialize the Client

require "zavudev"

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

# With custom base URL
client = Zavudev::Client.new(
  api_key: "zv_live_xxx",
  base_url: "https://api.zavu.dev"
)

Environment Variables

We recommend storing your API key in environment variables:

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

Accessing Response Headers

Use .with_raw_response to access the full HTTP response including headers (useful for rate limiting):

response = client.messages.send.with_raw_response(
  to: "+14155551234",
  text: "Hello!"
)

remaining = response.headers["X-RateLimit-Remaining"]
puts "Remaining requests: #{remaining}"

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

Error Handling

require "zavudev"

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

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

Error Types

Error Code	Description
`400`	Invalid request parameters
`401`	Invalid or missing API key
`403`	Insufficient permissions
`404`	Resource not found
`429`	Rate limit exceeded

Retries

The SDK supports automatic retries with configurable backoff:

client = Zavudev::Client.new(
  api_key: "zv_live_xxx",
  max_retries: 3
)

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

Thread Safety

The client is thread-safe and can be shared across threads:

# Create a single client instance
$zavu = Zavudev::Client.new(
  api_key: ENV["ZAVUDEV_API_KEY"]
)

# Safe to use from multiple threads
threads = 10.times.map do |i|
  Thread.new do
    $zavu.messages.send_(
      to: "+14155551234",
      text: "Message #{i}"
    )
  end
end

threads.each(&:join)

Rails Integration

# config/initializers/zavu.rb
require "zavudev"

ZAVU_CLIENT = Zavudev::Client.new(
  api_key: Rails.application.credentials.dig(:zavu, :api_key)
)

# app/services/notification_service.rb
class NotificationService
  def send_sms(phone_number, message)
    ZAVU_CLIENT.messages.send_(
      to: phone_number,
      text: message
    )
  end
end

​Installation

​Requirements

​Quick Start

​Configuration

​Initialize the Client

​Environment Variables

​Accessing Response Headers

​Error Handling

​Error Types

​Retries

​Thread Safety

​Rails Integration

Installation

Requirements

Quick Start

Configuration

Initialize the Client

Environment Variables

Accessing Response Headers

Error Handling

Error Types

Retries

Thread Safety

Rails Integration