Nexmo REST API client for Node.js. API support for SMS, Voice Calls, Text-to-Speech, Numbers, Verify (2FA) and more.
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)
npm install nexmo
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. If applicationId and privateKey are present, apiKey is optional.apiSecret - API SECRET from Nexmo. If applicationId and privateKey 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:
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
}
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, or null if the API call was successful.response - is an Object, with the API response if the API call was successful, or null if there was an error.Example:
callback = (error, response) => {
if (error) {
console.error(error)
}
if (response) {
console.log(response)
}
}
nexmo.message.sendSms(sender, recipient, message, options, callback);
options - parameter is optional. See SMS API Referencenexmo.message.sendBinaryMessage(fromnumber, tonumber, body, udh, callback);
body - Hex encoded binary dataudh - Hex encoded udhnexmo.message.sendWapPushMessage(fromnumber, tonumber, title, url, validity, callback);
validity - is optional (if given should be in milliseconds)nexmo.message.shortcodeAlert(recipient, messageParams, opts, callback);
For detailed information please see the documentation at https://developer.nexmo.com/api/voice
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
nexmo.calls.get(callId, callback);
For more information see https://developer.nexmo.com/api/voice#getCall
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.
nexmo.calls.update(callId, { action: 'hangup' }, callback);
For more information see https://developer.nexmo.com/api/voice#updateCall
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
nexmo.calls.stream.stop(callId);
For more information see https://developer.nexmo.com/api/voice#stopStream
nexmo.calls.talk.start(
callId,
{
text: 'No songs detected',
voiceName: 'Emma',
loop: 1
}
);
For more information see https://developer.nexmo.com/api/voice#startTalk
nexmo.calls.talk.stop(callId);
For more information see https://developer.nexmo.com/api/voice#stopTalk
nexmo.calls.dtmf.send(callId, params, callback);
For more information see https://developer.nexmo.com/api/voice#startDTMF
For detailed information please see the documentation at https://developer.nexmo.com/voice/voice-api/guides/recording
nexmo.files.get(fileIdOrUrl, callback);
nexmo.files.save(fileIdOrUrl, file, callback);
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
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
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
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
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
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
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);
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);
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
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.
For an overview of applications see https://developer.nexmo.com/concepts/guides/applications
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": {}
}
}
nexmo.applications.get(appId, callback, v2flag);
For more information see https://developer.nexmo.com/api/application.v2#getApplication
v2flag - if true, you'll receive the V2 API response, else you'll receive a V1 style response from the V2 APInexmo.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 - if true, you'll receive the V2 API response, else you'll receive a V1 style response from the V2 APInexmo.applications.update(appId, params, callback);
For more information see https://developer.nexmo.com/api/application.v2#updateApplication
nexmo.application.delete(appId, callback);
For more information see https://developer.nexmo.com/api/application.v2#deleteApplication
nexmo.account.checkBalance(callback);
nexmo.account.listSecrets(apiKey, callback);
nexmo.account.getSecret(apiKey, secretId, callback);
nexmo.account.createSecret(apiKey, secret, callback);
nexmo.account.deleteSecret(apiKey, secretId, callback);
nexmo.number.getPricing(countryCode, callback);
countryCode - 2 letter ISO Country Codenexmo.number.getPhonePricing(product, msisdn, callback);
product - either voice or smsmsisdn - Mobile Station International Subscriber Directory Number (MSISDN) is a number used to identify a mobile phone number internationally. i.e. 447700900000nexmo.number.get(options, callback);
options parameter is an optional Dictionary Object containing any of the following parameters
patternsearch_patternindexsizehas_applicationapplication_idFor 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);
nexmo.number.search(countryCode,options,callback);
options parameter is optional. They can be one of the following :
patternsearch_patterntypefeaturesindexsizeFor 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);
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.
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.
nexmo.number.update(countryCode, msisdn, params, callback);
params is a dictionary of parameters as described in the Numbers API reference.
nexmo.account.updatePassword(<NEW_PASSWORD>,callback);
nexmo.account.updateSMSCallback(<NEW_CALLBACK_URL>,callback);
nexmo.account.updateDeliveryReceiptCallback(<NEW_DR_CALLBACK_URL>,callback);
nexmo.redact.transaction(id, type, callback);
type is the type of service you wish to retrieve pricing for: either sms, sms-transit or voice.
nexmo.pricing.get(type, country_code, callback);
nexmo.pricing.getFull(type, callback);
nexmo.pricing.getPrefix(type, country_prefix, callback);
nexmo.pricing.getPhone(type, phone, callback);
nexmo.media.upload({"file": "/path/to/file"}, callback);
nexmo.media.upload({"url": "https://example.com/ncco.json"}, callback);
// 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);
nexmo.media.download(id, callback);
nexmo.media.delete(id, callback);
nexmo.media.update(id, body, callback);
nexmo.media.get(id, callback);
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();
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".
nexmo.voice.sendTTSMessage(<TO_NUMBER>,message,options,callback);
nexmo.sendTTSPromptWithCapture(<TO_NUMBER>,message,<MAX_DIGITS>, <BYE_TEXT>,options,callback);
nexmo.voice.sendTTSPromptWithConfirm(<TO_NUMBER>, message ,<MAX_DIGITS>,'<PIN_CODE>',<BYE_TEXT>,<FAILED_TEXT>,options,callback);
Run:
npm test
Or to continually watch and run tests as you change the code:
npm run-script test-watch
See examples/README.md.
Also, see the Nexmo Node Quickstarts repo.
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',
});
api.nexmo.com, use the nexmo.options.api object.rest.nexmo.com, use the nexmo.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
);
MIT - see LICENSE
2.9.1
FAQs
Nexmo REST API client for Node.js. API support for SMS, Voice Calls, Text-to-Speech, Numbers, Verify (2FA) and more.
The npm package nexmo receives a total of 5,307 weekly downloads. As such, nexmo popularity was classified as popular.
We found that nexmo demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.