Nexmo Client Library for Ruby

Gem Version Build Status Coverage Status

This is the Ruby client library for Nexmo's API. To use it you'll need a Nexmo account. Sign up for free at


Nexmo Ruby supports MRI/CRuby (2.5 or newer), JRuby (9.2.x), and Truffleruby.


To install the Ruby client library using Rubygems:

gem install nexmo

Alternatively you can clone the repository:

git clone


Begin by requiring the nexmo library:

require 'nexmo'

Then construct a client object with your key and secret:

client = 'YOUR-API-KEY', api_secret: 'YOUR-API-SECRET')

You can now use the client object to call Nexmo APIs. For example, to send an SMS:

client.sms.send(from: 'Ruby', to: '447700900000', text: 'Hello world')

For production you can specify the NEXMO_API_KEY and NEXMO_API_SECRET environment variables instead of specifying the key and secret explicitly, keeping your credentials out of source control.


Use the logger option to specify a logger. For example:

require 'logger'

logger =

client = logger)

By default the library sets the logger to Rails.logger if it is defined.

To disable logging set the logger to nil.

JWT authentication

To call newer endpoints that support JWT authentication such as the Voice API you'll also need to specify the application_id and private_key options. For example:

client = application_id, private_key: private_key)

Both arguments should have string values corresponding to the id and private_key values returned in a "create an application" response. These credentials can be stored in a datastore, in environment variables, on disk outside of source control, or in some kind of key management infrastructure.

By default the library generates a short lived JWT per request. To generate a long lived JWT for multiple requests or to specify JWT claims directly use Nexmo::JWT.generate and the token option. For example:

claims = {
  application_id: application_id,
  nbf: 1483315200,
  exp: 1514764800,
  iat: 1483228800

private_key ='path/to/private.key')

token = Nexmo::JWT.generate(claims, private_key)

client = token)

Webhook signatures

To check webhook signatures you'll also need to specify the signature_secret option. For example:

client = 'secret')

if client.signature.check(request.GET)  # valid signature

  # invalid signature

Alternatively you can set the NEXMO_SIGNATURE_SECRET environment variable.

Note: you'll need to contact [email protected] to enable message signing on your account.


Nexmo Ruby documentation:

Nexmo Ruby code examples:

Nexmo API reference:


This library is released under the MIT License