Ruby SDK Overview

Official Zavu SDK for Ruby. Send SMS, WhatsApp, Email and Voice messages from Rails or any Ruby app with idiomatic helpers, retries and idempotency.

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: "[phone]",
  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: "[phone]",
  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: "[phone]",
  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: "[phone]",
      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