Skip to content
master
Switch branches/tags
Go to file
Code
This branch is 6 commits ahead, 47 commits behind Vonage:master.

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Nexmo Client Library for Ruby

Gem Version [Coverage Status Coverage Status

Nexmo is now known as Vonage

This SDK and Ruby gem have moved! It is now vonage, located at vonage/vonage-ruby-sdk.

We will support this repository for 12 months, ending October 2021, with any needed bug or security fixes for the last release of v7.2.1. New features will be released under vonage, so to take advantage of those please make sure to switch to vonage as soon as possible so you don't miss out!

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.com.

Requirements

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

Installation

To install the Ruby client library using Rubygems:

gem install nexmo

Alternatively you can clone the repository:

git clone git@github.com:Nexmo/nexmo-ruby.git

Usage

Begin by requiring the nexmo library:

require 'nexmo'

Then construct a client object with your key and secret:

client = Nexmo::Client.new(api_key: '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.

Logging

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

require 'logger'

logger = Logger.new(STDOUT)

client = Nexmo::Client.new(logger: logger)

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

To disable logging set the logger to nil.

Overriding the default hosts

To override the default hosts that the SDK uses for HTTP requests, you need to specify the api_host, rest_host or both in the client configuration. For example:

client = Nexmo::Client.new(
  api_host: 'api-sg-1.nexmo.com',
  rest_host: 'rest-sg-1.nexmo.com'
)

By default the hosts are set to api.nexmo.com and rest.nexmo.com, respectively.

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 = Nexmo::Client.new(application_id: 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,
  private_key: 'path/to/private.key',
  nbf: 1483315200,
  ttl: 800
}

token = Nexmo::JWT.generate(claims)

client = Nexmo::Client.new(token: token)

Documentation for the Nexmo Ruby JWT generator gem can be found at https://www.rubydoc.info/github/nexmo/nexmo-jwt-ruby. The documentation outlines all the possible parameters you can use to customize and build a token with.

Webhook signatures

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

client = Nexmo::Client.new
client.config.signature_secret = 'secret'
client.config.signature_method = 'sha512'

if client.signature.check(request.GET)
  # valid signature
else
  # invalid signature
end

Alternatively you can set the NEXMO_SIGNATURE_SECRET environment variable.

Note: you'll need to contact support@nexmo.com to enable message signing on your account.

Documentation

Nexmo Ruby documentation: https://www.rubydoc.info/github/nexmo/nexmo-ruby

Nexmo Ruby code examples: https://github.com/Nexmo/nexmo-ruby-code-snippets

Nexmo API reference: https://developer.nexmo.com/api

Frequently Asked Questions

Supported APIs

The following is a list of Vonage APIs and whether the Ruby SDK provides support for them:

API API Release Status Supported?
Account API General Availability
Alerts API General Availability
Application API General Availability
Audit API Beta
Conversation API Beta
Dispatch API Beta
External Accounts API Beta
Media API Beta
Messages API Beta
Number Insight API General Availability
Number Management API General Availability
Pricing API General Availability
Redact API Developer Preview
Reports API Beta
SMS API General Availability
Verify API General Availability
Voice API General Availability

License

This library is released under the MIT License

About

Nexmo REST API client for Ruby. API support for SMS, Voice, Text-to-Speech, Numbers, Verify (2FA) and more.

Resources

License

Packages

No packages published

Languages