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.

Requirements
Installation
Usage
SMS API
Voice API
Verify API
Number Insight API
Application API
Numbers API
Logging
JWT authentication
Webhook signatures
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

Logging

Use the logger option or attribute writer method 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.

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

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 support@nexmo.com to enable message signing on your account.

API coverage

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

License

This library is released under the MIT License

Yaroslav-F/nexmo-ruby

Nexmo Client Library for Ruby

Requirements

Installation

Usage

Credentials

SMS API

Send a text message

Voice API

Make a call

Retrieve a list of calls

Retrieve a single call

Update a call

Stream audio to a call

Stop streaming audio to a call

Send a synthesized speech message to a call

Stop sending a synthesized speech message to a call

Send DTMF tones to a call

Verify API

Start a verification

Check a verification

Cancel a verification

Trigger next verification step

Number Insight API

Basic Number Insight

Standard Number Insight

Advanced Number Insight

Advanced Number Insight Async

Application API

Create an application

Retrieve a list of applications

Retrieve a single application

Update an application

Delete an application

Numbers API

List owned numbers

Search available numbers

Buy a number

Cancel a number

Update a number

Logging

JWT authentication

Webhook signatures

API coverage

License