Back at RailsConf 2016, we adopted the community-driven Nexmo Ruby gem and made it an officially supported client library. Since then, Ruby developers have been able to integrate Nexmo into their applications with more ease. Whether you were looking to create a Voice app, send or receive an SMS, obtain insights on numbers around the world, or more, you could do it with the Nexmo Ruby gem.
We are excited to share at RailsConf 2019 that we have taken another step to make it even easier for Ruby on Rails developers to use the full suite of Nexmo APIs in their Rails applications with the new Nexmo Rails gem. The Nexmo Rails gem performs another integration step for you by initializing a Nexmo client instance and making it available throughout your application.
Nexmo enables you to create sophisticated Rails applications using our broad range of cloud communications APIs. The Nexmo Rails gem makes it simple and straightforward to get started. Here's how to install the Nexmo Rails gem:
First, add the Nexmo Rails gem to your
# Gemfile gem 'nexmo-rails'
bundle install from your command line to install the dependency.
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.
You need to provide the gem with your Nexmo API credentials to access the functionality of our APIs. Once you have created your Nexmo account, navigate to your dashboard and add your API key and API secret to the
.env file in the root folder of your application:
# .env NEXMO_API_KEY= # Your API key NEXMO_API_SECRET= # Your API secret
Some of the Nexmo APIs also require an API signature, private key, or application ID. You can add those, if appropriate, to your
.env as well:
# .env NEXMO_API_SIGNATURE= # Your API signature NEXMO_PRIVATE_KEY= # Path to your private key file NEXMO_APPLICATION_ID= # Your application ID
Ensure you have installed the
dotenv-rails gem and added the
.env file to your
.gitignore so as not to commit your credentials to version control.
Now you are ready to initialize a Nexmo client for your application. This is easily done by running the initializer from your command line:
$ rails generate nexmo_initializer
This creates an initializer file in
nexmo.rb that contains the details your application requires to instantiate the Nexmo client. Now, when you start your Rails application, you have access to a fully-authenticated Nexmo instance to begin sending text messages, creating voice interactivity, and much more.
Now that your Nexmo Rails gem has been successfully installed and you have run the Nexmo initializer, you can begin to use the Nexmo client anywhere inside your application.
To use the Nexmo client, reference the
Nexmo instance followed by the specific method and parameters you wish to use. For example, to send an SMS you would do the following:
Nexmo.sms.send(from: '14155550100', to: '14155550101', text: 'Hello world')
To retrieve details about a number using the standard Number Insight API you would use the following:
To search for available phone numbers in the United States you would run the following:
More information on all the available functionality within the Nexmo Ruby client library can be found on GitHub. All of the methods within the Ruby client library can be accessed with the Rails gem—just remember to substitute the variable name
client in the Ruby client library examples with
We are so thrilled to share this during RailsConf 2019 in Minneapolis. As mentioned earlier, it was during RailsConf 2016 in Kansas City that we unveiled the Nexmo Ruby gem, and it is really meaningful to continue the tradition of new and exciting developments at this year's conference.
Come and find our booth at the conference. We'll be there with good conversation and, of course, lots of swag. We would love to hear about how you are using Nexmo in your applications or how you are thinking of incorporating Nexmo in future work. Let us know you'll be there by tweeting @NexmoDev with the hashtag #railsconf.