Chris Guzman

Vonage Team Member

Chris is a Developer Advocate at Nexmo where he helps developers use their global communications platform. When he’s not at conferences you can find him roaming the world.

[Read more]
< Tutorial />

How to Receive SMS Messages with Ruby on Rails

Last updated on May 07, 2021

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:

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Screenshot of new Meetings API session in progress
Start developing in minutes with free credits on us. No credit card required!

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
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
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
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 =
key: 'YOUR-API-KEY',

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
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.