Two-way SMS for customer engagement

Programmable SMS is not only useful for one way notifications. When you combine outbound notifications with inbound messages you create chat-like interactions between your company and your customers.

In this tutorial

You see how quick it is to build two-way communication into your app; you send a delivery notification to your customer's phone number and handle their reply when they want to change a delivery slot.

The workflow for your app is:

sequenceDiagram Participant App Participant Vonage Participant Phone number App->>Vonage: Request to SMS API Vonage-->>App: Response from SMS API Note over Vonage: Request accepted Vonage->>Phone number: Send delivery notification SMS Phone number->>Vonage: Reply to delivery notification Vonage-->>App: Send reply to webhook endpoint App->>Vonage: Request to SMS API Vonage-->>App: Response from SMS API Note over Vonage: Request accepted Vonage->>Phone number: Send acknowledgement in SMS

To do this:

  1. Configure a Vonage virtual number - rent a virtual number and set the webhook endpoints for inbound messages
  2. Create a basic Web app - create a Web app to collect your customer's phone number.
  3. Send an SMS notification - send your customer a delivery notification in an SMS and request a reply.
  4. Process the reply SMS - process and acknowledge the SMS reply.


In order to work through this tutorial you need:

Configure a Vonage virtual number

Vonage forwards inbound messages to the webhook endpoint associated with your Vonage virtual number.

You manage virtual numbers using the Developer API or the Vonage CLI. The following examples use the Vonage CLI to rent a Vonage number:

$ vonage numbers:search US
$ vonage numbers:buy 1201###### US

Then associate the virtual number with your webhook endpoint that handles inbound SMS:

$ vonage numbers:sms 1201######
Number updated

Note: ensure your server is running and publicly available before associating the webhook endpoint with your virtual number. Vonage must receive a 200 OK response from your webhook endpoint for successful configuration. If you're developing locally use a tool such as ngrok to expose your local web server to the Internet.

Now that you have configured your virtual number, you can send SMS delivery notifications.

Create a basic Web app

Use Sinatra to create a single page Web app:


source ''

# our web server
gem 'sinatra'


# web server and flash messages
require 'sinatra'

# load environment variables
# from .env file
require 'dotenv'

# Index
# - collects a phone number
get '/' do
  erb :index

Add an HTML form to collect the phone number you will send a notification SMS to:


<form action="/notify" method="post">
  <div class="field">
    <label for="number">
      Phone number
    <input type="text" name="number">

  <div class="actions">
    <input type="submit" value="Notify">

The form captures the phone number in the E.164 format expected by SMS API:

Send an SMS notification

In this tutorial, to send an SMS you add the Vonage Server SDK for Ruby to your app:


# the nexmo library
gem 'vonage'
# a way to load environment
# variables
gem 'dotenv'

Use your Vonage API key and secret to initialize the client:


# Vonage library
require 'vonage'
vonage =
  api_key: ENV['VONAGE_API_KEY'],
  api_secret: ENV['VONAGE_API_SECRET']

Note: do not store your API credentials in your code, use environment variables.

To receive replies to your notification SMS, you set your virtual number as the SenderID for outbound messages when you make a request to SMS API:


# Notify
# - Send the user their delivery
#   notification, asking them
#   to respond back if they
#   want to make any changes
post '/notify' do
  notification = "Your delivery is scheduled for tomorrow between " +
                 "8am and 2pm. If you wish to change the delivery date please " +
                 "reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to"
                 "post office) below.\n\n";

    from: ENV['VONAGE_NUMBER'],
    to: params['number'],
    text: notification

  "Notification sent to #{params['number']}"

To verify that this SMS was received by the customer, check the delivery receipt. This tutorial does not verify delivery receipts.

Process the reply SMS

When your customer replies to your notification SMS, Vonage forwards the inbound message to the webhook endpoint associated with the virtual number.

In this tutorial app you process the incoming webhook, extract the text and number, and send a confirmation message back to the customer.


# Receive incoming message
# - Receives incoming SMS
#   message, stores it, and
#   notifies sender
get '/update' do
  choice = params['text']
  number = params['msisdn']

  # You can store or validate
  # the choice made here

  message = "Thank you for picking option #{choice}. " +
            "Your delivery is now fully scheduled in."

    from: ENV['VONAGE_NUMBER'],
    to: number,
    text: message

  body ''

Storing and validating customers input is beyond the scope of this tutorial.

Now reply back to the SMS you received earlier. You should see it be processed by your app and receive a confirmation of your choice within seconds.


That's how quick it is to send and receive SMS in your app. With a few lines of code you have sent a SMS to a customer's phone with the SMS API, handled a reply, and responded with a confirmation.

Get the Code

All the code for this tutorial is available in the Two-way SMS for customer engagement GitHub repo.