Skip to main content

Ruby SDK

The official Audian SDK for Ruby.

Installation​

Add to your Gemfile:

gem 'audian-ruby'

Then run:

bundle install

Or install directly:

gem install audian-ruby

Quick Start​

require 'audian'

client = Audian::Client.new(api_key: 'YOUR_API_KEY')

# Search for phone numbers
numbers = client.numbers.search(location: 'US-CA-415', limit: 10)

puts numbers

Configuration​

Initialize Client​

client = Audian::Client.new(
  api_key: 'sk_live_...',
  base_url: 'https://api.audian.com:8443/v2', # Optional
  timeout: 30, # Optional, seconds
  max_retries: 3, # Optional
  backoff_factor: 2 # Optional
)

Environment Variables​

export AUDIAN_API_KEY='sk_live_...'
client = Audian::Client.new(api_key: ENV['AUDIAN_API_KEY'])

Phone Numbers API​

Search Numbers​

response = client.numbers.search(
  location: 'US-CA-415',
  pattern: '415*',
  features: ['sms', 'mms'],
  limit: 20,
  offset: 0
)

response['data']['numbers'].each do |number|
  puts "#{number['number']} - $#{number['price']['monthly']}/month"
end

List Your Numbers​

response = client.numbers.list(
  limit: 20,
  offset: 0,
  status: 'active'
)

response['data']['numbers'].each do |number|
  puts "#{number['number']}: #{number['friendly_name']}"
end

Get Number Details​

number = client.numbers.get('num_abc123')
puts "Status: #{number['data']['status']}"

Purchase a Number​

purchased = client.numbers.purchase(
  number: '+14155551234',
  friendly_name: 'Support Line'
)

puts "Purchased: #{purchased['data']['number']}"

Update Number Configuration​

updated = client.numbers.update_config(
  'num_abc123',
  friendly_name: 'Support Line',
  call_forwarding: {
    enabled: true,
    forward_to: '+14155559999',
    rings_before_forward: 4
  },
  voicemail: {
    enabled: true,
    transcription: true
  }
)

Set Caller ID​

caller_id = client.numbers.set_caller_id(
  'num_abc123',
  caller_id_number: '+14155551234',
  caller_id_name: 'Support'
)

Configure E911​

e911 = client.numbers.set_e911(
  'num_abc123',
  address_line_1: '123 Main Street',
  address_line_2: 'Suite 100',
  city: 'San Francisco',
  state: 'CA',
  postal_code: '94102',
  country: 'US',
  customer_name: 'Acme Corp'
)

SMS API​

Send SMS​

response = client.sms.send(
  to: '+14155551234',
  from: '+14155559999',
  message: 'Hello, World!'
)

puts "SMS ID: #{response['data']['id']}"
puts "Status: #{response['data']['status']}"

Send Batch SMS​

response = client.sms.send_batch(
  messages: [
    { to: '+14155551234', message: 'Hello 1' },
    { to: '+14155551235', message: 'Hello 2' },
    { to: '+14155551236', message: 'Hello 3' }
  ]
)

puts "Sent #{response['data']['messages'].length} SMS"

Get SMS Details​

sms = client.sms.get('sms_abc123')
puts "Status: #{sms['data']['status']}"

List SMS Messages​

messages = client.sms.list(
  limit: 20,
  offset: 0,
  status: 'delivered'
)

messages['data']['messages'].each do |message|
  puts "To: #{message['to']} - Status: #{message['status']}"
end

Voice API​

Make a Call​

call = client.voice.make_call(
  to: '+14155551234',
  from: '+14155559999',
  action: 'connect',
  connect_to: '+14155559999'
)

puts "Call ID: #{call['data']['id']}"

Get Call Details​

call = client.voice.get_call('call_abc123')
puts "Duration: #{call['data']['duration']}s"

List Calls​

calls = client.voice.list_calls(
  limit: 20,
  status: 'completed'
)

Billing API​

Get Usage​

usage = client.billing.usage.get

sms_cost = usage['data']['usage']['sms_messages']['cost']
voice_cost = usage['data']['usage']['voice_minutes']['cost']
phone_cost = usage['data']['usage']['phone_numbers']['monthly_cost']

puts "SMS: $#{sms_cost}"
puts "Voice: $#{voice_cost}"
puts "Phone Numbers: $#{phone_cost}"

Get Usage Breakdown​

breakdown = client.billing.usage.get_breakdown(
  metric: 'sms',
  granularity: 'day'
)

breakdown['data']['breakdown'].each do |item|
  puts "#{item['date']}: #{item['count']} SMS - $#{item['cost']}"
end

List Invoices​

invoices = client.billing.invoices.list(
  status: 'paid',
  limit: 20
)

invoices['data']['invoices'].each do |invoice|
  puts "#{invoice['invoice_number']}: $#{invoice['amount']}"
end

Get Invoice​

invoice = client.billing.invoices.get('inv_abc123')
puts "Total: $#{invoice['data']['total']}"

Download Invoice PDF​

pdf = client.billing.invoices.get_pdf('inv_abc123')

File.write('invoice.pdf', pdf)

Error Handling​

