How to Send SMS Messages with Ruby on Rails

Despite the rise of messaging apps like WhatsApp and Facebook Messenger, SMS remains essential. It works on any mobile device without extra software, boasts higher engagement for time-sensitive messages, and is the most reliable option since it doesn’t require an internet connection.

This tutorial demonstrates how to send SMS messages in a Ruby on Rails application using Vonage. This is the first post as part of the Vonage Ruby on Rails Quick Start series, getting you started with the core functionality of the Vonage API suite in your Ruby on Rails application.

TL;DR Skip ahead and find all the Quickstart code on GitHub

Note this tutorial series uses the Messages API which easily integrates omnichannel support. Vonage also offers the SMS API.

A demonstration of the Vonage Rails Quickstart application sending an SMS message in real time.

Prerequisites

• Ruby and Rails installed on your machine 

• Vonage Virtual Number

How to Create a Ruby on Rails Application

This tutorial will assume you have a basic understanding of Ruby and Rails, sticking to the commands required without too much deeper explanation.

First, we’ll create our new project.

rails new vonage-rails-quickstart

Next, move into the project and add the Vonage gem to your Gemfile so we can access the Vonage SDK. We’ll also add dotenv-rails so we can use environment variables safely.

#Gemfile
gem 'vonage'
gem 'dotenv-rails', groups: [:development, :test]

Then run the bundler to install our gems.

bundle install

Now, we’ll need to create our SMS model, which defines its attributes and how they are stored in the database. We’ll need 6 fields:

• to: the recipient of the SMS.

• from: the sender of the SMS.

• text: the content of the message.

• status: whether an SMS has successfully been delivered or not. See more information in the API Reference.

• message_uuid: the Vonage ID associated with the message, which will be important for tracking the status of messages.

• is_inbound: whether the message is sent or received by our application; this will be important in the following blog post.

rails g model Sms to:string from:string text:text status:string message_uuid:string is_inbound:boolean --force-plural

We’ll also need to update our database with the new model.

rails db:migrate

Let’s create our controller to handle our logic.

rails g controller OutboundSms index create

Lastly, let’s define our routes for outbound SMS.

# config/routes.rb

Rails.application.routes.draw do
	resources :outbound_sms, only: [:index, :create]
end 

How to Create a Vonage Application

Now that our Rails App is ready, we’ll also need to create and set up our Vonage Application. First, we need to create our app in the Vonage Dashboard. Give the app a name and turn on the Messages capability. You can add placeholder URLs for the webhooks for now. We will update these in further blog posts.

The Vonage Developer dashboard showing the creation of a new application with authentication, privacy, and messaging capabilities settings.

Make sure to generate a private.key, click ‘Generate public and private key’. This will download a private.key file to your computer. Then move the private.key file to the root of your rails application.

When your application is created, take note of the application ID. You’ll need the application ID, your API Key, and your API Secret in the next step.

Create an .env file in the root of your Rails application:

touch .env

Lastly, add the following keys with your credentials.

#.env

# To use Vonage Ruby Client
VONAGE_API_KEY=''
VONAGE_API_SECRET=''
VONAGE_APPLICATION_ID=''
VONAGE_PRIVATE_KEY='./private.key'

How to Initialize the Vonage Ruby Client

The REST API client allows us easy access to 15 Vonage APIs, not just the Messages API. You can learn more about the supported APIs.

To use the client, we’ll just need to initialize an instance with our Vonage credentials stored in our environment file.

# app/controllers/outbound_sms_controller.rb
 def vonage
    Vonage::Client.new(
      api_key: ENV["VONAGE_API_KEY"], 
      api_secret: ENV["VONAGE_API_SECRET"], 
      token: generate_vonage_token
    )
  end

Since we’re using the Messages API, you’ll notice that we need to pass a JWT token. We can also handle this with environment variables.

# app/controllers/outbound_sms_controller.rb
 def generate_vonage_token
    claims = {
      application_id: ENV["VONAGE_APPLICATION_ID"],
      private_key: ENV["VONAGE_PRIVATE_KEY"]
    }
    Vonage::JWT.generate(claims)
  end

How to Send an SMS Message in Ruby

Now that our client is initialized, sending an SMS becomes quite simple. We call the messaging method to tell the client to use the Messages API and then call send with the required fields.

# app/controllers/outbound_sms_controller.rb
response = vonage.messaging.send(
   "message_type": "text",
   "text": "Hello from Vonage!",
   "to": "447700900000",
   "from": "447700900001",
   "channel": "sms"
)

You can see all the options for different channels and fields in the API Reference.

Sending SMS in a Ruby on Rails Application

Now that we’ve covered how to use the Vonage Ruby client to send SMS, let’s integrate a Ruby on Rails send SMS functionality into our app with a simple form and controller. We’ll need a nice UI to handle the to, from, and text fields. You can copy and add the form to your /app/views/outbound_sms/index.html.erb view.

A Vonage-powered SMS form where users can input a sender's phone number or name, the recipient's phone number, and a message before sending an SMS.

Note: Not every country accepts a name as a valid ‘to’ field 

Now, let’s implement the logic to make our form work. First, we’ll need to create an empty SMS instance to load the form. Then we call the create method which saves the SMS to our database and then sends it via the deliver method.

# app/controllers/outbound_sms_controller.rb 

def index
    @sms = Sms.new
  end

  def create
    # Create a SMS record to be stored in the database
    @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

The deliver method is largely the same as what we used in the previous section, except now using the Messages message object and handling the API response.

If the message is sent successfully, it returns a 202 status code along with a message UUID. This UUID helps track delivery status using Delivery Receipts, which we’ll cover in the next post.

 def deliver(sms)
    message = Vonage::Messaging::Message.sms(message: sms.text)

    response = vonage.messaging.send(
      from: sms.from,
      to: sms.to,
      **message
    )

    if response.http_response.code == '202'
      sms.update(
        message_uuid: response.entity.attributes[:message_uuid]
      )
    end
  end

> See the full outbound_sms_controller.rb file.

Now start your rails server rails s and open http://localhost:3000/outbound_sms. You can start sending SMS via your Ruby on Rails app!

Conclusion

You did it! You learned how to build a Vonage application, initialize and use the Vonage Ruby client, and successfully send SMS from a Ruby on Rails application. In future posts, we'll add more SMS and Voice features to this application.

If you have any questions or suggestions for more Ruby content, send us a message over on the Community Slack. You can also stay in the loop on our developer content and events on X, formerly known as Twitter.