How to Receive and Respond to Incoming SMS Messages in Ruby with Rails and Plivo

Sending an outbound message using the Plivo SMS platform is easy, but communication should be a two-way street. Customers should be able to text you, and you should acknowledge their messages and address their concerns. To do this, you can build a Ruby on Rails application to receive and respond to incoming SMS messages on a Plivo phone number. In this post, we walk you through how to implement this.

Prerequisites

Before you get started, you’ll need:

• A Plivo account — sign up for one for free if you don’t have one already.
• An SMS-enabled Plivo phone number, as you want to receive incoming SMS messages. To search for and buy an available number, go to Phone Numbers > Buy Numbers on the Plivo console.
• Rails and Plivo Ruby packages.
• ngrok — a utility that exposes your local development server to the internet over secure tunnels.

Create a Rails application to receive SMS messages

First, you need to install Rails if you haven’t installed it already. Use the command gem install rails, or use bundler or RVM to install it. Add a new Rails project with boilerplate code with the command rails new myrailsapp. This will create a myrailsapp directory with the necessary folders and files for development. Then add the Plivo Ruby gem (gem ‘plivo’, ‘~> 4.16.0’) as a dependency in the gemfile and use the command bundle install to install it.

Once you’ve installed Rails and the Plivo Ruby SDK, change to the newly created myrailsapp project directory and run rails generate controller Plivo sms to create a Rails controller to handle incoming SMS messages on a Plivo number. Use this code:

class PlivoController < ApplicationController
 def sms
   from_number = params[:From]
   to_number = params[:To]
   text = params[:Text]
   puts "Message received - From: #{from_number}, To: #{to_number}, Text: #{text}"
 end
end

Return a Message XML document to reply to incoming messages

To reply to an incoming SMS message, you need to return an XML document from the URL configured as the Message URL in the application assigned to the Plivo number. The Ruby SDK can manage the XML document generation, and you can use the Message XML element to reply to incoming SMS messages. Use this code:

class PlivoController < ApplicationController
 def sms
   from_number = params[:From]
   to_number = params[:To]
   text = params[:Text]
   puts "Message received - From: #{from_number}, To: #{to_number}, Text: #{text}"
 end
 def reply
   from_number = params[:From]
   to_number = params[:To]
   text = params[:Text]
   response = Plivo::XML::Response.new
   params = {
     src: to_number,
     dst: from_number,
   }
   message_body = "Thank you, we have received your request"
   response.addMessage(message_body, params)
   xml = Plivo::XML::PlivoXML.new(response)
   puts xml.to_xml
   render xml: xml.to_xml
 end
end

Now open the config/routes.rb file and add the route for this reply function. The routes would become:

Rails.application.routes.draw do
 get 'plivo/sms'
 get 'plivo/reply'
end

Test the code locally

To run the code on the rails server, use the command

$ rails server

You should see your basic server application in action on http://127.0.0.1:3000/plivo/reply/.

Expose the local server to the internet using ngrok

Once you see the application working locally, the next step is to connect the application to the internet to receive and reply to messages. For that, we recommend using ngrok, which exposes local servers behind NATs and firewalls to the public internet over secure tunnels.

Install ngrok, but 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.

Now run ngrok on the command line, specifying the port that hosts the application on which you want to receive messages (3000 in this case, as our local Rails application runs there):

Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network.

Test the link by opening the ngrok URL (https://dd10ca394535.ngrok.io/plivo/reply/) in a browser. We used HTTPie to check the XML response from the ngrok URL.

Connect the Rails application to a Plivo number

The final step is to configure the application as a Plivo messaging application and assign it to a Plivo number on which you want to receive SMS messages.

Go to the Plivo console and navigate to Messaging > Applications > XML, then click on the Add New Application button in the upper right.

Provide a friendly name for the app — we used “App-Incoming-SMS” — and configure the ngrok URL https://dd10ca394535.ngrok.io/plivo/reply/ as the Message URL. Select the HTTP verb as POST, then click Create Application.

Now go to Phone Numbers > Your Numbers and click on the number to which you want to assign the application. From the Plivo Application drop-down, choose the message application you just created. Finally, click Update Number.

Test the application

Test the application by sending an SMS message to the Plivo number you selected. You should see that the Rails application automatically sends a reply back to your mobile number.

And that’s how simple it is to receive and respond to incoming SMS messages using Plivo’s Ruby SDK and a Rails application.

Haven’t tried Plivo yet? Getting started is easy and only takes five minutes! Sign up today.