1. Vonage Learn
  2. Blog
  3. 2017
  4. 10
  5. 23
  6. Receive Sms Messages Ruby on Rails Dr
How to Receive SMS Messages with Ruby on Rails

< Tutorial />

How to Receive SMS Messages with Ruby on Rails

This is the third article in a series of "Getting Started with Nexmo SMS and Ruby on Rails" tutorials.

In the previous article, you set up your Rails application to be publicly accessible by Nexmo, and then received a Delivery Receipt for a sent message. In this article you will learn how to receive an inbound SMS by implementing a similar webhook endpoint in Ruby on Rails.

View the source code on GitHub


For this tutorial I assume you will:

What is an "Inbound SMS"?

When someone sends an SMS message to the Nexmo Number that you purchased in the first tutorial it will be received by Nexmo, and we will then pass the content of that message on to a webhook in your application.

To receive this webhook you will need to set up a webhook endpoint and tell Nexmo where to find it.

DLR diagram receive flow

In the previous tutorial I already covered how to set up ngrok for your application to allow it to be accessible even in a development environment.

Set the Webhook Endpoint with Nexmo

There are 2 ways to set up your number for inbound SMS. The first way is to install the Nexmo CLI tool (a NodeJS command line interface) and then run the following commands to bind your number to an inbound SMS webhook:

$ nexmo link:sms 14155550102 http://abc123.ngrok.io/inbound_sms
Number updated

Alternatively, head over to the Settings page on the Nexmo Dashboard and scroll down to API settings to configure the Webhook URL for Inbound Message.


Global inbound SMS configuration

Note: This sets the webhook endpoint for inbound SMS at an account level. You can also set up unique webhook endpoints for each virtual number.

Handle an Inbound SMS WebHook

The hard part is really done again at this point. When an SMS has been sent to your virtual Nexmo number, Nexmo will notify your application by sending a webhook. A typical payload for an inbound SMS will look something like this.

"msisdn": "14155550101",
"to": "14155550102",
"messageId": "0B00000057CC7BC7",
"text": "Hello World!",
"type": "text",
"keyword": "HELLO",
"message-timestamp": "2020-01-01 12:00:00"

In this payload the sending number is identified by the msisdn parameter, and your Nexmo number is the to parameter. Let's add a new controller to process this payload and store a new SMS record.

# app/controllers/inbound_sms_controller.rb
class InboundSmsController < ApplicationController
skip_before_action :verify_authenticity_token

def create
sms = Sms.create(
to: params[:to],

from: params[:msisdn],
text: params[:text],
message_id: params[:messageId],
is_inbound: true

# Let's send a reply as well?
reply sms
head :ok

Finally, let's immediately reply back to the sender by reversing the message they sent and sending it back to them.

# app/controllers/inbound_sms_controller.rb

def reply sms
nexmo = Nexmo::Client.new(
key: 'YOUR-API-KEY',

from: sms.to,
to: sms.from,
text: sms.text.reverse

Ok, now start your server, ensure you have something like ngrok running, and send an SMS to your Nexmo number.

Reversed SMS result

To sum things up

That's it for this tutorial. We've set up our Rails application to receive inbound SMS webhooks, informed Nexmo of where to find our server, processed an incoming SMS webhook, and replied back to the sender.

You can view the code used in this tutorial on GitHub.

Next steps

In the next tutorial we will move on from SMS and start looking at making our first phone call from a Rails application.

Comments currently disabled.