Skip to main content
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.
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 CodeDescription
400Invalid request parameters
401Invalid or missing API key
403Insufficient permissions
404Resource not found
429Rate 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