Permalink
Fetching contributors…
Cannot retrieve contributors at this time
323 lines (218 sloc) 9.94 KB

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

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 support@nexmo.com to enable message signing on your account before you can validate webhook signatures.

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