Get Started with Call Forwarding Using Ruby


    Call forwarding can be useful in any business work flow. For example, incoming calls can be dynamically routed to available agents, extensions, or departments that cater to the caller’s needs. In this tutorial, you’ll learn how to forward a received call to another phone number.

    Start by signing up for a free trial account that you can use to experiment with and learn about our services. The free trial account comes with free credits, and you can add more as you go along. You can also add a phone number to your account to start testing the full range of our voice and SMS features. A page in our support portal walks you through the signup process.

    You can start making and receiving calls either by using our PHLO visual workflow builder or our APIs and XML documents. Follow the instructions in one of the tabs below.

    You can create and deploy a workflow to implement a call forwarding use case with a few clicks on the PHLO canvas.


    1. Create a Plivo account if you don’t have one already. Sign up with your work email address.
    2. Buy a Plivo number: You must have a voice-enabled Plivo phone number to receive incoming calls. You can purchase numbers from the Numbers page of the Plivo console, or by using the Numbers API.
    3. PHLO application: When you receive a call on a Plivo voice-enabled number, you can control the call flow by associating a PHLO application with that Plivo phone number. Plivo will fetch the PHLO associated with the number and expect valid instructions via PHLO to handle the call.

    Create the PHLO

    • On the left navigation bar, click PHLO. The PHLO page will appear and display your existing PHLOs, if any. If this is your first PHLO, then the PHLO page will be empty.
    • Click CREATE NEW PHLO to build a new PHLO.
    • On the Choose your use case window, click Build my own. The PHLO canvas will appear, displaying the Start node, which is the starting point of any PHLO. You can choose between three available trigger states to start the PHLO: Incoming Message, Incoming Call, and API Request. For this PHLO, choose Incoming Call.
    • From the list of components on the left side, drag and drop the Call Forward component onto the canvas to add a Call Forward node to the canvas.
    • Connect the Start node with the Call Forward node by dragging down from the Incoming Call trigger state.

    • Configure the Call Forward node to select the From number using a variable. Enter all the numbers you want to call in the To field, separated with commas.
    • Once you’ve configured a node, click Validate to save the configuration.
    • If this PHLO had more nodes you could configure them now. After you complete all the configurations, click Save.

    Your complete PHLO will look like this:

    Call Forwarding

    Assign the PHLO to a Plivo number for incoming calls

    Once you’ve created and configured your PHLO, assign your PHLO to a Plivo number.

    1. Go to the Numbers page of the Plivo console.
    2. Under Your Numbers, click the phone number you want to use for the PHLO.
    3. In the Number Configuration section, under Application Type, select PHLO from the drop-down list.
    4. From the PHLO Name drop-down, select the PHLO you want to use with the phone number, then click Update Number.

    Assign PHLO to a Plivo Number

    Test and validate

    To test that the PHLO is working, call your Plivo phone number to see how the inbound call is forwarded.

    For more information about creating a PHLO app, see the PHLO User Guide. For information on components and their variables, see the PHLO Components Library.

    Here’s how to implement call forwarding by using Ruby and the Plivo Dial XML element handle incoming calls.

    First, a little background information. To control call flow, you create a Plivo application and associate it with a Plivo voice-enabled number. The application includes an answer URL.  When a call comes in, Plivo sends an HTTP request to the answer URL with the attributes of the call, and expects a valid XML response back so that it knows how to handle the call.

    Plivo also initiates HTTP requests to your application server through the course of a call based on specific XML elements in your answer XML. Such requests fall broadly into two categories:

    Action URL requests: Plivo expects XML instructions to carry forward the call in response to action URL requests, which are typically invoked at the end of an XML element’s execution, such as when IVR input is received from a caller during GetInput XML execution.

    Callback URL requests: No XML instructions are expected in response to these requests. They serve as webhooks to notify your application server of important events through the course of an XML element’s execution — for example, when a conference participant is muted or unmuted.

    Call forwarding workflow

    Call Forward- Call Flow


    1. Create a Plivo account if you don’t have one already. Sign up with your work email address.
    2. Buy a Plivo number: You must have a voice-enabled Plivo phone number to receive incoming calls. You can purchase numbers from the Numbers page of the Plivo console, or by using the Numbers API.
    3. Set up a web server: You need a web server to host answer and callback URLs and to provide valid XML and accept notifications on these URLs. The next section talks about how to set up a Rails server for incoming calls and callbacks section.

    Set up a Rails server for incoming calls and callbacks

    You can set up a Rails server in less than five minutes to start handling incoming calls and callbacks.

    Install Rails

    Use this command to install Rails.

    $ gem install rails

    Create a Rails project

    Use this command to start your Rails project. It creates a plivotest directory with the necessary folders and files for development.

    $ rails new plivotest

    Install Plivo

    Now edit the Gemfile and add the Plivo Ruby gem by adding the line:

    gem 'plivo', '~> 4.16.0'

    Then use this command to install the Plivo Ruby gem into the bundle:

    $ bundle install

    Create a Rails controller to forward incoming calls

    Change to the newly created plivotest project directory and run this command to create a Rails controller for inbound calls.

    $ rails generate controller Plivo voice

    This command generates a controller named plivo_controller in the app/controllers/ directory and a respective view in app/views/plivo directory. You can delete the view, as we don’t need it.

    $ rm app/views/plivo/voice.html.erb

    Open the app/controllers/plivo_controller.rb file and add this code in the PlivoController class:

    def forward
       response =
       dial = response.addDial()
       dest_number = "14153234567"
       xml =
       puts xml.to_xml
       render xml: xml.to_xml

    Add a route

    Add a route for the inbound function in the PlivoController class. Open the config/routes.rb file and add this line after the inbound route:

    get 'plivo/forward'

    Now plivo_controller is ready for inbound calls. Use this command to start the server to handle inbound calls.

    $ rails server

    You can test the Rails app to forward incoming calls via the URL

    Expose your local server to the internet

    To receive incoming calls and handle callbacks, your local server must be able to connect with Plivo. To make your server available, we recommend using ngrok, which exposes local servers behind NAT and firewalls to the public internet over secure tunnels. With ngrok you can set webhooks that can talk to a Plivo server.

    ngrok block diagram

    Note: Before you start the ngrok service, you need to add ngrok in the config.hosts list in the config/environments/development.rb file and include the line below. If you forget to add it, you'll see Blocked host errors.
    # whitelist ngrok domain
    config.hosts << /[a-z0-9]+\.ngrok\.io/

    Run ngrok on the command line, specifying the port that hosts the application on which you want to receive messages. For example, if your port number is 3000, run the command

    ./ngrok http 3000

    That command displays output with links that look like*, which you can use to access your local server using the public network.

    ngrok CLI

    You can check the application in action on

    Create a Plivo application

    Now that we have a web server that’s accessible from outside our network we can create an application to forward the call.

    1. Create an application by visiting Voice > Applications > XML on the console and click on Add New Application, or by using Plivo’s Application API.
    2. Give the application a name. Let’s call it Forward Call. Enter your server URL ( in this example) in the Primary Answer URL field and set the method as POST. See our Application API documentation to learn how to modify your application through our APIs.
    3. Click Create Application to save your application.

    Plivo Create Application

    Assign a Plivo number to your application

    1. Navigate to the Phone Numbers page on the console and select the phone number you want to use for this application.
    2. Select XML Application from the Application Type drop-down list, and Forward Call (the name of the application) from the Plivo Application drop-down list.
    3. Click Update Number to save.

    Assign Call Forward Application


    Make a call to your Plivo number using a regular mobile phone. Plivo will send a request to your answer URL for a valid XML response and forward the call. At the same time, it sends a set of call status parameters to your server using the callback URL requests we mentioned above.

    Common use cases for call forwarding

    Call forwarding plays a pivotal role in routing customers’ calls based on any of several possible factors.

    • Agent availability: You can place calls in a holding queue and route them to an available agent as soon as one is available.
    • Business hours-based forward: You can route calls to an office number during business hours and to a mobile phone or voicemail during non-business hours.
    • Time-zone based Forward: You can forward calls to agents from different time zones to ensure round-the-clock availability.