A Node.JS REST API Wrapper library for Nexmo.
For full API documentation refer to docs.nexmo.com.
Installation | Constructor | Messaging | Voice | Verify | Number Insight | Applications | Management | Redact | 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,
}, options);
apiKey
- API Key from NexmoapiSecret
- API SECRET from NexmoapplicationId
- The Nexmo Application ID to be used when creating JWTs. Required for voice-related functionality.privateKey
- The Private Key to be used when creating JWTs. You can specify the key as any of the following:- The private key as a string (It must start with
-----BEGIN PRIVATE KEY-----
) - A Buffer containing the file contents. Required for voice-related functionality.
- A path to the key file on disk
- The private key as a string (It must start with
options
- 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
}
nexmo.message.sendSms(sender, recipient, message, options, callback);
opts
- parameter is optional. See SMS API Reference
nexmo.message.sendBinaryMessage(fromnumber, tonumber, body, udh, callback);
body
- Hex encoded binary dataudh
- Hex encoded udh
nexmo.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://docs.nexmo.com/voice/voice-api
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://docs.nexmo.com/voice/voice-api/api-reference#call_create
nexmo.calls.get(callId, callback);
For more information see https://docs.nexmo.com/voice/voice-api/api-reference#call_create
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#modify-an-existing-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://docs.nexmo.com/voice/voice-api/api-reference#stream_put
nexmo.calls.stream.stop(callId);
For more information see https://docs.nexmo.com/voice/voice-api/api-reference#stream_delete
nexmo.calls.talk.start(
callId,
{
text: 'No songs detected',
voiceName: 'Emma',
loop: 1
}
);
For more information see https://docs.nexmo.com/voice/voice-api/api-reference#talk_put
nexmo.calls.talk.stop(callId);
nexmo.calls.dtmf.send(callId, params, callback);
For more information see https://docs.nexmo.com/voice/voice-api/api-reference#dtmf_put
For detailed information please see the documentation at https://docs.nexmo.com/voice/voice-api/recordings
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://docs.nexmo.com/verify/api-reference/api-reference#vrequest
nexmo.verify.check({request_id:<UNIQUE_ID_FROM_VERIFICATION_REQUEST>,code:<CODE_TO_CHECK>},callback);
For more information check the documentation at https://docs.nexmo.com/verify/api-reference/api-reference#check
nexmo.verify.search(<ONE_REQUEST_ID or ARRAY_OF_REQUEST_ID>,callback);
For more information check the documentation at https://docs.nexmo.com/verify/api-reference/api-reference#search
nexmo.verify.control({request_id:<UNIQUE_ID_FROM_VERIFICATION_REQUEST>,cmd:'cancel'},callback);
For more information check the documentation at https://docs.nexmo.com/verify/api-reference/api-reference#control
nexmo.verify.control({request_id:<UNIQUE_ID_FROM_VERIFICATION_REQUEST>,cmd:'trigger_next_event'},callback);
For more information check the documentation at https://docs.nexmo.com/verify/api-reference/api-reference#control
nexmo.numberInsight.get({level: 'basic', number: NUMBER}, callback);
For more information check the documentation at https://docs.nexmo.com/number-insight/basic
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://docs.nexmo.com/number-insight/standard
Example:
nexmo.numberInsight.get({level: 'standard', number: '1-234-567-8900'}, callback);
nexmo.numberInsight.get({level: 'advanced', number: NUMBER}, callback);
For more information check the documentation at https://docs.nexmo.com/number-insight/advanced
Number Insight Advanced might take a few seconds to return a result, therefore the option exist 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://docs.nexmo.com/tools/application-api
nexmo.applications.create(name, type, answerUrl, eventUrl, options, callback);
For more information see https://docs.nexmo.com/tools/application-api/api-reference#create
nexmo.applications.get(appId, callback);
For more information see https://docs.nexmo.com/tools/application-api/api-reference#retrieve
nexmo.application.get(options, callback);
For more information see https://docs.nexmo.com/tools/application-api/api-reference#list
nexmo.applications.update(appId, name, type, answerUrl, eventUrl, options, callback);
For more information see https://docs.nexmo.com/tools/application-api/api-reference#update
nexmo.application.delete(appId, callback);
For more information see https://docs.nexmo.com/tools/application-api/api-reference#delete
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 Code
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
nexmo.number.get(options, callback);
options
parameter is an optional Dictionary Object containing any of the following parameterspattern
search_pattern
index
size
For more details on what the above options mean refer to the Nexmo API documentation
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 :
- number pattern to match the search (eg. 1408)
- Dictionary Object optionally containing the following parameters :
pattern
search_pattern
features
index
size
For more details on what the above options mean refer to the Nexmo API documentation
Example:
nexmo.number.search('US',{pattern:3049,index:1,size:50,features:'VOICE',search_pattern:2}, callback);
nexmo.number.buy(countryCode, msisdn, callback);
nexmo.number.cancel(countryCode, msisdn, callback);
nexmo.number.update(countryCode, msisdn, params, callback);
params is a dictionary of parameters per documentation
nexmo.account.updatePassword(<NEW_PASSWORD>,callback);
nexmo.updateSMSCallback(<NEW_CALLBACK_URL>,callback);
nexmo.account.updateDeliveryReceiptCallback(<NEW_DR_CALLBACK_URL>,callback);
nexmo.redact.transaction(id, type, 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();
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',
});
- 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
);
- Voice
- Outbound Calls
- Inbound Call Webhook
- Update calls
- Stream to Call
- Talk to Call
- DTMF to Call
- Messaging
- Send
- Delivery Receipt Webhook
- Inbound Message Webhook
- Search
- Message
- Messages
- Rejections
- US Short Codes
- Two-Factor Authentication
- Event Based Alerts
- Sending Alerts
- Campaign Subscription Management
- Number Insight
- Basic
- Standard
- Advanced
- Advanced Async
- Advanced Async Webhook
- Verify
- Verify
- Check
- Search
- Control
- Applications
- Create an Application
- Get Applications
- Update an Application
- Delete an Application
- Account
- Balance
- Pricing
- Settings
- Top Up
- Numbers
- Search
- Buy
- Cancel
- Update
- Media
- Upload
- Download
- Search
- Get
- Update
- Delete
- Voice (Deprecated)
- Outbound Calls
- Inbound Call Webhook
- Text-To-Speech Call
- Text-To-Speech Prompt
- Redact
- Transaction
MIT - see LICENSE