Plivo Ruby SDK

The Plivo Ruby SDK makes it simpler to integrate voice and SMS communications into your Ruby applications using the Plivo REST APIs. Using the SDK, you’ll be able to make voice calls, send SMS messages, and generate Plivo XML documents to control your call flows.

Installation

Add this line to your application’s Gemfile:

gem 'plivo', '>= 4.3.0'

Then execute:

$ bundle

Or install it yourself as:

$ gem install plivo

Getting started

Authentication

To make API requests, you need to create a RestClient and provide it with authentication credentials, which you can find on the Overview page of the Plivo console.

We recommend that you store your credentials in the PLIVO_AUTH_ID and the PLIVO_AUTH_TOKEN environment variables, to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and it will automatically fetch them from the environment variables:

client = RestClient.new;

Alternatively, you can specify the authentication credentials while initializing the RestClient.

client = RestClient.new('<auth_id>', '<auth_token>');

Replace the auth placeholders with your authentication credentials from the Plivo console.

The basics

The SDK uses consistent interfaces to create, retrieve, update, delete, and list resources. The pattern is:

client.resources.create(params); # Create
client.resources.get(resource_identifier); # Get
client.resources.update(resource_identifier, params); # Update
client.resources.delete(resource_identifier); # Delete
client.resources.list; # List all resources, max 20 at a time

You can also use the resource directly to update and delete it. For example:

resource = client.resources.get(resource_identifier);
resource.update(params); # update the resource
resource.delete(); # Delete the resource

Using client.resources.list lists the first 20 resources by default (the first page, with limit as 20, and offset as 0). Use limit and offset to get more pages of resources.

To list all resources, you can use this pattern to handle pagination for you automatically, so you don’t have to worry about passing the right limit and offset values.

client.resources.each do |resource|
  puts resource.id
end

Examples

Send a message

require 'rubygems'
require 'plivo'

include Plivo

client = RestClient.new
message_created = client.messages.create(
  '<source_number>',
  '<destination_number>',
  'Hello, world!'
)

Replace the auth placeholders with your authentication credentials from the Plivo console. Replace the phone number placeholders with actual phone numbers in E.164 format (for example, +12025551234).

Make a call

require 'rubygems'
require 'plivo'

include Plivo

client = RestClient.new
call_made = client.calls.create(
  '<caller_id>',
  ['<destination_number>'],
  'https://<answer.url>'
)

Generate Plivo XML

require 'rubygems'
require 'plivo'

include Plivo::XML

response = Response.new
response.addSpeak('Hello, world!')
puts response.to_xml # Prints the XML string

xml_response = PlivoXML.new(response)
puts xml_response.to_xml # Prints XML along with XML version & encoding details

This generates the following XML:

<?xml version="1.0" encoding="utf-8" ?>
<Response>
  <Speak>Hello, world!</Speak>
</Response>

Run a PHLO

require 'rubygems'
require 'plivo'

include Plivo

AUTH_ID = '<auth_id>'
AUTH_TOKEN = '<auth_token>'

client = Phlo.new(AUTH_ID, AUTH_TOKEN)

# if credentials are stored in the PLIVO_AUTH_ID and the PLIVO_AUTH_TOKEN environment variables
# then initialize client as:
# client = Phlo.new

# run a phlo:
begin
    #parameters set in PHLO - params
    params = {
       from: '<caller_id>',
       to: '<destination_number>'
    }
    response = phlo.run(params)
    puts response
  rescue PlivoRESTError => e
    puts 'Exception: ' + e.message
  end

Replace the auth placeholders with your authentication credentials from the Plivo console. Replace the phlo_id placeholder with your PHLO ID from the Plivo console. Replace the phone number placeholders with actual phone numbers in E.164 format (for example, +12025551234).

More examples

Refer to the Ruby API Reference documentation for more examples. Also refer to our guide to setting up dev environment for details on how to set up a Sinatra server and expose that server to the internet.

Reporting issues

Report feedback or problems with this version by opening an issue on GitHub.