Set Up a Ruby Dev Environment for Messaging

    This guide shows how to set up a development environment in five minutes to trigger API requests related to our Messaging API. It also shows how to send and receive messages using tunneling software to expose the local dev server to the public internet.

    Install Ruby and Rails

    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.

    Install the Plivo Ruby SDK

    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

    bundle install
    

    Create a Rails controller to trigger an API request

    Now you can create a file in the project directory and execute code to trigger any Plivo API. Here’s some example code that sends an SMS message. Change to the newly created plivotest project directory and run this command to create a Rails controller to send an outbound SMS message:

    rails generate controller Plivo sms
    

    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.

    rm app/views/plivo/sms.html.erb
    

    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.messages.create(
         '<Caller_ID>',
    	 ['<Destination_Number>'],
    	 'Hello, from Rails!'
       )
       puts response
       render json: response.to_s
     end
    end
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    
    include Plivo
    include Plivo::Exceptions
    
    class PlivoController < ApplicationController
     def outbound
       api = RestClient.new("<auth_id>","<auth_token>")
       response = api.messages.create(
         '<Caller_ID>',
         ['<Destination_Number>'],
         'Hello, MMS from Rails!',
         {
    			media_urls:['https://media.giphy.com/media/26gscSULUcfKU7dHq/source.gif'],
    			type: "mms",
    			media_ids:['801c2056-33ab-499c-80ef-58b574a462a2']
    		}
       )
       puts response
       render json: response.to_s
     end
    end
    
    Note:
    • Replace the placeholders <auth_id> and <auth_token> with your authentication credentials, which you can find on the overview page of the Plivo console.
    • We recommend that you store your credentials in the auth_id and 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 the values from the environment variables.
    • Replace the placeholder <Caller_ID> with a phone number you’ve purchased, and <Destination_Number> with the phone number you’ll be calling. Both phone numbers should be in E.164 format

    Add a route

    To add a route for the outbound function in the PlivoController class, open the config/routes.rb file and change the line:

    get 'plivo/sms' 
    

    to

    get 'plivo/outbound'
    

    Now plivo_controller is ready. Use this command to initiate an outbound SMS message.

    rails server
    

    Your local development server will be started and you can test the application for outbound messages 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 Messaging API platform.

    Set up a Rails server to serve XML and manage callbacks

    Now that we’ve sent a message, let’s set up a Rails server to handle incoming messages.

    Plivo supports receiving SMS text messages in several countries (see complete SMS API coverage). When someone sends a text message to a Plivo phone number, you can receive it on your server by setting a Message URL in your Plivo application. Plivo sends the message, along with other parameters, to your Message URL.

    Edit app/controllers/plivo_controller.rb and add this code in the PlivoController class after the outbound function:

    1
    2
    3
    4
    5
    6
    
    def inbound
        from_number = params[:From]
          to_number = params[:To]
          text = params[:Text]
          puts "Message received - From: #{from_number}, To: #{to_number}, Text: #{text}"
    end
    
    1
    2
    3
    4
    5
    6
    7
    
    def inbound
        from_number = params[:From]
          to_number = params[:To]
          text = params[:Text]
          media_url = params[:Media0]
          puts "Message received - From: #{from_number}, To: #{to_number}, Text: #{text}, Media: #{media_url}"
    end
    

    Add a route

    To add a route for the inbound function in PlivoController class, open the config/routes.rb file and add this line after the outbound route:

    get 'plivo/inbound'
    

    Now plivo_controller is ready. Use this command to receive an inbound message.

    $rails server
    

    Your local development server will be started and you can test the application for inbound messages via the URL http://localhost:3000/plivo/inbound/.

    Ngrok setup

    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.

    ngrok block diagram

    Note: Before you start the ngrok service, whitelist ngrok by adding it to the config.hosts list in the config/environments/development.rb file with this command. You’ll face a Blocked host error if you fail to add it.
    # Whitelist ngrok domain
    config.hosts << /[a-z0-9]+\.ngrok\.io/
    

    Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive messages (3000 in this case):

    ./ngrok http 3000
    

    This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. You should be able to see your basic server application in action at https://<nrgok_URL>/inbound/.

    Now people can send messages to your Plivo number.

    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 Messaging API platform.