Nexmo Client Library for Node.js

❗ The SDK and NPM package have moved! The NPM package is now is now @vonage/server-sdk. The code repository is located at vonage/vonage-node-sdk.

We will support this repository for 12 months, ending October 2021, with any needed bug or security fixes for the last release of v2.9.1.

New features will be released under @vonage/server-sdk, so to take advantage of those please make sure to switch to @vonage/server-sdk as soon as possible.

A Node.JS REST API Wrapper library for Nexmo.

For full API documentation refer to developer.nexmo.com.

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. 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:
- 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 requests
signatureMethod - (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, 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)
  }
}

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 data
udh - 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 - if true, 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 applications
v2flag - if true, 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 - either voice or sms
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 parameters
- pattern
- 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 the nexmo.options.api object.
If your API endpoint is on 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
);

API Coverage

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
- PSD2
- 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

License

MIT - see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 553 Commits
.github		.github
examples		examples
src		src
test		test
typings		typings
.babelrc		.babelrc
.editorconfig		.editorconfig
.eslintrc		.eslintrc
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
.nycrc		.nycrc
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.txt		LICENSE.txt
MAINTENANCE.md		MAINTENANCE.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
postinstall.js		postinstall.js

License

Nexmo/nexmo-node

Folders and files

Latest commit

History

Repository files navigation

Nexmo Client Library for Node.js

Installation

Constructor

Callbacks

Messaging

Send a text message

Send a Binary Message

Send a WAP Push Message

Send a Short Code alert

Voice

Make a call

Get a Call

Query Calls

Update a Call

Stream an Audio File to a Call

Stop an audio stream in a call

Play synthesized text in a call

Stop synthesized text in a call

Send DTMF to a Call

Files

Get a file (recording)

Save a file (recording)

Verify

Submit a Verification Request

Submit a PSD2 (Payment Services Directive 2) Verification Request

Validate the response of a Verification Request

Search one or more Verification Request

Cancel verification

Trigger next verification event

Number Insight

Basic

Standard

Advanced

Advanced Async

Applications

Create an App

Get a single App

Get Apps by a filter

Update an App

Delete an App

Management

Check Account Balance

List Account Secrets

Get Account Secret

Create Account Secret

Delete Account Secret

Get Pricing for sending a message to a country.

Get Pricing for sending a message or making a call to a number.

Get all numbers associated with the account.

Search for MSISDN's available to purchase

Purchase Number

Cancel Number

Update Number

Update Password (API Secret)

Update Callback URL associated to the account

Change Delivery Receipt URL associated to the account

Redact

Redact a specific ID

Pricing

Get pricing for a specific country

Get pricing for all countries

Get pricing for a specific dialing prefix

Get pricing for a specific phone number

Media

Upload a file

Upload from a URL

Search existing media

Download media

Delete media

Update media

Get media details

JWT

Signature

Voice (Deprecated)

Packages