Mobile app invites

With the number of apps on Android and iOS rising it is important for people to easily find your apps, both in the stores and on the Web.

If your mobile app has a Website you are probably familiar with:


These buttons make it easy for anyone to navigate to the correct store for their mobile device. However, this flow quickly falls apart if the user is not mobile. What happens when your user is using a desktop computer? By using Mobile app promotion, you can quickly convert a browsing user into an active customer by sending them a link to your app via SMS.

In this tutorial

You see how easy it is to build a mobile app invites system using the Nexmo APIs and libraries:

  1. Create a Web app - create a Web app with download buttons.
  2. Detect desktop users - show the correct download button for desktop or mobile users.
  3. Collect a name and phone number - for desktop browsers, display a form to collect user information.
  4. Send the download link in an SMS - send an SMS to your user containing the download link for your app.
  5. Run this tutorial - run the tutorial and send the download URL to your phone number.


In order to work through this tutorial you need:

Create a Web app

For your customer interface, use Sinatra and rack to create a single page Web app:


source ''

gem 'sinatra'
gem 'rack-flash3'


# web server and flash messages
require 'sinatra'
require 'rack-flash'
use Rack::Flash

# enable sessions and set the
# session secret
enable :sessions
set :session_secret, '123456'

# Index
# - shows our landing page
#   with links to download
#   from the app stores or
#   via SMS
get '/' do
  erb :index

Add the Google and iOS store buttons to the HTML in your Web app:


<a href="">
  <!-- place this image in a public/ folder -->
  <img src="google-play-badge.png" />

<a href="">
  <!-- place this image in a public/ folder -->
  <img src='app-store-badge.svg' />

To make life easier, you can download the buttons.

Detect desktop users

To check if a user is browsing from a mobile or desktop device, parse request.user_agent:


gem 'browser'


# determine the browser and platform
require 'browser'

before do
  @browser ||=

Use the value of browser.device to display the correct store button for the mobile devices:


<% unless @browser.platform.ios? %>
  <a href="">
    <!-- place this image in a public/ folder -->
    <img src="google-play-badge.png" />
<% end %>

<% unless %>
  <a href="">
    <!-- place this image in a public/ folder -->
    <img src='app-store-badge.svg' />
<% end %>

If the user is not using a mobile device, display the button for SMS download:


<% unless %>
  <a href="/download">
    <!-- place this image in a public/ folder -->
    <img src='sms-badge.png' />
<% end %>

This button looks like:


Collect a name and phone number

If your user is browsing from the desktop, use an HTML form to collect both the phone number you will send an SMS to and a name if the user wants to send this link to a friend. When the user clicks the SMS download button in the home page, show them the input form for their phone number.


# Download page
# - a page where the user
#   fills in their phone
#   number in order to get a
#   download link
get '/download' do
  erb :download

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


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

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

When your user clicks Continue, you use SMS API to send them a text message containing the download URL for your app.

You can also send a direct link to the correct stores in the SMS. To do this you update the form so the user can choose their device.

You send an SMS using a single call to SMS API, Nexmo takes care of all the routing and delivery. The following diagram shows the workflow followed in this tutorial to send an SMS:

sequenceDiagram Participant App Participant Nexmo Participant Phone number Note over App: Initialize library App->>Nexmo: Request to SMS API Nexmo-->>App: Response from SMS API Note over Nexmo: Request accepted Nexmo->>Phone number: Send SMS

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


gem 'nexmo'

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


# Nexmo library
require 'nexmo'
nexmo =
  api_key: ENV['NEXMO_API_KEY'],
  api_secret: ENV['NEXMO_API_SECRET']

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

Use the initialized library to make a request to SMS API:


# Send SMS
# - when submitted this action
#   sends an SMS to the user's
#   phone number with a download
#   link
post '/send_sms' do
  message = "Download our app on #{url('/')}"

  # send the message
  response = nexmo.sms.send(
    from: 'My App',
    to: params[:number],
    text: message

  # verify the response
  if response.status == '0'
    flash[:notice] = 'SMS sent'
    redirect '/'
    flash[:error] = response.error-text
    erb :download

The status response parameter tells you if Nexmo has accepted your request and sent the SMS.

To verify that this SMS was received by the user, check the (link: messaging/sms-api/api-reference#delivery_receipt text: delivery receipt). This tutorial does not verify delivery receipts.

Run this tutorial

To run this tutorial:

  1. Spin up your app.
  2. Using your desktop browser, navigate to the Web app.
  3. Click the SMS message button. You are presented with the phone number form.
  4. Fill in and submit the form. Within seconds you receive an SMS text with the link to your app.

Note: if the SMS has a localhost or link, use a tool like ngrok so the tutorial code creates a URL your mobile device can connect to.


That's it. You can now let anyone send themselves or a friend a direct link to download your mobile app in an SMS. To do this you collected a phone number, sent the user a link, detected their platform, and presented them with the correct download link to continue.

Get the Code

All the code for this tutorial is available in the Mobile app invites tutorial GitHub repo.