nexmo
v2.9.1
Published
Nexmo REST API client for Node.js. API support for SMS, Voice Calls, Text-to-Speech, Numbers, Verify (2FA) and more.
Downloads
39,650
Readme
Nexmo Client Library for Node.js
A Node.JS REST API Wrapper library for Nexmo.
For full API documentation refer to developer.nexmo.com.
Installation | Constructor | Callbacks | Messaging | Message Signing | Voice | Verify | Number Insight | Applications | Management | Redact | Pricing | JWT (JSON Web Token)
Installation
npm install nexmo
Constructor
const Nexmo = require('nexmo');
const nexmo = new Nexmo({
apiKey: API_KEY,
apiSecret: API_SECRET,
applicationId: APP_ID,
privateKey: PRIVATE_KEY_PATH,
signatureSecret: SIGNATURE_SECRET,
signatureMethod: SIGNATURE_METHOD
}, options);
apiKey
- API Key from Nexmo. IfapplicationId
andprivateKey
are present,apiKey
is optional.apiSecret
- API SECRET from Nexmo. IfapplicationId
andprivateKey
are present,apiSecret
is optional.applicationId
- (optional) The Nexmo Application ID to be used when creating JWTs.privateKey
- (optional) The Private Key to be used when creating JWTs. You can specify the key as any of the following:- A Buffer containing the file contents.
- A String containing the path to the key file on disk.
signatureSecret
- (optional) API singature secret from Nexmo, used for signing SMS message requestssignatureMethod
- (optional) singature method matching the one you gave Nexmo, used for signing SMS message requests. Must be one of "md5hash", "md5", "sha1", "sha256", or "sha512"options
- (optional) Additional options for the constructor.
Options are:
{
// If true, log information to the console
debug: true|false,
// append info the the User-Agent sent to Nexmo
// e.g. pass 'my-app' for /nexmo-node/1.0.0/4.2.7/my-app
appendToUserAgent: string,
// Set a custom logger
logger: {
log: function() {level, args...}
info: function() {args...},
warn: function() {args...}
},
// Set a custom timeout for requests to Nexmo in milliseconds. Defaults to the standard for Node http requests, which is 120,000 ms.
timeout: integer,
// Set a custom host for requests instead of api.nexmo.com
apiHost: string,
// Set a custom host for requests instead of rest.nexmo.com
restHost: string
}
Callbacks
All methods expect a callback
function to be passed in, with a method signature of (error, response)
where:
error
- is an Error object if the API call returns an error, ornull
if the API call was successful.response
- is an Object, with the API response if the API call was successful, ornull
if there was an error.
Example:
callback = (error, response) => {
if (error) {
console.error(error)
}
if (response) {
console.log(response)
}
}
Messaging
Send a text message
nexmo.message.sendSms(sender, recipient, message, options, callback);
options
- parameter is optional. See SMS API Reference
Send a Binary Message
nexmo.message.sendBinaryMessage(fromnumber, tonumber, body, udh, callback);
body
- Hex encoded binary dataudh
- Hex encoded udh
Send a WAP Push Message
nexmo.message.sendWapPushMessage(fromnumber, tonumber, title, url, validity, callback);
validity
- is optional (if given should be in milliseconds)
Send a Short Code alert
nexmo.message.shortcodeAlert(recipient, messageParams, opts, callback);
Voice
For detailed information please see the documentation at https://developer.nexmo.com/api/voice
Make a call
Requires applicationId
and privateKey
to be set on the constructor.
nexmo.calls.create({
to: [{
type: 'phone',
number: TO_NUMBER
}],
from: {
type: 'phone',
number: FROM_NUMBER
},
answer_url: [ANSWER_URL]
}, callback);
For more information see https://developer.nexmo.com/api/voice#createCall
Get a Call
nexmo.calls.get(callId, callback);
For more information see https://developer.nexmo.com/api/voice#getCall
Query Calls
nexmo.calls.get({status: 'completed'}, callback);
The first parameter can contain many properties to filter the returned call or to page results. For more information see the Calls API Reference.
Update a Call
nexmo.calls.update(callId, { action: 'hangup' }, callback);
For more information see https://developer.nexmo.com/api/voice#updateCall
Stream an Audio File to a Call
nexmo.calls.stream.start(
callId,
{
stream_url: [
'https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3'
],
loop: 1
});
For more information see https://developer.nexmo.com/api/voice#startStream
Stop an audio stream in a call
nexmo.calls.stream.stop(callId);
For more information see https://developer.nexmo.com/api/voice#stopStream
Play synthesized text in a call
nexmo.calls.talk.start(
callId,
{
text: 'No songs detected',
voiceName: 'Emma',
loop: 1
}
);
For more information see https://developer.nexmo.com/api/voice#startTalk
Stop synthesized text in a call
nexmo.calls.talk.stop(callId);
For more information see https://developer.nexmo.com/api/voice#stopTalk
Send DTMF to a Call
nexmo.calls.dtmf.send(callId, params, callback);
For more information see https://developer.nexmo.com/api/voice#startDTMF
Files
For detailed information please see the documentation at https://developer.nexmo.com/voice/voice-api/guides/recording
Get a file (recording)
nexmo.files.get(fileIdOrUrl, callback);
Save a file (recording)
nexmo.files.save(fileIdOrUrl, file, callback);
Verify
Submit a Verification Request
nexmo.verify.request({number:<NUMBER_TO_BE_VERIFIED>,brand:<NAME_OF_THE_APP>},callback);
For more information check the documentation at https://developer.nexmo.com/api/verify#verify-request
Submit a PSD2 (Payment Services Directive 2) Verification Request
nexmo.verify.psd2({number:<NUMBER_TO_BE_VERIFIED>,payee:<NAME_OF_THE_SELLER>,amount:<AMOUNT_IN_EUROS>},callback);
For more information check the documentation at https://developer.nexmo.com/api/verify#verifyRequestWithPSD2
Validate the response of a Verification Request
nexmo.verify.check({request_id:<UNIQUE_ID_FROM_VERIFICATION_REQUEST>,code:<CODE_TO_CHECK>},callback);
For more information check the documentation at https://developer.nexmo.com/api/verify#verify-check
Search one or more Verification Request
nexmo.verify.search(<ONE_REQUEST_ID or ARRAY_OF_REQUEST_ID>,callback);
For more information check the documentation at https://developer.nexmo.com/api/verify#verify-search
Cancel verification
nexmo.verify.control({request_id:<UNIQUE_ID_FROM_VERIFICATION_REQUEST>,cmd:'cancel'},callback);
For more information check the documentation at https://developer.nexmo.com/api/verify#verify-control
Trigger next verification event
nexmo.verify.control({request_id:<UNIQUE_ID_FROM_VERIFICATION_REQUEST>,cmd:'trigger_next_event'},callback);
For more information check the documentation at https://developer.nexmo.com/api/verify#verify-control
Number Insight
Basic
nexmo.numberInsight.get({level: 'basic', number: NUMBER}, callback);
For more information check the documentation at https://developer.nexmo.com/number-insight/building-blocks/number-insight-basic/node
Example:
nexmo.numberInsight.get({level: 'basic', number: '1-234-567-8900'}, callback);
Standard
nexmo.numberInsight.get({level: 'standard', number: NUMBER}, callback);
For more information check the documentation at https://developer.nexmo.com/number-insight/building-blocks/number-insight-standard/node
Example:
nexmo.numberInsight.get({level: 'standard', number: '1-234-567-8900'}, callback);
Advanced
nexmo.numberInsight.get({level: 'advancedSync', number: NUMBER}, callback);
For more information check the documentation at https://developer.nexmo.com/number-insight/building-blocks/number-insight-advanced/node
Advanced Async
Number Insight Advanced might take a few seconds to return a result, therefore the option exists to process the result asynchronously through a webhook.
nexmo.numberInsight.get({level: 'advancedAsync', number: NUMBER, callback: "http://example.com"}, callback);
In this case, the result of your insight request is posted to the callback URL as a webhook. For more details on webhooks see the Number Insight Advanced documentation.
Applications
For an overview of applications see https://developer.nexmo.com/concepts/guides/applications
Create an App
nexmo.applications.create(params, callback);
For more information see https://developer.nexmo.com/api/application.v2#createApplication
params
can be
{
"name": "My Application",
"capabilities": {
"voice": {
"webhooks": {
"answer_url": {
"address": "https://example.com/webhooks/answer",
"http_method": "POST"
},
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"messages": {
"webhooks": {
"inbound_url": {
"address": "https://example.com/webhooks/inbound",
"http_method": "POST"
},
"status_url": {
"address": "https://example.com/webhooks/status",
"http_method": "POST"
}
}
},
"rtc": {
"webhooks": {
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"vbc": {}
}
}
Get a single App
nexmo.applications.get(appId, callback, v2flag);
For more information see https://developer.nexmo.com/api/application.v2#getApplication
v2flag
- iftrue
, you'll receive the V2 API response, else you'll receive a V1 style response from the V2 API
Get Apps by a filter
nexmo.applications.get(options, callback, v2flag);
For more information see https://developer.nexmo.com/api/application.v2#listApplication
options
- filter options, use{}
to get all your applicationsv2flag
- iftrue
, you'll receive the V2 API response, else you'll receive a V1 style response from the V2 API
Update an App
nexmo.applications.update(appId, params, callback);
For more information see https://developer.nexmo.com/api/application.v2#updateApplication
Delete an App
nexmo.application.delete(appId, callback);
For more information see https://developer.nexmo.com/api/application.v2#deleteApplication
Management
Check Account Balance
nexmo.account.checkBalance(callback);
List Account Secrets
nexmo.account.listSecrets(apiKey, callback);
Get Account Secret
nexmo.account.getSecret(apiKey, secretId, callback);
Create Account Secret
nexmo.account.createSecret(apiKey, secret, callback);
Delete Account Secret
nexmo.account.deleteSecret(apiKey, secretId, callback);
Get Pricing for sending a message to a country.
nexmo.number.getPricing(countryCode, callback);
countryCode
- 2 letter ISO Country Code
Get Pricing for sending a message or making a call to a number.
nexmo.number.getPhonePricing(product, msisdn, callback);
product
- eithervoice
orsms
msisdn
- Mobile Station International Subscriber Directory Number (MSISDN) is a number used to identify a mobile phone number internationally. i.e. 447700900000
Get all numbers associated with the account.
nexmo.number.get(options, callback);
options
parameter is an optional Dictionary Object containing any of the following parameterspattern
search_pattern
index
size
has_application
application_id
For more details about these options, refer to the Numbers API reference
Example:
nexmo.number.get({pattern:714,index:1,size:50,search_pattern:2}, callback);
Search for MSISDN's available to purchase
nexmo.number.search(countryCode,options,callback);
options
parameter is optional. They can be one of the following :
- number pattern to match the search (eg. 1408)
- Dictionary Object optionally containing the following parameters :
pattern
search_pattern
type
features
index
size
For more details about these options, refer to the Numbers API reference
Example:
nexmo.number.search('US',{pattern:3049,index:1,size:50,type:'mobile-lvn',features:'VOICE',search_pattern:2}, callback);
Purchase Number
nexmo.number.buy(countryCode, msisdn, callback);
// optional target_api_key option
nexmo.number.buy(countryCode, msisdn, target_api_key, callback);
For more details on these parameters, see the Numbers API reference.
Cancel Number
nexmo.number.cancel(countryCode, msisdn, callback);
// optional target_api_key option
nexmo.number.cancel(countryCode, msisdn, target_api_key, callback);
For more details on these parameters, see the Numbers API reference.
Update Number
nexmo.number.update(countryCode, msisdn, params, callback);
params
is a dictionary of parameters as described in the Numbers API reference.
Update Password (API Secret)
nexmo.account.updatePassword(<NEW_PASSWORD>,callback);
Update Callback URL associated to the account
nexmo.account.updateSMSCallback(<NEW_CALLBACK_URL>,callback);
Change Delivery Receipt URL associated to the account
nexmo.account.updateDeliveryReceiptCallback(<NEW_DR_CALLBACK_URL>,callback);
Redact
Redact a specific ID
nexmo.redact.transaction(id, type, callback);
Pricing
type
is the type of service you wish to retrieve pricing for: either sms
, sms-transit
or voice
.
Get pricing for a specific country
nexmo.pricing.get(type, country_code, callback);
Get pricing for all countries
nexmo.pricing.getFull(type, callback);
Get pricing for a specific dialing prefix
nexmo.pricing.getPrefix(type, country_prefix, callback);
Get pricing for a specific phone number
nexmo.pricing.getPhone(type, phone, callback);
Media
Upload a file
nexmo.media.upload({"file": "/path/to/file"}, callback);
Upload from a URL
nexmo.media.upload({"url": "https://example.com/ncco.json"}, callback);
Search existing media
// See https://ea.developer.nexmo.com/api/media#search-media-files
// for possible search parameters
nexmo.media.search({ page_size: 1, page_index: 1 }, callback);
Download media
nexmo.media.download(id, callback);
Delete media
nexmo.media.delete(id, callback);
Update media
nexmo.media.update(id, body, callback);
Get media details
nexmo.media.get(id, callback);
JWT
There are two ways of generating a JWT. You can use the function that exists on the Nexmo definition:
const Nexmo = require('nexmo');
const jwt = Nexmo.generateJwt('path/to/private.key', {application_id: APP_ID});
Or via a Nexmo
instance where your supplied applicationId
and privateKey
credentials will be used:
const Nexmo = require('nexmo');
const nexmo = new Nexmo({
apiKey: API_KEY,
apiSecret: API_SECRET,
applicationId: APP_ID,
privateKey: PRIVATE_KEY_PATH,
});
const jwt = nexmo.generateJwt();
Signature
There are two ways of generating a signature hash. Both strip the sig
parameter if supplied. You can use the function that exists on the Nexmo definition:
const Nexmo = require('nexmo');
const hash = Nexmo.generateSignature(SIGNATURE_METHOD, SIGNATURE_SECRET, params);
Or via a Nexmo
instance where your supplied signatureSecret
and signatureMethod
:
const Nexmo = require('nexmo');
const nexmo = new Nexmo({
apiKey: API_KEY,
apiSecret: API_SECRET,
signatureSecret: SIGNATURE_SECRET,
signatureMethod: SIGNATURE_METHOD,
});
const hash = nexmo.generateSignature();
SIGNATURE_METHOD
is the signature method matching the one you gave Nexmo. Must be one of "md5hash", "md5", "sha1", "sha256", or "sha512".
Voice (Deprecated)
Send TTS Message
nexmo.voice.sendTTSMessage(<TO_NUMBER>,message,options,callback);
Send TTS Prompt With Capture
nexmo.sendTTSPromptWithCapture(<TO_NUMBER>,message,<MAX_DIGITS>, <BYE_TEXT>,options,callback);
Send TTS Prompt With Confirm
nexmo.voice.sendTTSPromptWithConfirm(<TO_NUMBER>, message ,<MAX_DIGITS>,'<PIN_CODE>',<BYE_TEXT>,<FAILED_TEXT>,options,callback);
Testing
Run:
npm test
Or to continually watch and run tests as you change the code:
npm run-script test-watch
Examples
See examples/README.md.
Also, see the Nexmo Node Quickstarts repo.
Creating your own requests
IMPORTANT
This section uses internal APIs and should not be relied on. We make no guarantees that the interface is stable. Relying on these methods is not recommended for production applications
For endpoints that are not yet implemented, you can use the Nexmo HTTP Client to make requests with the correct authentication method.
In these examples, we assume that you've created a nexmo
instance as follows:
const nexmo = new Nexmo({
apiKey: 'API_KEY',
apiSecret: 'API_SECRET',
applicationId: 'APPLICATION_ID',
privateKey: './private.key',
});
- If your API endpoint is on
api.nexmo.com
, use thenexmo.options.api
object. - If your API endpoint is on
rest.nexmo.com
, use thenexmo.options.rest
object.
Both of these objects expose the following methods:
get(path, params, callback, useJwt)
(params
is the query string to use)post(path, params, callback, useJwt)
(params
is the POST body to send)postUseQueryString(path, params, callback, useJwt)
(params
is the query string to use)delete(path, callback, useJwt)
To make a request to api.nexmo.com/v1/calls?status=rejected
:
nexmo.options.api.get(
"/v1/calls",
{"status": "rejected"},
function(err, data){
console.log(err);
console.log(data);
},
true // Use JWT for authentication
);
To make a request to rest.nexmo.com/sms/json?from=Demo&to=447700900000&text=Testing
:
nexmo.options.rest.postUseQueryString(
"/sms/json",
{"from": "Demo", "to": "447700900000", "text": "Testing"},
function(err, data){
console.log(err);
console.log(data);
},
false // Don't use JWT, fall back to API key/secret
);
API Coverage
- Voice
- [x] Outbound Calls
- [ ] Inbound Call Webhook
- [x] Update Calls
- [x] Stream to Call
- [x] Talk to Call
- [x] DTMF to Call
- Messaging
- [x] Send
- [ ] Delivery Receipt Webhook
- [ ] Inbound Message Webhook
- [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
- Number Insight
- [X] Basic
- [X] Standard
- [X] Advanced
- [X] Advanced Async
- [ ] Advanced Async Webhook
- Verify
- [x] Verify
- [x] PSD2
- [x] Check
- [x] Search
- [x] Control
- Applications
- [x] Create an Application
- [x] Get Applications
- [x] Update an Application
- [x] Delete an Application
- Account
- [X] Balance
- [x] Pricing
- [x] Settings
- [x] Top Up
- [x] Numbers
- [x] Search
- [x] Buy
- [x] Cancel
- [x] Update
- Media
- [x] Upload
- [x] Download
- [x] Search
- [x] Get
- [x] Update
- [x] Delete
- Voice (Deprecated)
- [x] Outbound Calls
- [ ] Inbound Call Webhook
- [x] Text-To-Speech Call
- [x] Text-To-Speech Prompt
- Redact
- [x] Transaction
License
MIT - see LICENSE