Skip to main content
The official Ruby SDK for the Vobiz Voice API. Make outbound calls, manage SIP trunks, handle phone numbers, and drive live call flows directly from your Ruby on Rails or native Ruby stack. Source code: vobiz-ai/Vobiz-Ruby-SDK

​
Installation

Requires Ruby >= 3.3.0. The SDK is distributed from its GitHub repo (not RubyGems). Clone it, then reference it by path in your Gemfile: 
git clone https://github.com/vobiz-ai/Vobiz-Ruby-SDK.git

# Gemfile
gem "vobiz", path: "./Vobiz-Ruby-SDK"
Then run bundle install.

​
Quick start

Place an outbound call. When the call connects, Vobiz queries your answer_url webhook, which must return a valid VobizXML document. 
require 'vobiz'

client = Vobiz::Client.new(
  api_key: ENV['VOBIZ_AUTH_ID'],
  auth_token: ENV['VOBIZ_AUTH_TOKEN']
)

auth_id = ENV['VOBIZ_AUTH_ID']

response = client.calls.make_call(
  auth_id:       auth_id,
  from:          '14155551234',
  to:            '+919876543210',
  answer_url:    'https://yourserver.com/answer',
  answer_method: 'POST'
)

puts "Call UUID: #{response.call_uuid}"

​
Authentication

The Ruby client uses your Auth ID and Auth Token. Find both in the Vobiz Console. Pass your Auth ID as api_key (mapped to the X-Auth-ID header) and your Auth Token as auth_token (mapped to X-Auth-Token). It is recommended to load credentials from environment variables: 
require 'vobiz'

client = Vobiz::Client.new(
  api_key: ENV['VOBIZ_AUTH_ID'],
  auth_token: ENV['VOBIZ_AUTH_TOKEN']
)
Most API methods also take your auth_id as a parameter: 
auth_id = ENV['VOBIZ_AUTH_ID']

​
VobizXML

When Vobiz calls your answer_url, your webhook must respond with a VobizXML document that defines the call flow. The gem ships a builder at Vobiz::XML (require "vobiz/xml") — each add_* returns the created child for nesting, and keyword args map to VobizXML attributes: 
require "vobiz/xml"

# Example Sinatra/Rails handler returning VobizXML
post '/answer' do
  content_type 'application/xml'
  r = Vobiz::XML::Response.new
  gather = r.add_gather(
    action: "https://yourapp.com/menu-choice",
    method: "POST",
    input_type: "dtmf",          # -> inputType (Gather uses inputType / execution_timeout)
    num_digits: 1,
    execution_timeout: 10,
  )
  gather.add_speak("Press 1 for sales, 2 for support, or 0 for an operator.")
  r.add_speak("We didn't receive your input. Goodbye.")
  r.add_hangup
  r.to_s                          # pretty; r.to_s(pretty: false) for one line
end
Prefer the builder, but returning a raw VobizXML string also works. See the VobizXML reference for all verbs and attributes.

​
Common operations

​
Live call text-to-speech

# Inject TTS dynamically into a live call
client.speak_text.call(
  auth_id:   auth_id,
  call_uuid: 'YOUR_CALL_UUID',
  text:      'Hello dynamically!',
  voice:     'WOMAN',
  language:  'en-US',
  legs:      'aleg'
)

​
Recordings

recordings = client.recordings.list_recordings(auth_id: auth_id, limit: 10)
recordings.data.each { |rec| puts rec.recording_url }

​
DID phone management

# List numbers you own
numbers = client.phone_numbers.list_numbers(auth_id: auth_id)

# List inventory numbers available to buy
available = client.phone_numbers.list_inventory_numbers(auth_id: auth_id)

# Purchase a number from inventory
client.phone_numbers.purchase_from_inventory(auth_id: auth_id)

​
Error handling

The SDK raises Vobiz::ApiError for any non-2xx response. Inspect the exception for the status code and raw body: 
begin
  client.calls.make_call(
    auth_id:       auth_id,
    from:          '14155551234',
    to:            '+919876543210',
    answer_url:    'https://yourserver.com/answer',
    answer_method: 'POST'
  )
rescue Vobiz::ApiError => e
  puts "Status: #{e.status_code}, Body: #{e.body}"
end

​
Resources