Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A Ruby wrapper for the Nexmo API

branch: master


A Ruby wrapper for the Nexmo API.


$ gem install nexmo

Quick start (sending a message)

First you need to load up the gem and construct a Nexmo::Client object with your API credentials, like this:

require 'nexmo'

nexmo ='...API KEY...', '...API SECRET...')

Then you have a choice. For a "fire and forget" approach to sending a message, use the send_message! method, like this:

nexmo.send_message!({:to => '...NUMBER...', :from => 'Ruby', :text => 'Hello world'})

This method call returns the message id if the message was sent successfully, or raises an exception if there was an error. If you need more robust error handling use the send_message method instead, like this:

response = nexmo.send_message({:to => '...NUMBER...', :from => 'Ruby', :text => 'Hello world'})

if response.ok?
  # do something with response.object
  # handle the error

This method call returns a Nexmo::Response object, which wraps the underlying Net::HTTP response and adds a few convenience methods. Additional methods are also provided for managing your account and messages.

Authenticating with OAuth (beta)

If you are building an app that needs access to Nexmo resources on behalf of other accounts then you will want to use OAuth to authenticate your requests. Authorizing access and fetching access tokens can be achieved using the oauth gem directly. You can then use an OAuth::AccessToken object together with a Nexmo::Client object to make calls to the API that are authenticated using OAuth. For example:

require 'nexmo'
require 'oauth'

nexmo =
nexmo.oauth_access_token =, token, secret)

response = nexmo.get_balance

if response.ok?
  # do something with response.object
  # handle the error

The OAuth::Consumer object should be pointed at with the :scheme option set to :header, like this:, consumer_secret, {
  :site => '',
  :scheme => :header

Using the :body or :query_string authorization mechanisms is not supported.

Custom response behaviour

You can customise the response handling by passing a block when constructing a Nexmo::Client object. For example, if you want to use an alternative JSON implementation to decode response bodies, you could do this:

nexmo = do |response|
  response.object = MultiJson.load(response.body) if response.ok? && response.json?

This might also be useful if you prefer a different style of error handling (e.g. raising exceptions on error and returning the response object directly for 200 OK responses), if you need to log responses etc.


Remember that phone numbers should be specified in international format.

The Nexmo documentation contains a list of error codes which may be useful if you have problems sending a message.

Please report all bugs/issues via the GitHub issue tracker.

Something went wrong with that request. Please try again.