Ruby SDK

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:

bashCopy
git clone https://github.com/vobiz-ai/Vobiz-Ruby-SDK.git

rubyCopy
# 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.

rubyCopy
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:

rubyCopy
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:

rubyCopy
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:

rubyCopy
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

ℹ️ Note: 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

rubyCopy
# 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

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

DID phone management

rubyCopy
# 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:

rubyCopy
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

• GitHub repository
• Vobiz Console
• API documentation
• VobizXML reference