In this tutorial and the ones to follow, I will take you through some real-life examples of how to integrate Nexmo into your Rails application. We will see how to set up the basics, and then we will write some code together to properly integrate Nexmo. Let's get started!
For this tutorial I assume you will:
- Have a basic understanding of Ruby and Rails
- Have Rails installed on your machine
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.
The easiest way to send an SMS with Ruby is using the
gem install nexmo
This gem conveniently provides an easy wrapper around the Nexmo REST API. To initialize it, just provide the credentials we found earlier.
nexmo = Nexmo::Client.new( key: 'YOUR-API-KEY', secret: 'YOUR-API-SECRET' )
If you are using environment variables in your application you can even shorten this code further, as the gem automatically picks up the
NEXMO_API_SECRET variables if they are specified.
nexmo = Nexmo::Client.new
With our API client in place, sending an SMS is easy, we simply call the
send_message method on the initialized client and pass in the phone number we want to send
to, the Nexmo number we want the number to appear
from, and the
text to send.
response = nexmo.send_message( from: '14155550102', to: '14155550101', text: 'Hello World!' )
There are a lot more parameters that we could pass into this method, have a look at the reference documentation for full details.
In a Rails application we'd probably have a Model for SMS where we can store the
text data before sending it off to Nexmo. In my demo application I've whipped up a simple form and a straightforward model.
When the form is submitted, we store the SMS record and then send the SMS. In a real application, you might use a background queue for this, though in this case we will just pass the SMS record to a new method.
def create @sms = Sms.new(safe_params) if @sms.save deliver @sms redirect_to :outbound_sms, notice: 'SMS Sent' else flash[:alert] = 'Something went wrong' render :index end end private def safe_params params.require(:sms).permit(:to, :from, :text) end
All we are left with then is to send the SMS using the Nexmo API.
def deliver sms response = nexmo.send_message( from: sms.from, to: sms.to, text: sms.text ) if response['messages'].first['status'] == '0' sms.update_attributes( message_id: response['messages'].first['message-id'] ) end end
The response object might contain multiple
message objects, as your request might have been broken up into multiple SMS messages due to the 160 character limit. If the status equals
0 the message has been queued with Nexmo, and we can store the
message-id on the SMS record. The
message-id can be used to track the status of the SMS message, specifically when a Delivery Receipt comes in via a webhook.
Now go ahead, submit the form and within a few seconds you should seen an SMS arrive!
That's it for this tutorial. We've created a Nexmo account, fetched our API credentials, installed and initialized the Ruby gem, and created a deep integration into our Rails application.
You can view the code used in this tutorial on GitHub.