This guide shows how to set up a development environment in five minutes to trigger API requests and start serving Plivo XML to control your call flow. It also shows how to test your code using tunneling software to expose the local dev server to the public internet.
To get started, install Ruby, Rails, and Plivo’s Ruby SDK. You can check whether you have Ruby installed by running
ruby --version in a terminal window. If you don’t have it, macOS and Linux users can install it using homebrew, and Windows users can use RubyInstaller.
To install Rails, run
gem install rails
Auto-generate code for a new Rails project with the command
rails new plivotest
This command creates a directory named plivotest with the necessary folders and files for development.
Add the Plivo Ruby SDK by editing the Gemfile and adding the line
gem 'plivo', '~> 4.16.0'
To install the Plivo-Ruby gem into the bundle, run
Now you can create a file in the project directory and execute code to trigger any Plivo API. Change to the newly created plivotest project directory and run this command to create a Rails controller for outbound calls.
rails generate controller Plivo voice
This command generates a controller named plivo_controller in the app/controllers/ directory and a view in app/views/plivo. You can delete the view — we don’t need it.
Now, edit the app/controllers/plivo_controller.rb file and add this code:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 include Plivo include Plivo::Exceptions class PlivoController < ApplicationController def outbound api = RestClient.new("<auth_id>","<auth_token>") response = api.calls.create( '<Caller_ID>', ['<Destination_Number>'], 'http://s3.amazonaws.com/static.plivo.com/answer.xml' ) puts response render json: response.to_s end end
To add a route for the outbound function in the PlivoController class, open the config/routes.rb file and change the line:
Now plivo_controller is ready. Use this command to initiate an outbound call.
Your local development server will be started and you can test the application for outbound calls via the URL http://localhost:3000/plivo/outbound/.
You can follow the same approach to trigger other API requests. Refer to our detailed API reference to see all the API requests available on the Voice API platform.
When you receive a call on a Plivo voice-enabled number, you can control the call flow by declaring an Answer URL for the Plivo application associated with that phone number. Plivo will invoke the Answer URL specified and expect a valid XML response to handle the call.
In addition to requests to the Answer URL, Plivo initiates other HTTP requests to your application server based on specific XML elements in your Answer XML document. Such requests are broadly classified into two categories:
Action URL requests: These requests are typically invoked at the end of an XML element’s execution, and the server expects XML instructions to carry forward the call in response to these requests. This happens, for example, when a caller provides Touch-Tone input during GetInput XML execution.
Callback URL requests: These requests serve as webhooks to pass the application server information about events through the course of an XML element’s execution, such as when a conference participant is muted or unmuted. No XML instructions are expected in response to these requests.
Here’s how to set up a Rails server to serve XML documents and manage callbacks.
Use this code snippet to start a local server.
1 2 3 4 5 6 7 8 def inbound response = Response.new speak_body = 'Hello, you just received your first call' response.addSpeak(speak_body) xml = Plivo::PlivoXML.new(response) render xml: xml.to_xml end
To add a route for the inbound function in the PlivoController class, open the config/routes.rb file and add this line after the outbound route:
Now plivo_controller is ready. Use this command to receive an inbound call.
Your local development server will be started and you can test the application for inbound calls via the URL http://localhost:3000/plivo/inbound/.
To serve XML documents, your local server must connect with Plivo API services. For that, we recommend using ngrok, which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server.
# Whitelist ngrok domain config.hosts << /[a-z0-9]+\.ngrok\.io/
Run ngrok on the port that hosts the application on which you want to receive messages (3000 in this case):
./ngrok http 3000
This will start the ngrok server on your local server.
You should be able to see your basic server application in action at https://<nrgok_URL>/receive_call/ and check the XML response:
You can follow the same approach to serve other XML documents to manage other call flows. Refer to our detailed XML reference to see all the XML elements available on the Voice API platform.