Nexmo Client Library for Ruby

Gem Version Build 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.com.

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(key: 'YOUR-API-KEY', secret: 'YOUR-API-SECRET')

For production you can specify the NEXMO_API_KEY and NEXMO_API_SECRET environment variables instead of specifying the key and secret explicitly.

For newer endpoints that support JWT authentication such as the Voice API, you can also specify the application_id and private_key arguments:

client = Nexmo::Client.new(application_id: application_id, private_key: private_key)

In order to check signatures for incoming webhook requests, you'll also need to specify the signature_secret argument (or the NEXMO_SIGNATURE_SECRET environment variable).

SMS API

Send a text message

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

if response['messages'][0]['status'] == '0'
  puts "Sent message #{response['messages'][0]['message-id']}"
else
  puts "Error: #{response['messages'][0]['error-text']}"
end

Docs: https://docs.nexmo.com/messaging/sms-api/api-reference#request

Voice API

Make a call

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

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_create

Retrieve a list of calls

response = client.get_calls

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_retrieve

Retrieve a single call

response = client.get_call(uuid)

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_retrieve_single

Update a call

response = client.update_call(uuid, action: 'hangup')

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_modify_single

Stream audio to a call

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

response = client.send_audio(uuid, stream_url: stream_url)

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#stream_put

Stop streaming audio to a call

response = client.stop_audio(uuid)

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#stream_delete

Send a synthesized speech message to a call

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

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#talk_put

Stop sending a synthesized speech message to a call

response = client.stop_speech(uuid)

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#talk_delete

Send DTMF tones to a call

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

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#dtmf_put

Verify API

Start a verification

response = client.start_verification(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://docs.nexmo.com/verify/api-reference/api-reference#vrequest

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

Check a verification

response = client.check_verification('00e6c3377e5348cdaf567e1417c707a5', code: '1234')

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

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

The verification request id comes from the call to the start_verification method.

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

Cancel a verification

client.cancel_verification('00e6c3377e5348cdaf567e1417c707a5')

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

Trigger next verification step

client.trigger_next_verification_event('00e6c3377e5348cdaf567e1417c707a5')

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

Application API

Create an application

response = client.create_application(name: 'Example App', type: 'voice', answer_url: answer_url)

Docs: https://docs.nexmo.com/tools/application-api/api-reference#create

Retrieve a list of applications

response = client.get_applications

Docs: https://docs.nexmo.com/tools/application-api/api-reference#list

Retrieve a single application

response = client.get_application(uuid)

Docs: https://docs.nexmo.com/tools/application-api/api-reference#retrieve

Update an application

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

Docs: https://docs.nexmo.com/tools/application-api/api-reference#update

Delete an application

response = client.delete_application(uuid)

Docs: https://docs.nexmo.com/tools/application-api/api-reference#delete

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.auth_token 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.auth_token(claims, private_key)

client.auth_token = auth_token

Validate webhook signatures

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

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

Docs: https://docs.nexmo.com/messaging/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