Nexmo Client Library for Ruby

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.

Installation
Usage
SMS API
Voice API
Verify API
Number Insight API
Application API
Numbers API
Coverage
License

Requirements

Nexmo Ruby supports CRuby 2.0.0+ and JRuby 9k.

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 send a text message, start a verification, or create an application.

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.

Credentials

To check signatures for incoming webhook requests you'll also need to specify the signature_secret argument:

client = Nexmo::Client.new(signature_secret: 'secret')

Alternatively you can set the NEXMO_SIGNATURE_SECRET environment variable.

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

SMS API

Send a text message

response = client.sms.send(from: 'Ruby', to: 'YOUR NUMBER', text: 'Hello world')

if response.messages.first.status == '0'
  puts "Sent message id=#{response.messages.first.message_id}"
else
  puts "Error: #{response.messages.first.error_text}"
end

Docs: https://developer.nexmo.com/api/sms#request

Voice API

Make a call

response = client.calls.create({
  to: [{type: 'phone', number: '14843331234'}],
  from: {type: 'phone', number: '14843335555'},
  answer_url: ['https://example.com/answer']
})

Docs: https://developer.nexmo.com/api/voice#create-an-outbound-call

Retrieve a list of calls

response = client.calls.list

Docs: https://developer.nexmo.com/api/voice#retrieve-information-about-all-your-calls

Retrieve a single call

response = client.calls.get(uuid)

Docs: https://developer.nexmo.com/api/voice#retrieve-information-about-a-single-call

Update a call

response = client.calls.hangup(uuid)

Docs: https://developer.nexmo.com/api/voice#modify-an-existing-call

Stream audio to a call

stream_url = 'https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3'

response = client.stream.start(uuid, stream_url: stream_url)

Docs: https://developer.nexmo.com/api/voice#stream-an-audio-file-to-an-active-call

Stop streaming audio to a call

response = client.stream.stop(uuid)

Docs: https://developer.nexmo.com/api/voice#stop-streaming-an-audio-file-to-an-active-call

Send a synthesized speech message to a call

response = client.talk.start(uuid, text: 'Hello')

Docs: https://developer.nexmo.com/api/voice#send-a-synthesized-speech-message-to-an-active-call

Stop sending a synthesized speech message to a call

response = client.talk.stop(uuid)

Docs: https://developer.nexmo.com/api/voice#stop-sending-a-synthesized-speech-message-to-an-active-call

Send DTMF tones to a call

response = client.dtmf.send(uuid, digits: '1234')

Docs: https://developer.nexmo.com/api/voice#send-dual-tone-multi-frequency-dtmf-tones-to-an-active-call

Verify API

Start a verification

response = client.verify.request(number: '441632960960', brand: 'MyApp')

if response.status == '0'
  puts "Started verification request_id=#{response.request_id}"
else
  puts "Error: #{response.error_text}"
end

Docs: https://developer.nexmo.com/api/verify#verify-request

The response contains a verification request id which you will need to store temporarily.

Check a verification

response = client.verify.check(request_id: '00e6c3377e5348cdaf567e1417c707a5', code: '1234')

if response.status == '0'
  puts "Verification complete, event_id=#{response.event_id}"
else
  puts "Error: #{response.error_text}"
end

Docs: https://developer.nexmo.com/api/verify#verify-check

The verification request id comes from the call to client.verify.request.

The PIN code is entered into your application by the user.

Cancel a verification

client.verify.cancel('00e6c3377e5348cdaf567e1417c707a5')

Docs: https://developer.nexmo.com/api/verify#verify-control

Trigger next verification step

client.verify.trigger_next_event('00e6c3377e5348cdaf567e1417c707a5')

Docs: https://developer.nexmo.com/api/verify#verify-control

Number Insight API

Basic Number Insight

client.number_insight.basic(number: '447700900000')

Docs: https://developer.nexmo.com/api/number-insight#request

Standard Number Insight

client.number_insight.standard(number: '447700900000')

Docs: https://developer.nexmo.com/api/number-insight#request

Advanced Number Insight

client.number_insight.advanced(number: '447700900000')

Docs: https://developer.nexmo.com/api/number-insight#request

Advanced Number Insight Async

client.number_insight.advanced_async(number: '447700900000', callback: webhook_url)

The results of the API call will be sent via HTTP POST to the webhook URL specified in the callback parameter.

Docs: https://developer.nexmo.com/api/number-insight#request

Application API

Create an application

response = client.applications.create(name: 'Example App', type: 'voice', answer_url: answer_url, event_url: event_url)

Docs: https://developer.nexmo.com/api/application#create-an-application

Retrieve a list of applications

response = client.applications.list

Docs: https://developer.nexmo.com/api/application#retrieve-your-applications

Retrieve a single application

response = client.applications.get(uuid)

Docs: https://developer.nexmo.com/api/application#retrieve-an-application

Update an application

response = client.applications.update(uuid, answer_method: 'POST')

Docs: https://developer.nexmo.com/api/application#update-an-application

Delete an application

response = client.applications.delete(uuid)

Docs: https://developer.nexmo.com/api/application#destroy-an-application

Numbers API

List owned numbers

client.numbers.list

Docs: https://developer.nexmo.com/api/developer/numbers#list-owned-numbers

Search available numbers

client.numbers.search(country: 'GB')

Docs: https://developer.nexmo.com/api/developer/numbers#search-available-numbers

Buy a number

client.numbers.buy(country: 'GB', msisdn: '447700900000')

Docs: https://developer.nexmo.com/api/developer/numbers#buy-a-number

Cancel a number

client.numbers.cancel(country: 'GB', msisdn: '447700900000')

Docs: https://developer.nexmo.com/api/developer/numbers#cancel-a-number

Update a number

client.numbers.update(country: 'GB', msisdn: '447700900000', voice_callback_type: 'app', voice_callback_value: application_id)

Docs: https://developer.nexmo.com/api/developer/numbers#update-a-number

JWT authentication

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 call Nexmo::JWT.generate to generate a token, and set the auth_token attribute on the client object. For example:

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

private_key = File.read('path/to/private.key')

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

client.auth_token = auth_token

Validate webhook signatures

client = Nexmo::Client.new(signature_secret: 'secret')

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

Docs: https://developer.nexmo.com/concepts/guides/signing-messages

Note: you'll need to contact [email protected] to enable message signing on your account before you can validate webhook signatures.

API Coverage

Account
- [X] Balance
- [X] Pricing
- [X] Settings
- [X] Top Up
- [X] Numbers
  - [X] Search
  - [X] Buy
  - [X] Cancel
  - [X] Update
Number Insight
- [X] Basic
- [X] Standard
- [X] Advanced
- [ ] Webhook Notification
Verify
- [X] Verify
- [X] Check
- [X] Search
- [X] Control
Messaging
- [X] Send
- [ ] Delivery Receipt
- [ ] Inbound Messages
- [X] Search
  - [X] Message
  - [X] Messages
  - [X] Rejections
- [X] US Short Codes
  - [X] Two-Factor Authentication
  - [X] Event Based Alerts
    - [X] Sending Alerts
    - [X] Campaign Subscription Management
Voice
- [X] Outbound Calls
- [ ] Inbound Call
- [X] Text-To-Speech Call
- [X] Text-To-Speech Prompt

License

This library is released under the MIT License