begin
  client.numbers.purchase(number: '+14155551234')
rescue Audian::Error => e
  puts "Error: #{e.message}"
  puts "Code: #{e.code}"
  puts "Status: #{e.status}"
rescue StandardError => e
  puts "Unexpected error: #{e.message}"
end

Rate Limiting​

The SDK automatically handles rate limiting:

# Automatically retries with exponential backoff
numbers = client.numbers.search(location: 'US-CA-415')

Custom Retry Configuration​

client = Audian::Client.new(
  api_key: 'YOUR_API_KEY',
  max_retries: 5,
  backoff_factor: 2,
  initial_retry_delay: 0.1
)

Monitor Rate Limit Headers​

response = client.numbers.list

limit = response.headers['RateLimit-Limit']
remaining = response.headers['RateLimit-Remaining']
reset = response.headers['RateLimit-Reset']

puts "Limit: #{limit}"
puts "Remaining: #{remaining}"

Webhooks​

Verify Webhook Signature​

require 'audian/webhook'

verifier = Audian::WebhookVerifier.new(signing_secret: 'whsec_...')

post '/webhook' do
  begin
    event = verifier.verify(request.body.read, request.env['HTTP_X_AUDIAN_SIGNATURE'])
    puts "Event type: #{event['type']}"
    { success: true }.to_json
  rescue Audian::WebhookVerificationError => e
    status 401
    { error: e.message }.to_json
  end
end

Handle Webhook Events​

post '/webhook' do
  event = verifier.verify(request.body.read, request.env['HTTP_X_AUDIAN_SIGNATURE'])

  case event['type']
  when 'sms.received'
    puts "SMS from #{event['data']['from']}: #{event['data']['message']}"

  when 'call.completed'
    puts "Call duration: #{event['data']['duration']}s"

  when 'number.ported'
    puts "Number #{event['data']['number']} ported successfully"
  end

  { success: true }.to_json
end

Rails Integration​

Configuration​

# config/initializers/audian.rb
Audian.configure do |config|
  config.api_key = ENV['AUDIAN_API_KEY']
  config.base_url = 'https://api.audian.com:8443/v2'
  config.timeout = 30
  config.max_retries = 3
end

# Access globally
Audian.client

Use in Models​

class PhoneNumber < ApplicationRecord
  def send_sms(message)
    Audian.client.sms.send(
      to: number,
      message: message
    )
  end
end

Use in Controllers​

class SMSController < ApplicationController
  def send
    Audian.client.sms.send(
      to: params[:to],
      message: params[:message]
    )

    render json: { success: true }
  end
end

Testing​

The SDK provides helpers for testing:

require 'audian/testing'

# Use mock client
mock_client = Audian::Testing::MockClient.new

mock_client.set_mock_response('numbers.search', {
  'success' => true,
  'data' => {
    'numbers' => [
      { 'number' => '+14155551234', 'available' => true }
    ]
  }
})

numbers = mock_client.numbers.search(location: 'US-CA-415')

RSpec Integration​

require 'spec_helper'
require 'audian/testing/rspec'

describe 'SMS Sending' do
  include Audian::Testing::RSpec

  it 'sends SMS successfully' do
    stub_audian_request(:post, 'sms/send') do
      { success: true, data: { id: 'sms_123' } }
    end

    response = client.sms.send(to: '+14155551234', message: 'Test')
    expect(response['data']['id']).to eq('sms_123')
  end
end

Examples​

Complete Example​

require 'audian'

client = Audian::Client.new(api_key: ENV['AUDIAN_API_KEY'])

# Search for available numbers
available = client.numbers.search(
  location: 'US-CA-415',
  limit: 5
)

puts "Found #{available['data']['numbers'].length} available numbers"

# Purchase the first number
if available['data']['numbers'].any?
  number = available['data']['numbers'].first['number']

  purchased = client.numbers.purchase(
    number: number,
    friendly_name: 'Demo Number'
  )

  puts "Purchased: #{purchased['data']['number']}"

  # Send SMS from the number
  sms = client.sms.send(
    from: purchased['data']['number'],
    to: '+14155559999',
    message: 'Hello from Audian!'
  )

  puts "SMS sent: #{sms['data']['id']}"
end

Production Example​

class AudianService
  def initialize
    @client = Audian::Client.new(api_key: ENV['AUDIAN_API_KEY'])
  end

  def send_sms(to, message)
    @client.sms.send(to: to, message: message)
  rescue Audian::Error => e
    Rails.logger.error("Failed to send SMS: #{e.message}")
    raise
  end

  def get_usage
    @client.billing.usage.get
  end
end

Troubleshooting​

API Key Not Set​

api_key = ENV['AUDIAN_API_KEY']
raise 'AUDIAN_API_KEY not set' unless api_key

client = Audian::Client.new(api_key: api_key)

Timeout Issues​

client = Audian::Client.new(
  api_key: ENV['AUDIAN_API_KEY'],
  timeout: 60
)

Debug Logging​

require 'logger'

logger = Logger.new(STDOUT)
client = Audian::Client.new(
  api_key: ENV['AUDIAN_API_KEY'],
  logger: logger
)

Support​

Version History​

See changelog