vonage / vonage-node-sdk

Vonage API client for Node.js. API support for SMS, Voice, Text-to-Speech, Numbers, Verify (2FA) and more.

Vonage Server SDK for Node.js

This is the Node.JS Server SDK for Vonage APIs. To use it you will need a Vonage account. Sign up for free at vonage.com.

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

• Installation
• Constructor
• Promises
• Testing
• Examples
• References

Installation

With NPM

npm install @vonage/server-sdk

With Yarn

yarn add @vonage/server-sdk

Constructor

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage(credentials, options);

Where credentials is any option from @vonage/auth, and options is any option from @vonage/server-client

Promises

Most methods that interact with the Vonage API uses Promises. You can either resolve these yourself, or use await to wait for a response.

const resp = await vonage.sms.send({
    to: '15552220000',
    from: '15559992222',
    text: 'This is a test',
});

Testing

Run:

npm run test

Or to continually watch and run tests as you change the code:

npm run test-watch

Examples

See the Vonage Node Quickstarts repo.

References

You can find more information for each product below:

• Accounts
• Applications
• Audit
• Auth
• JWT
• Messages
• Number Insight V2
• Number Insights
• Numbers
• Pricing
• Server Client
• Server SDK
• SMS
• Sub Accounts
• Verify
• Verify V2
• Vetch
• Video
• Voice

Supported APIs

The following is a list of Vonage APIs and whether the Node Server SDK provides support for them:

API	API Release Status	Supported?
Account API	General Availability	✅
Alerts API	General Availability	✅
Application API	General Availability	✅
Audit API	Beta	✅
Conversation API	Beta	❌
Dispatch API	Beta	❌
External Accounts API	Beta	❌
Media API	Beta	❌
Messages API	Beta	✅
Number Insight V2 API	Beta	✅
Number Insights API	General Availability	✅
Number Management API	General Availability	✅
Pricing API	General Availability	✅
Proactive Connect API	Beta	✅
Redact API	Developer Preview	✅
Reports API	Beta	❌
SMS API	General Availability	✅
Sub Accounts	Beta	✅
Users	General Availability	✅
Verify API	General Availability	✅
Verify v2 API	General Availability	✅
Video API	General Availability	✅
Voice API	General Availability	✅

V2 Migrations

While most of the V2 functions have been ported into their own package, some of the functions have not been ported or were removed. Below is a list of those changes:

V2 Function	Status	Note
vonage.conversion	REMOVED
vonage.conversation	Not Implemented	This was only released as a beta package
vonage.app	Moved	Moved to Applications
vonage.files	Moved	Move to ServerClient
vonage.message	Moved	Moved to SMS
vonage.generateJwt	Moved	Was moved to JWT
vonage.generateSignature	Moved	Was moved to SMS and Voice
vonage.calls	Moved	Was moved to Voice
vonage.credentials	Updated	Options can be found in Server Client
vonage.options	Updated	Options can be found in Server Client
vonage.options.httpClient	Removed
vonage.options.userAgent	Moved	Options can be found in Server Client

For more information, check out each packages migration guide.

vonage-node-sdk's Issues

Update README to document what callback receives

[Edit by @cbetta]

Add documentation on what callback actually is. For most people it's clear to be a function but even then it would be good to document what to expect exactly.

[Original issue]

Hello there,
would it be possible to add the response to all function calls ?
Otherwise I am unable to determine if for example an SMS message was sent.

Cheers.

I'm getting 411 error code randomly when creating a call.

Voice API is returning 411 "length-required" code from time to time. Fixed by forking the nexmo library and including "Content-Length" header.

Add support for retrieving call recordings

For @jonlingard :)

Generally missing across the board on docs and in other libraries.

Runtime error using searchNumbers

I'm getting an error on this line: https://github.com/Nexmo/nexmo-node/blob/9136d8471ea27487bdec95f1bdd78261a1afe621/lib/nexmo.js#L290

