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
- Secret Management API
- Redact API
- Logging
- JWT authentication
- Webhook signatures
- API coverage
- License
Requirements
Nexmo Ruby supports CRuby 2.1.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 an SMS, 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 an SMS
response = client.sms.send(from: 'Ruby', to: 'YOUR NUMBER', text: 'Hello world')
if response..first.status == '0'
puts "Sent message id=#{response..first.}"
else
puts "Error: #{response..first.error_text}"
end
Docs: https://developer.nexmo.com/api/sms#send-an-sms
Voice API
Create an outbound 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#createCall
Get details of your calls
response = client.calls.list
Docs: https://developer.nexmo.com/api/voice#getCalls
Get detail of a specific call
response = client.calls.get(uuid)
Docs: https://developer.nexmo.com/api/voice#getCall
Modify an in progress call
response = client.calls.hangup(uuid)
Docs: https://developer.nexmo.com/api/voice#updateCall
Play an audio file into a call
stream_url = 'https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3'
response = client.calls.stream.start(uuid, stream_url: [stream_url])
Docs: https://developer.nexmo.com/api/voice#startStream
Stop playing an audio file into a call
response = client.calls.stream.stop(uuid)
Docs: https://developer.nexmo.com/api/voice#stopStream
Play text to speech into a call
response = client.calls.talk.start(uuid, text: 'Hello')
Docs: https://developer.nexmo.com/api/voice#startTalk
Stop text to speech in a call
response = client.calls.talk.stop(uuid)
Docs: https://developer.nexmo.com/api/voice#stopTalk
Play DTMF tones into a call
response = client.calls.dtmf.send(uuid, digits: '1234')
Docs: https://developer.nexmo.com/api/voice#startDTMF
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
Secret Management API
Retrieve a list of secrets
client.secrets.list
Docs: https://developer.nexmo.com/api/account/secret-management#retrieveSecrets
Create a secret
client.secrets.create(secret: 't0ps3cr3t')
Docs: https://developer.nexmo.com/api/account/secret-management#createSecret
Retrieve a secret
client.secrets.get(secret_id)
Docs: https://developer.nexmo.com/api/account/secret-management#retrieveSecret
Revoke a secret
client.secrets.revoke(secret_id)
Docs: https://developer.nexmo.com/api/account/secret-management#revokeSecret
Redact API
Redact a specific message
client.redact.transaction(id: '00A0B0C0', product: 'sms')
Docs: https://developer.nexmo.com/api/redact#transaction
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 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')
client.token = Nexmo::JWT.generate(claims, private_key)
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.
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