> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby SDK

> Build Ruby and Rails voice apps with the Vobiz SDK - outbound calls, SIP trunks, DID management, and VobizXML for global calling in 130+ countries.

The official Ruby SDK for the Vobiz Voice API. Make outbound calls, manage SIP trunks, handle phone numbers, and construct programmatic XML workflows directly from your Ruby on Rails or native Ruby stack.

**Source code:** [vobiz-ai/Vobiz-Ruby-SDK](https://github.com/vobiz-ai/Vobiz-Ruby-SDK)

## Installation

Clone the repository directly into your workspace:

```bash theme={null}
git clone https://github.com/vobiz-ai/Vobiz-Ruby-SDK.git
cd Vobiz-Ruby-SDK
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.

```ruby theme={null}
require 'vobiz'

client = Vobiz::Client.new

call = client.calls.create(
  from:          '+1xxxxxxxxxx',
  to:            '+1xxxxxxxxxx',
  answer_url:    'https://yourserver.com/answer',
  answer_method: 'POST',
  hangup_url:    'https://yourserver.com/hangup',
  hangup_method: 'POST'
)

puts "Call UUID: #{call[:request_uuid]}"
```

## Authentication

The Ruby client uses your **Auth ID** and **Auth Token**. Find both in the [Vobiz Console](https://console.vobiz.ai).

Initialize the client automatically using environment variables:

```ruby theme={null}
require 'vobiz'

client = Vobiz::Client.new
```

Or pass credentials explicitly:

```ruby theme={null}
client = Vobiz::Client.new('YOUR_AUTH_ID', 'YOUR_AUTH_TOKEN')
```

## VobizXML

Use the object-oriented `XML::Response` builder. Instead of concatenating raw XML strings, instantiate elements like `add_speak` or `add_record` and render with `to_xml` - your webhooks will always be schema-compliant.

```ruby theme={null}
require 'vobiz/xml'

response = Vobiz::XML::Response.new
response.add_speak('Welcome to Vobiz!', voice: 'WOMAN', language: 'en-US')
response.add_record(action: 'https://yourserver.com/recording', max_length: 30)

puts response.to_xml
```

## Common operations

### Live call mutators and storage

```ruby theme={null}
# Inject TTS dynamically into a live call
client.calls.speak_text('call-uuid', text: 'Hello dynamically!', voice: 'WOMAN', language: 'en-US')

# List recordings via native pagination
recordings = client.recordings.list
recordings.each { |rec| puts rec[:recording_url] }
```

### DID phone management

```ruby theme={null}
# Search the inventory
available = client.numbers.search(country_iso: 'US', type: 'local')

# Provision a number
number = client.numbers.purchase(number: '+12025550123')
```

## Resources

* [GitHub repository](https://github.com/vobiz-ai/Vobiz-Ruby-SDK)
* [Vobiz Console](https://console.vobiz.ai)
* [API documentation](/introduction)
* [VobizXML reference](/xml/response)