.../easynexmo/lib/nexmo.js:290
            for (arg in pattern){
                 ^

ReferenceError: arg is not defined

Seems arg should be declared earlier or inline to be valid JS.

From v1.0 update package to be `nexmo` in NPM

Nexmo now has access to the nexmo package.

Suggested plan:

• Mark easynexmo as deprecated https://docs.npmjs.com/cli/deprecate
• Publish v1.0 of this repo as nexmo

Any concerns or thoughts regarding this approach?

error in README.md

The function prototype in the readme for sendTextMessage() is incorrect as it does not include the "opts" parameter. It should be sendTextMessage(sender,recipient,message,opts,callback)

Using nexmo sandbox!

Hi, is there a way to make the request of the library go to
http://rest-sandbox.nexmo.com ?
I didn't see any mention about this. But in test environement i need to try out my logic before making actual requests.

Can version installed by npm be updated to include content-length fix please

Add Insights Advanced sync callback

Necessary for Nexmo/nexmo-cli#87

Implement promise styled api?

Consider implement promise styled api?

Add way to generate JWT with App ID and Key to be used from outside module

This is needed for Nexmo/nexmo-cli#88

@leggetter you already added a JwtGenerator but I can't use this from the CLI as it's not being exported yet by the module. What do you reckon we do, export the class or an instance?

Support private key as authentication vs file?

I currently find the library to be a bit inconsistent when it comes to private keys. As a user I am left to write a key to file:

var Nexmo = require('nexmo');

var nexmo = new Nexmo({
    apiKey: 'key',
    apiSecret: 'secret',
});


nexmo.app.create(
  'First Voice App',
  'voice',
  'http://example.com/answer',
  'http://example.com/event',
  {},
  function(err, res) {
    var appId = res.id;
    var privateKey = res.keys.private_key;
    var privateKeyFile = __dirname + '/' + appId;
    require('fs').writeFileSync(privateKeyFile, privateKey);
  }
);

But then when I try to configure the library with a key it requires a filename and reads the file:

  nexmo = new Nexmo({
      apiKey: 'key',
      apiSecret: 'secret',
      applicationId: appId,
      privateKey: privateKeyFile
    });

I somehow think it would make a lot more sense for the initializer to just accept the key itself and not bother itself with reading from disc. This would also make it possible to create an app and then reinitialize the library in a few lines of code without having to write the key to disc.

Final note: I might want to save my API key somewhere else on the disk (another volume, database, etc) so having this option would be useful regardless.

Thoughts @leggetter @tjlytle ?

problam on ver 0.6

when i tried to update to version 0.6 the first sms worked fine but all the other send to the same number of the first sms and with the option i provided in the end of the sms text.

TypeError: Cannot read property 'sendSms' of undefined Help

Hey Guys,

So I've run into an issue when I go and try to send an SMS and it seems like nexmo isn't being defined at all. I've tried this on staging a local however I can't seem to resolve the issue. Here's the code I have

Init.

    const Nexmo = require('nexmo');
    const nexmo = Nexmo({ apiKey: 'super', apiSecret: 'Secret' });

    nexmo.message.sendSms(sender,recipent,message,{},function(err, message){

	    if (err) {
		    console.log(err);
	   }
    
    });

and here's the error

    TypeError: Cannot read property 'create' of undefined
        at Object.<anonymous> (C:\Users\User\Documents\Projects\project\testing.js:25:12)
        at Module._compile (module.js:570:32)
        at Object.Module._extensions..js (module.js:579:10)
       at Module.load (module.js:487:32)
       at tryModuleLoad (module.js:446:12)
       at Function.Module._load (module.js:438:3)
       at Module.runMain (module.js:604:10)
       at run (bootstrap_node.js:394:7)
       at startup (bootstrap_node.js:149:9)

Any ideas or help?
Thanks, Colin

Handle non 2xx status codes from Nexmo API

When the Nexmo API responds with a non 2xx status code an appropriate response should be printed.

Perhaps something like:

Nexmo API is currently experiencing problems. Please see https://status.nexmo.com for more
information. If your problem persists please contact support at https://help.nexmo.com

sendTextMessage to multiple numbers in a single call

My following code is working fine for sending text message to single recipient. can i send sms to multiple numbers in a single call?

var nexmo = require('easynexmo');
nexmo.initialize(KEY, SECRET, DEBUG);

function callback (err,messageResponse) {
    if (err) {
                console.log(err);
        } else {
                console.log(messageResponse);
        }
}

Handlers.nexmoHandlers = function(request, reply) {
    nexmo.sendTextMessage(S_XXXXXXXX,R_YYYYYYYYY,'Group message',callback);
    reply("nexmo sms");
};
{
    path: '/nexmo',
    method: 'GET',
    handler: Handlers.nexmoHandlers,
    config: {
        auth: false
    }
}

sms error 411

Hi again,
When I send sms using the api, using {} as option and a callback, I systematically get
{ success: false, errors: [ { message: '', code: 411 } ] }
When using the debug mod, I am able to get the query path.. It works perfectly with postman!
Any idea?

createApplication does not like spaces in the name

> nexmo.createApplication('FooBar 1', 'voice', 'http://example.com/', 'http://example.com', {}, function(err, res) { console.log(err); console.log(res) });
TypeError: Request path contains unescaped characters
    at new ClientRequest (_http_client.js:53:11)
    at Object.exports.request (http.js:31:10)
    at Object.exports.request (https.js:199:15)
    at sendRequest (/Users/cbetta/code/nexmo/nexmo-cli/node_modules/easynexmo/lib/nexmo.js:228:27)
    at Object.exports.createApplication (/Users/cbetta/code/nexmo/nexmo-cli/node_modules/easynexmo/lib/nexmo.js:407:7)
    at repl:1:7
    at REPLServer.defaultEval (repl.js:272:27)
    at bound (domain.js:280:14)
    at REPLServer.runBound [as eval] (domain.js:293:12)
    at REPLServer.<anonymous> (repl.js:441:10)

Handle 504 errors in the API

(Via @adambutler)

When the Nexmo API responds with a non 2xx status code an appropriate response should be printed.

Perhaps something like:

Nexmo API is currently experiencing problems. Please see https://status.nexmo.com for more
information. If your problem persists please contact support at https://help.nexmo.com

npm install easynexmo - not latest

The nexmo.js file doesn't include the latest changes:

"Added support for additional options to be passed [justinfreitag]".

sendTextMessage function doesn't include options to be passed in the current npm version:

exports.sendTextMessage = function(sender,recipient,message, callback) {
if (!message) {
sendError(callback,new Error(ERROR_MESSAGES.msg));
} else {
sendMessage({from:sender,to:recipient,text:message},callback);
}
}

Use Travis to publish new releases to NPM

Currently we are doing this manually but this can be automated with Travis. The simplest way to do this is by listening to new tags being published.

Benefits:

• We can limit publish access for the gem to the NPM nexmo user only
• NPM.js will no longer list a user as the "owner" if a release was pushed by that user
• Every new release will be forced to pass tests
• Every new release will be tagged

I've implemented this with other clients and it should be totally doable.

Add active linting to tests

We should add linting to our tests and ensure all linting passes before code is merged. This will initially require one big refactor to lint all the current code. Things we should look at fixing:

• Strip trailing white space
• Pick tabs or spaces - probably 4 spaces
• Pick whether to enforce trailing semi colons
• Enforce camel case over snake case

Add support for calling Standard Number Insight API

https://docs.nexmo.com/number-insight/standard

Runtime error in cancelNumber

Getting a SyntaxError: Unexpected end of JSON input due to this line: https://github.com/Nexmo/nexmo-node/blob/master/lib/nexmo.js#L319

CLI enable environment selection

I would like to be able to define what environment the CLI should be working against currently it seems hardcoded to only work with Production env

A good solutions is is an argument which can be set as part of command

so for exmaple to check your balance, you would do :

nexmo balance --host "URL"
18.96 EUR

Change default to https

Per https://help.nexmo.com/hc/en-us/articles/213877768-Enforcing-mandatory-use-of-secure-HTTP-HTTPS-on-Dec-15th-2015

Support for sending options to getNumbers and searchNumbers API

Add support for calling Basic Number Insight API

https://docs.nexmo.com/number-insight/basic

Add license field to package.json

Need to know the proper way to implement numberInsight and the callback

I'm currently stuck trying to implement the callback for the numberInsight API
I'm "new" to javascript and express so any help would be much appreciated
I need to use the api to extract the city data from phone number when they text in and i'm getting stuck at the callback portion :(

Stream fails due to undefined method

Streaming mp3 fails due to the method being undefined when it's supposed to be PUT

Output of debug when using stream

info: Request: { host: 'api.nexmo.com', port: 443, path: '/v1/calls/-call-id/stream', method: undefined, headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': 'nexmo-node/1.1.0/v4.6.1', 'Content-Length': 81, Authorization: '--' } } Body: {"stream_url":["some.mp3"],"loop":1} info: response ended: 400

Add pagination to nexmo.getNumbers

Currently this doesn't support pagination but the API does.

missing "main" in package.json

"main": "lib/nexmo" does the trick

hope someone is still supporting this!

Support for shortcode messages

Hello,

Is there any plan to support nexmo shortcodes in the future ?

Fix broken API by setting content length

Fix 411 content length error in sendRequest() method. See related commit.

Could you "npm publish" the latest version?

Is it possible or you to npm publish so that we can get the newest version?

Right now you have to do var nexmo = require('easynexmo/lib/nexmo'); to require the module, and with the change you already made to package.json you just need to do npm publish.

SMS not being sent

So, I have credits in my nexmo account, I'm trying to send an SMS and with debug mode on, I can see:

sending message from NEXMO to [phone]xxxx with message Nexmo - rollbar winston test
{ host: 'rest.nexmo.com',
  port: 80,
  path: '/sms/json?&api_key=a8xxxxxx&api_secret=85xxxxxx',
  method: 'POST',
  headers:
   { 'Content-Type': 'application/x-www-form-urlencoded',
     accept: 'application/json',
     'Content-Length': 0 } }
response ended

I've confirmed the api key and the api secret, but any SMS is being sent. Suggestions?

Update USER-AGENT header format to LIBRARY-NAME/LIBRARY-VERSION LANGUAGE-NAME/LANGUAGE-VERSION

LIBRARY-NAME/LIBRARY-VERSION LANGUAGE-NAME/LANGUAGE-VERSION

As per https://github.com/Nexmo/client-library-specification/blob/master/SPECIFICATION.md#reporting

MUST set a user-agent with the following format: LIBRARY-NAME/LIBRARY-VERSION LANGUAGE-NAME/LANGUAGE-VERSION
Example: nexmo-php/1.0.0 php/7.0.8

In addition, appendToUserAgent should be appended to the string so the format will be:

LIBRARY-NAME/LIBRARY-VERSION LANGUAGE-NAME/LANGUAGE-VERSION APPENDED_VALUE

As an example usage:

nexmo-node/1.0.0 node/6.0.0 nexmo-cli/0.3.0

debugon

There is a bug in file lib/nexmo.js, line 72. When debugon is undefined, it can't be stringified

Is there a reason that you do not expose the module via module.exports?

Since most of the libraries use module.exports so that we could easily import via a simple require, I don't know if there are particular reasons that you don't do that. Consequently, I have to import it by specifying the absolute path, such as:

var nexmo = require('../node_modules/easynexmo/lib/nexmo');

This is not very convenient since I have to change this each time I move the module that use nexmo.

Thanks

Missing parameters (from, to and message)

Guys this plugin have a problem:

debug:
sending message from Chamariz to 5513996276077 with message Isso é apenas um teste de envio utilizando o nexmo
{ host: 'rest.nexmo.com',
port: 80,
path: '/sms/json?username=25ce83a5&password=f01b420c&',
method: 'POST',
headers:
{ 'Content-Type': 'application/x-www-form-urlencoded',
accept: 'application/json' } }

callback not work too.

I think not passing from, to and message parameters to path....

Why singleton?

How to deal with two nexmo accounts or several instances for different purposes?
Is it solution by design or am I missing something?

Why not just:

const myNexmo1 = new Nexmo(key1, secret1);
const myNexmo2 = new Nexmo(key2, secret2); 

Improve error format consistency

Currently errors come in either as:

• The error object in a callback, with a message attributes
• The error object in a callback, with a error-code and error-code-label attribute
• The response object in a callback, with a status attribute with a value of 0

This is causing a lot of headache when used (see Nexmo/nexmo-cli#104).

I propose we instead return an error object and only an error object if an error occurred, and a response object and only a response object if no errors occurred. This would also bring the library more in line with how Promises work down the line if we want to go that way.

shortcodeAlert: confusing parameters (messageParams and opts)

Hi,
what is messageParams?

Thanks

ReferenceError: Nexmo is not defined

Hi,
It is impossible to instantiate Nexmo. I always an error : ReferenceError: Nexmo is not defined, trigerred on /node_modules/nexmo/lib/Nexmo.js:76:15. Of course, I did npm install nexmo before...
Can you please help on that?
Thanks a lot,

Better way to catch authentication errors?

Is there a better way to catch authentication errors? At the moment if I run nexmo.initialize(...) with incorrect credentials the callback for a method does NOT return an error object. Instead the response object looks as follows:

{ 'error-code': '401',
  'error-code-label': 'authentication failed' }

There's a few things that would be useful here.

1. Catch authentication errors and actually return an error object instead of a response in an API call.
2. Provide a way to validate nexmo.initialize(...) without making an API call

getPricing for outbound voice calls

Would you implement this call in the library ?

https://docs.nexmo.com/api-ref/developer-api/account-pricing

Throughput Rate Exceeded error

Hi.
All our accounts are set with 30 SMS per second cap. Except US and Canada with long virtual numbers limited to 1 SMS per second. Or we'll see:

Throughput Rate Exceeded - please wait [ 978 ] and retry

About it: https://help.nexmo.com/hc/en-us/articles/203993598-What-is-the-Throughput-Limit-for-Outbound-SMS-
Please, add support of queue for sending sms.

Thank you.

sendTextMessage is not working

I am implementing this in my hapi application. sendMessage is working fine, but sendTextMessage is not working.
var nexmo = require('easynexmo');
nexmo.initialize('KEY', 'SECRET');
function consolelog (err,messageResponse) {
if (err) {
console.log(err);
} else {
console.log(messageResponse);
}
}
nexmo.sendTextMessage(XXXXXXXXXXX,YYYYYYYYYY,'Test Meessage',consolelog); // This is not working

nexmo.sendMessage({from:XXXXXXXXXXX,to: YYYYYYYYYY, text:'Test Message'}, consolelog); // This is working fine

.

wrong issue reported by me. want to remove but unable to do this