With the help of the Vonage SMS API you can send SMS anywhere in the world. All you need is your virtual phone number, the Ruby SDK, and a few lines of code.
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!
View the source code on GitHub
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 nexmo gem.
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_KEY and 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 to, from, and text data before sending it off to Nexmo. In my demo application I've whipped up a simple form and a straightforward model.
The final sending SMS user interface
localhost:3000/outbound_sms
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.
app/controllers/outbound_sms_controller.rb
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)
endAll 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
endThe 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!
Example of an SMS message being received
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.
