Vonage SMS

Vonage SMS SDK for Node.js

GitHub Workflow Status Latest Release

This is the Vonage SMS SDK for Node.js for use with 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.nexmo.com.

If you are updating from V2 to V3, please check the migration guide found here

Installation
Usage
Promises
Testing

Installation

We recommend using this SDK as part of the overall @vonage/server-sdk package. Please see the main package for installation.

You can also use this SDK standalone if you only need access to just the SMS API.

With NPM

npm install @vonage/sms

With Yarn

yarn add @vonage/sms

Usage

As part of the Vonage Server SDK

If you are using this SDK as part of the Vonage Server SDK, you can access it as the sms property off of the client that you instantiate.

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

const credentials = new Auth({
  apiKey: API_KEY,
  apiSecret: API_SECRET
});
const options = {};
const vonage = new Vonage(credentials, options);

vonage.sms.listCountrySMS('sms')
  .then(resp => console.log(resp))
  .catch(err => console.error(err));

Standalone

The SDK can be used standalone from the main Vonage Server SDK for Node.js if you only need to use the SMS API. All you need to do is require('@vonage/sms'), and use the returned object to create your own client.

const { Auth } = require('@vonage/auth');
const { SMS } = require('@vonage/sms');

const credentials = new Auth({
  apiKey: API_KEY,
  apiSecret: API_SECRET
});
const options = {};

const smsClient = new SMS(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.basicLookup(PHONE_NUMBER)

vonage.sms.getAvailableSMS()
  .then(resp => console.log(resp))
  .catch(err => console.error(err));

Testing

Run:

npm run test

Enumerations

MessageClassEnum

Defined in: packages/sms/lib/enums/MessageClassEnum.ts:6

Enumeration representing the possible message classes.

Defines different message classes that can be associated with SMS messages.

Enumeration Members

Enumeration Member	Value	Description	Defined in
`NUMBER_0`	`0`	Class 0: Flash SMS.	packages/sms/lib/enums/MessageClassEnum.ts:10
`NUMBER_1`	`1`	Class 1: Immediate display (user should be able to read the message instantly).	packages/sms/lib/enums/MessageClassEnum.ts:15
`NUMBER_2`	`2`	Class 2: Mobile equipment-to-mobile equipment (ME-to-ME) communication.	packages/sms/lib/enums/MessageClassEnum.ts:20
`NUMBER_3`	`3`	Class 3: SIM card-based storage.	packages/sms/lib/enums/MessageClassEnum.ts:25

SMSStatus

Defined in: packages/sms/lib/enums/SMSStatus.ts:9

Enumeration representing possible SMS status codes.

Defines different status codes that can be associated with SMS messages.

Remarks

This matches SMSErrors. Since Enums can't be joined, this is here to help check valid statuses

Enumeration Members

Enumeration Member	Value	Description	Defined in
`ACCOUNT_NOT_ENABLED`	`"11"`	Account Not Enabled For HTTP: Account is not provisioned for the SMS API.	packages/sms/lib/enums/SMSStatus.ts:68
`BARRED_NUMBER`	`"7"`	Barred Number: The number you're trying to send messages to is blocklisted.	packages/sms/lib/enums/SMSStatus.ts:48
`INTERNAL_ERROR`	`"5"`	Internal Error: An error occurred while processing the message.	packages/sms/lib/enums/SMSStatus.ts:38
`INVALID_CALLBACK_URL`	`"23"`	Invalid Callback URL: Callback URL is too long or contains illegal characters.	packages/sms/lib/enums/SMSStatus.ts:93
`INVALID_CREDENTIALS`	`"4"`	Invalid Credentials: API key and/or secret are incorrect, invalid, or disabled.	packages/sms/lib/enums/SMSStatus.ts:33
`INVALID_MESSAGE`	`"6"`	Invalid Message: The platform was unable to process the message.	packages/sms/lib/enums/SMSStatus.ts:43
`INVALID_NETWORK_CODE`	`"22"`	Invalid Network Code: Network code is unrecognized or doesn't match the destination.	packages/sms/lib/enums/SMSStatus.ts:88
`INVALID_PARAM`	`"3"`	Invalid Parameter: The value of one or more parameters is invalid.	packages/sms/lib/enums/SMSStatus.ts:28
`INVALID_SENDER_ADDRESS`	`"15"`	Invalid Sender Address: Using a non-authorized sender ID in the 'from' field.	packages/sms/lib/enums/SMSStatus.ts:83
`INVALID_SIGNATURE`	`"14"`	Invalid Signature: The supplied signature could not be verified.	packages/sms/lib/enums/SMSStatus.ts:78
`MESSAGE_TOO_LONG`	`"12"`	Message Too Long: Message length exceeds the maximum allowed.	packages/sms/lib/enums/SMSStatus.ts:73
`MISSING_REQUIRED_PARAM`	`"2"`	Missing Required Parameter: One or more required parameters are missing.	packages/sms/lib/enums/SMSStatus.ts:23
`NON_WHITELISTED_DESTINATION`	`"29"`	Non-Whitelisted Destination: Vonage account is in demo mode and requires whitelisted numbers. This error is returned if you attempt to send a message to a number that isn't in your pre-approved destination list.	packages/sms/lib/enums/SMSStatus.ts:100
`NUMBER_DEACTIVATED`	`"33"`	Number Deactivated: The number you're trying to send messages to is deactivated.	packages/sms/lib/enums/SMSStatus.ts:110
`PARTNER_ACCOUNT_BARRED`	`"8"`	Partner Account Barred: Your Vonage account has been suspended.	packages/sms/lib/enums/SMSStatus.ts:53
`PARTNER_QUOTA_VIOLATION`	`"9"`	Partner Quota Violation: Insufficient credit to send the message.	packages/sms/lib/enums/SMSStatus.ts:58
`SIGNATURE_AND_API_SECRET_DISALLOWED`	`"32"`	Signature And API Secret Disallowed: A signed request may not present an API secret.	packages/sms/lib/enums/SMSStatus.ts:105
`SUCCESS`	`"0"`	Success: The message was sent successfully.	packages/sms/lib/enums/SMSStatus.ts:13
`THROTTLED`	`"1"`	Throttled: Sending SMS faster than the account limit.	packages/sms/lib/enums/SMSStatus.ts:18
`TOO_MANY_EXISTING_BINDS`	`"10"`	Too Many Existing Binds: Number of simultaneous connections exceeds account allocation.	packages/sms/lib/enums/SMSStatus.ts:63

TypeEnum

Defined in: packages/sms/lib/enums/TypeEnum.ts:6

Enumeration representing possible message types for SMS.

Defines different message types that can be associated with SMS messages.

Enumeration Members

Enumeration Member	Value	Description	Defined in
`BINARY`	`"binary"`	Binary: The message body is in binary format.	packages/sms/lib/enums/TypeEnum.ts:15
`TEXT`	`"text"`	Text: The message body contains standard text.	packages/sms/lib/enums/TypeEnum.ts:10
`UNICODE`	`"unicode"`	Unicode: The message body is URL-encoded Unicode, valid for various character sets.	packages/sms/lib/enums/TypeEnum.ts:20

Classes

MessageSendAllFailure

Defined in: packages/sms/lib/classes/Error/MessageSendAllFailure.ts:9

Class representing a failure when sending all SMS messages.

Extends the SMSFailure class and is used to indicate that all SMS messages failed to send.

Extends

SMSFailure

Constructors

Constructor

new MessageSendAllFailure(response): MessageSendAllFailure;

Defined in: packages/sms/lib/classes/Error/MessageSendAllFailure.ts:15

Creates an instance of MessageSendAllFailure.

Parameters

response

SMSMessages

The response containing details about the failed SMS messages.

Returns

MessageSendAllFailure

Overrides

SMSFailure.constructor

Properties

cause?

optional cause: unknown;

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from

SMSFailure.cause

message

message: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

SMSFailure.message

name

name: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

SMSFailure.name

response

protected response: SMSMessages;

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:14

The response containing details about the SMS messages.

Inherited from

SMSFailure.response

stack?

optional stack: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

SMSFailure.stack

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Defined in: node_modules/@types/node/globals.d.ts:143

Optional override for formatting stack traces

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

SMSFailure.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:145

Inherited from

SMSFailure.stackTraceLimit

Methods

getFailedMessages()

getFailedMessages(): ErrorMessage[];

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:41

Retrieves an array of failed messages in the response.

Returns

ErrorMessage[]

An array of failed messages in the response.

Inherited from

SMSFailure.getFailedMessages

getMessages()

getMessages(): ErrorMessage & SMSMessageResponse & object[];

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:32

Retrieves an array of all messages in the response.

Returns

An array of all messages in the response.

Inherited from

SMSFailure.getMessages

getResponse()

getResponse(): SMSMessages;

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:52

Retrieves the original response containing details about the SMS messages.

Returns

SMSMessages

The original response containing details about the SMS messages.

Inherited from

SMSFailure.getResponse

getSuccessfulMessages()

getSuccessfulMessages(): Message[];

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:61

Retrieves an array of successfully sent messages in the response.

Returns

Message[]

An array of successfully sent messages in the response.

Inherited from

SMSFailure.getSuccessfulMessages

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:136

Create .stack property on a target object

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

SMSFailure.captureStackTrace

MessageSendPartialFailure

Defined in: packages/sms/lib/classes/Error/MessageSendPartialFailure.ts:9

Class representing a partial failure when sending SMS messages.

Extends the SMSFailure class and is used to indicate that some SMS messages failed to send.

Extends

SMSFailure

Constructors

Constructor

new MessageSendPartialFailure(response): MessageSendPartialFailure;

Defined in: packages/sms/lib/classes/Error/MessageSendPartialFailure.ts:15

Creates an instance of MessageSendPartialFailure.

Parameters

response

SMSMessages

The response containing details about the partially failed SMS messages.

Returns

MessageSendPartialFailure

Overrides

SMSFailure.constructor

Properties

cause?

optional cause: unknown;

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from

SMSFailure.cause

message

message: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

SMSFailure.message

name

name: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

SMSFailure.name

response

protected response: SMSMessages;

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:14

The response containing details about the SMS messages.

Inherited from

SMSFailure.response

stack?

optional stack: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

SMSFailure.stack

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Defined in: node_modules/@types/node/globals.d.ts:143

Optional override for formatting stack traces

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

SMSFailure.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:145

Inherited from

SMSFailure.stackTraceLimit

Methods

getFailedMessages()

getFailedMessages(): ErrorMessage[];

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:41

Retrieves an array of failed messages in the response.

Returns

ErrorMessage[]

An array of failed messages in the response.

Inherited from

SMSFailure.getFailedMessages

getMessages()

getMessages(): ErrorMessage & SMSMessageResponse & object[];

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:32

Retrieves an array of all messages in the response.

Returns

An array of all messages in the response.

Inherited from

SMSFailure.getMessages

getResponse()

getResponse(): SMSMessages;

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:52

Retrieves the original response containing details about the SMS messages.

Returns

SMSMessages

The original response containing details about the SMS messages.

Inherited from

SMSFailure.getResponse

getSuccessfulMessages()

getSuccessfulMessages(): Message[];

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:61

Retrieves an array of successfully sent messages in the response.

Returns

Message[]

An array of successfully sent messages in the response.

Inherited from

SMSFailure.getSuccessfulMessages

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:136

Create .stack property on a target object

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

SMSFailure.captureStackTrace

SMS

Defined in: packages/sms/lib/sms.ts:47

Client for sending legacy SMS messages using the Vonage API.

Examples

Create a standalone SMS client

import { AlgorithmTypes } from '@vonage/auth';
import { SMS } from '@vonage/sms';

const smsClient = new SMS({
 apiKey: VONAGE_API_KEY,
 apiSecret: VONAGE_API_SECRET
 secret: {
   secret: VONAGE_SIGNATURE_SECRET
   algorithm: AlgorithmTypes.sha512hmac
 },
});

Create an SMS client from the Vonage client

import { AlgorithmTypes } from '@vonage/auth';
import { Vonage } from '@vonage/server-client';

const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET
  secret: {
    secret: VONAGE_SIGNATURE_SECRET
    algorithm: AlgorithmTypes.sha512hmac
  },
});

const smsClient = vonage.sms;

Extends

Client

Constructors

Constructor

new SMS(credentials, options?): SMS;

Defined in: packages/server-client/dist/lib/client.d.ts:35

Creates a new instance of the Client.

Parameters

credentials

The authentication credentials or an authentication instance.

AuthInterface | AuthParams

options?

ConfigParams

Optional configuration settings for the client.

Returns

SMS

Inherited from

Client.constructor

Properties

auth

protected auth: AuthInterface;

Defined in: packages/server-client/dist/lib/client.d.ts:24

The authentication instance responsible for generating authentication headers and query parameters.

Inherited from

Client.auth

authType?

protected optional authType: AuthenticationType = AuthenticationType.BASIC;

Defined in: packages/sms/lib/sms.ts:51

See

Client.authType

Overrides

Client.authType

config

protected config: ConfigParams;

Defined in: packages/server-client/dist/lib/client.d.ts:28

Configuration settings for the client, including default hosts for various services and other request settings.

Inherited from

Client.config

transformers

static transformers: object;

Defined in: packages/server-client/dist/lib/client.d.ts:11

Static property containing utility transformers.

camelCaseObjectKeys

camelCaseObjectKeys: PartialTransformFunction;

kebabCaseObjectKeys

kebabCaseObjectKeys: PartialTransformFunction;

omit()

omit: (keys, obj) => TransformedObject;

Parameters

keys

string[]

obj

ObjectToTransform

Returns

TransformedObject

snakeCaseObjectKeys

snakeCaseObjectKeys: PartialTransformFunction;

Inherited from

Client.transformers

Methods

addAuthenticationToRequest()

addAuthenticationToRequest(request): Promise<VetchOptions>;

Defined in: packages/server-client/dist/lib/client.d.ts:43

Adds the appropriate authentication headers or parameters to the request based on the authentication type.

Parameters

request

VetchOptions

The request options to which authentication needs to be added.

Returns

Promise<VetchOptions>

The request options with the added authentication.

Inherited from

Client.addAuthenticationToRequest

addBasicAuthToRequest()

protected addBasicAuthToRequest(request): Promise<VetchOptions>;

Defined in: packages/server-client/dist/lib/client.d.ts:71

Adds basic authentication headers to the request.

Parameters

request

VetchOptions

The request options to which authentication needs to be added.

Returns

Promise<VetchOptions>

The request options with the added authentication.

Inherited from

Client.addBasicAuthToRequest

addJWTToRequest()

protected addJWTToRequest(request): Promise<VetchOptions>;

Defined in: packages/server-client/dist/lib/client.d.ts:64

Adds a JWT to the request.

Parameters

request

VetchOptions

The request options to which authentication needs to be added.

Returns

Promise<VetchOptions>

The request options with the added authentication.

Inherited from

Client.addJWTToRequest

addQueryKeySecretToRequest()

protected addQueryKeySecretToRequest(request): Promise<VetchOptions>;

Defined in: packages/server-client/dist/lib/client.d.ts:57

Adds API key and secret to the request.

Parameters

request

VetchOptions

The request options to which authentication needs to be added.

Returns

Promise<VetchOptions>

The request options with the added authentication.

Inherited from

Client.addQueryKeySecretToRequest

addQueryKeySecretToRequestBody()

protected addQueryKeySecretToRequestBody(request): Promise<VetchOptions>;

Defined in: packages/server-client/dist/lib/client.d.ts:50

Adds API key and secret to the request body.

Parameters

request

VetchOptions

The request options to which authentication needs to be added.

Returns

Promise<VetchOptions>

The request options with the added authentication.

Inherited from

Client.addQueryKeySecretToRequestBody

getConfig()

getConfig(): ConfigParams;

Defined in: packages/server-client/dist/lib/client.d.ts:36

Returns

ConfigParams

Inherited from

Client.getConfig

parseResponse()

protected parseResponse<T>(request, response): Promise<VetchResponse<T>>;

Defined in: packages/server-client/dist/lib/client.d.ts:168

Parses the response based on its content type.

Type Parameters

T

T

The expected type of the parsed response data.

Parameters

request

VetchOptions

The request options.

response

Response

The raw response from the request.

Returns

Promise<VetchResponse<T>>

The parsed response.

Inherited from

Client.parseResponse

prepareBody()

protected prepareBody(request): undefined | string;

Defined in: packages/server-client/dist/lib/client.d.ts:158

Prepares the body for the request based on the content type.

Parameters

request

VetchOptions

The request options.

Returns

undefined | string

The prepared request body as a string or undefined.

Inherited from

Client.prepareBody

prepareRequest()

protected prepareRequest(request): Promise<VetchOptions>;

Defined in: packages/server-client/dist/lib/client.d.ts:151

Prepares the request with necessary headers, authentication, and query parameters.

Parameters

request

VetchOptions

The initial request options.

Returns

Promise<VetchOptions>

The modified request options.

Inherited from

Client.prepareRequest

send()

send(params?): Promise<SMSMessages>;

Defined in: packages/sms/lib/sms.ts:71

Sends an SMS message using the legacy Vonage SMS API.

Parameters

params?

SMSParams

The parameters for the SMS message.

Returns

Promise<SMSMessages>

A Promise that resolves to the response containing details about the sent SMS messages.

Throws

If all SMS messages fail to send.

Throws

If some SMS messages fail to send.

Example

const response = await smsClient.send({
  to: TO_NUMBER,
  from: FROM_NUMBER,
  text: 'Hello from Vonage SMS API',
});
console.log(`Number of messages sent: ${response.messageCount}`););

sendDeleteRequest()

sendDeleteRequest<T>(url): Promise<VetchResponse<T>>;

Defined in: packages/server-client/dist/lib/client.d.ts:78

Sends a DELETE request to the specified URL.

Type Parameters

T

T

Parameters

url

string

The URL endpoint for the DELETE request.

Returns

Promise<VetchResponse<T>>

The response from the DELETE request.

Inherited from

Client.sendDeleteRequest

sendFormSubmitRequest()

sendFormSubmitRequest<T>(url, payload?): Promise<VetchResponse<T>>;

Defined in: packages/server-client/dist/lib/client.d.ts:86

Sends a POST request with form data to the specified URL.

Type Parameters

T

T

Parameters

url

string

The URL endpoint for the POST request.

payload?

Record<string, undefined | string>

Optional payload containing form data to send with the POST request.

Returns

Promise<VetchResponse<T>>

The response from the POST request.

Inherited from

Client.sendFormSubmitRequest

sendGetRequest()

sendGetRequest<T>(url, queryParams?): Promise<VetchResponse<T>>;

Defined in: packages/server-client/dist/lib/client.d.ts:94

Sends a GET request to the specified URL with optional query parameters.

Type Parameters

T

T

Parameters

url

string

The URL endpoint for the GET request.

queryParams?

Optional query parameters to append to the URL. These should be compatible with Node's URLSearchParams.

Returns

Promise<VetchResponse<T>>

The response from the GET request.

Inherited from

Client.sendGetRequest

sendPatchRequest()

sendPatchRequest<T>(url, payload?): Promise<VetchResponse<T>>;

Defined in: packages/server-client/dist/lib/client.d.ts:104

Sends a PATCH request to the specified URL with an optional payload.

Type Parameters

T

T

Parameters

url

string

The URL endpoint for the PATCH request.

payload?

Optional payload to be sent as the body of the PATCH request.

Returns

Promise<VetchResponse<T>>

The response from the PATCH request.

Inherited from

Client.sendPatchRequest

sendPostRequest()

sendPostRequest<T>(url, payload?): Promise<VetchResponse<T>>;

Defined in: packages/server-client/dist/lib/client.d.ts:114

Sends a POST request to the specified URL with an optional payload.

Type Parameters

T

T

Parameters

url

string

The URL endpoint for the POST request.

payload?

Optional payload to be sent as the body of the POST request.

Returns

Promise<VetchResponse<T>>

The response from the POST request.

Inherited from

Client.sendPostRequest

sendPutRequest()

sendPutRequest<T>(url, payload?): Promise<VetchResponse<T>>;

Defined in: packages/server-client/dist/lib/client.d.ts:124

Sends a PUT request to the specified URL with an optional payload.

Type Parameters

T

T

Parameters

url

string

The URL endpoint for the PUT request.

payload?

Optional payload to be sent as the body of the PUT request.

Returns

Promise<VetchResponse<T>>

The response from the PUT request.

Inherited from

Client.sendPutRequest

sendRequest()

sendRequest<T>(request): Promise<VetchResponse<T>>;

Defined in: packages/server-client/dist/lib/client.d.ts:144

Sends a request adding necessary headers, handling authentication, and parsing the response.

Type Parameters

T

T

Parameters

request

VetchOptions

The options defining the request, including URL, method, headers, and data.

Returns

Promise<VetchResponse<T>>

The parsed response from the request.

Inherited from

Client.sendRequest

sendRequestWithData()

sendRequestWithData<T>(
   method, 
   url, 
payload?): Promise<VetchResponse<T>>;

Defined in: packages/server-client/dist/lib/client.d.ts:135

Sends a request with JSON-encoded data to the specified URL using the provided HTTP method.

Type Parameters

T

T

Parameters

method

The HTTP method to be used for the request (only POST, PATCH, or PUT are acceptable).

POST | PUT | PATCH

url

string

The URL endpoint for the request.

payload?

Optional payload to be sent as the body of the request, JSON-encoded.

Returns

Promise<VetchResponse<T>>

The response from the request.

Inherited from

Client.sendRequestWithData

verifySignature()

verifySignature(
   signature, 
   params, 
   signatureSecret, 
   algorithm): boolean;

Defined in: packages/sms/lib/sms.ts:132

Verifies the signature of a request using the specified algorithm and signature secret.

Parameters

signature

string

The signature to be verified.

params

Record<string, string>

The request parameters used to generate the signature.

signatureSecret

string

The secret key used for generating the signature.

algorithm

AlgorithmTypes

The algorithm used for generating the signature.

Returns

boolean

true if the signature is valid, false otherwise.

Remarks

This will not parse the request parameters from the request object, so you will need to do that yourself.

Throws

If the provided signature algorithm is not supported.

Example

const params = Object.assign(request.query, request.body);
const { sig } = params;

sms.verifySignature(
  sig,
  {}, // request parameters
  VONAGE_API_SIGNATURE_SECRET,
  AlgorithmTypes.md5hash,
) === params.sig) {
  console.log("Valid signature");
} else {
  console.log("Invalid signature");
}

SMSFailure

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:10

Class representing a failure response when sending SMS messages.

Extends the built-in Error class and provides methods for accessing and handling failed SMS messages.

Extends

Error

Constructors

Constructor

new SMSFailure(message, response): SMSFailure;

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:22

Creates an instance of SMSFailure.

Parameters

message

string

The error message.

response

SMSMessages

The response containing details about the SMS messages.

Returns

SMSFailure

Overrides

Error.constructor

Properties

cause?

optional cause: unknown;

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from

Error.cause

message

message: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

Error.message

name

name: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.name

response

protected response: SMSMessages;

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:14

The response containing details about the SMS messages.

stack?

optional stack: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

Error.stack

prepareStackTrace()?

static optional prepareStackTrace: (err, stackTraces) => any;

Defined in: node_modules/@types/node/globals.d.ts:143

Optional override for formatting stack traces

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:145

Inherited from

Error.stackTraceLimit

Methods

getFailedMessages()

getFailedMessages(): ErrorMessage[];

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:41

Retrieves an array of failed messages in the response.

Returns

ErrorMessage[]

An array of failed messages in the response.

getMessages()

getMessages(): ErrorMessage & SMSMessageResponse & object[];

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:32

Retrieves an array of all messages in the response.

Returns

An array of all messages in the response.

getResponse()

getResponse(): SMSMessages;

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:52

Retrieves the original response containing details about the SMS messages.

Returns

SMSMessages

The original response containing details about the SMS messages.

getSuccessfulMessages()

getSuccessfulMessages(): Message[];

Defined in: packages/sms/lib/classes/Error/SMSFailure.ts:61

Retrieves an array of successfully sent messages in the response.

Returns

Message[]

An array of successfully sent messages in the response.

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:136

Create .stack property on a target object

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

Type Aliases

DeliveryReceipt

type DeliveryReceipt = object;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:6

Interface representing a delivery receipt for an SMS message.

Describes the structure of a delivery receipt containing information about the message's delivery status.

Properties

apiKey?

optional apiKey: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:50

The API key that sent the SMS (optional).

clientRef?

optional clientRef: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:55

Your client reference for the message (optional).

errCode?

optional errCode: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:45

The status of the request (optional).

messageId?

optional messageId: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:25

The Vonage ID for this message (optional).

messageTimestamp?

optional messageTimestamp: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:60

The time when Vonage started to push this Delivery Receipt to your webhook endpoint (optional).

msisdn?

optional msisdn: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:10

The recipient's phone number in E.164 format (optional).

networkCode?

optional networkCode: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:20

The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier (optional).

nonce?

optional nonce: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:70

A random string forming part of the signed set of parameters for validation (optional).

price?

optional price: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:30

The cost of the message (optional).

scts?

optional scts: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:40

When the Delivery Receipt was received from the carrier in YYMMDDHHMM format (optional).

sig?

optional sig: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:75

The hash of the request parameters, a timestamp, and the signature secret (optional).

status?

optional status: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:35

A code explaining the message's delivery status (optional).

timestamp?

optional timestamp: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:65

A Unix timestamp representation of 'messageTimestamp' (optional).

to?

optional to: string;

Defined in: packages/sms/lib/types/Responses/DeliveryReceipt.ts:15

The SenderID set in the 'from' field of the request (optional).

ErrorMessage

type ErrorMessage = object;

Defined in: packages/sms/lib/types/ErrorMessage.ts:6

Interface representing an error message.

Describes the structure of an error message containing status and error text.

Properties

errorText?

optional errorText: string;

Defined in: packages/sms/lib/types/ErrorMessage.ts:15

The error text providing details about the error (optional).

status?

optional status: string;

Defined in: packages/sms/lib/types/ErrorMessage.ts:10

The status code indicating the error (optional).

InboundMessage

type InboundMessage = object;

Defined in: packages/sms/lib/types/InboundMessage.ts:8

Interface representing an inbound SMS message.

Describes the structure of an inbound SMS message, including its properties and details.

Properties

api-key

api-key: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:12

The Vonage API Key of the receiving account.

concat

concat: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:62

Indicates whether this is a concatenated message.

concat-part

concat-part: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:77

The number of this part in the concatenated message.

concat-ref

concat-ref: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:67

The transaction reference for concatenated messages.

concat-total

concat-total: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:72

The total number of parts in this concatenated message.

data

data: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:82

The content of this message, if the type is binary.

keyword

keyword: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:42

The first word in the message body, converted to uppercase.

message-timestamp

message-timestamp: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:47

The time when Vonage started to push this Inbound SMS to your webhook endpoint.

messageId

messageId: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:27

The unique ID of the inbound message.

msisdn

msisdn: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:17

The phone number that this inbound message was sent from in E.164 format.

nonce

nonce: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:57

A random string that forms part of the signed set of parameters for validation.

text

text: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:32

The message body for this inbound message.

timestamp

timestamp: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:52

A Unix timestamp representation of 'message-timestamp'.

to

to: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:22

The phone number the message was sent to (virtual number) in E.164 format.

type

type: TypeEnum | string;

Defined in: packages/sms/lib/types/InboundMessage.ts:37

The format of the message body.

udh

udh: string;

Defined in: packages/sms/lib/types/InboundMessage.ts:87

The hex encoded User Data Header, if the type is binary.

Message

type Message = SMSMessageResponse & object;

Defined in: packages/sms/lib/types/Message.ts:8

Type representing an SMS message.

Extends the structure of an SMS message response and includes additional optional properties.

Type declaration

accountRef?

optional accountRef: string;

An optional string used to identify separate accounts using the SMS endpoint for billing purposes (optional).

clientRef?

optional clientRef: string;

Your client reference for the message (optional).

messageId?

optional messageId: string;

The unique ID of the SMS message (optional).

messagePrice?

optional messagePrice: string;

The estimated cost of the SMS message (optional).

remainingBalance?

optional remainingBalance: string;

Your estimated remaining balance after sending the SMS (optional).

SendSMSResponse

type SendSMSResponse = SMSResponse;

Defined in: packages/sms/lib/types/Responses/SendSMSResponse.ts:10

Deprecated type alias for SMSResponse.

Please use SMSResponse instead.

Deprecated

Use SMSResponse instead.

SMSEmptyResponse

type SMSEmptyResponse = object;

Defined in: packages/sms/lib/types/Responses/SMSEmptyResponse.ts:6

Deprecated interface for an empty SMS response.

Deprecated

There is no substitution for this interface.

Properties

errorCode?

optional errorCode: string;

Defined in: packages/sms/lib/types/Responses/SMSEmptyResponse.ts:10

The error code, if applicable (optional).

errorCodeLabel?

optional errorCodeLabel: string;

Defined in: packages/sms/lib/types/Responses/SMSEmptyResponse.ts:15

A label for the error code, if provided (optional).

SMSGeneralResponse

type SMSGeneralResponse = SMSResponse;

Defined in: packages/sms/lib/types/Responses/SMSGeneralResponse.ts:10

Deprecated type alias for SMSResponse.

Please use SMSResponse instead.

Deprecated

Use SMSResponse instead.

SMSMessageResponse

type SMSMessageResponse = object;

Defined in: packages/sms/lib/types/Responses/SMSMessageResponse.ts:7

Interface representing an SMS message response.

Describes the structure of a response containing information about an SMS message's status and details.

Properties

account-ref?

optional account-ref: string;

Defined in: packages/sms/lib/types/Responses/SMSMessageResponse.ts:46

An optional string used to identify separate accounts using the SMS endpoint for billing purposes (optional).

client-ref?

optional client-ref: string;

Defined in: packages/sms/lib/types/Responses/SMSMessageResponse.ts:41

Your client reference for the message (optional).

message-id

message-id: string;

Defined in: packages/sms/lib/types/Responses/SMSMessageResponse.ts:16

The unique ID of the SMS message.

message-price

message-price: string;

Defined in: packages/sms/lib/types/Responses/SMSMessageResponse.ts:31

The estimated cost of the SMS message.

network

network: string;

Defined in: packages/sms/lib/types/Responses/SMSMessageResponse.ts:36

The estimated ID of the network of the recipient.

remaining-balance

remaining-balance: string;

Defined in: packages/sms/lib/types/Responses/SMSMessageResponse.ts:26

Your estimated remaining balance after sending the SMS.

status

status: SMSStatus;

Defined in: packages/sms/lib/types/Responses/SMSMessageResponse.ts:21

The status of the SMS message.

to

to: string;

Defined in: packages/sms/lib/types/Responses/SMSMessageResponse.ts:11

The recipient's phone number in E.164 format.

SMSMessages

type SMSMessages = SMSResponse & object;

Defined in: packages/sms/lib/types/SMSMessages.ts:13

Interface representing an SMS response containing multiple messages, including errors.

Extends the structure of an SMS response and includes additional properties for message count and an array of messages, which can include both valid messages and error messages.

Type declaration

messageCount

messageCount: number;

The count of messages included in the response.

messages

messages: Message & ErrorMessage[];

An array of messages, which can include both valid messages and error messages.

SMSParams

type SMSParams = object;

Defined in: packages/sms/lib/types/SMSParams.ts:9

Type representing parameters for sending an SMS.

Describes the structure of parameters that can be used when sending an SMS, including sender, recipient, message content, and additional options.

Properties

accountRef?

optional accountRef: string;

Defined in: packages/sms/lib/types/SMSParams.ts:88

An optional string used to identify separate accounts using the SMS endpoint for billing purposes (optional).

body?

optional body: string;

Defined in: packages/sms/lib/types/SMSParams.ts:53

The binary body of the message (optional).

callback?

optional callback: string;

Defined in: packages/sms/lib/types/SMSParams.ts:38

The webhook callback URL for receiving delivery receipts (optional).

clientRef?

optional clientRef: string;

Defined in: packages/sms/lib/types/SMSParams.ts:83

Your client reference for the message (optional).

contentId?

optional contentId: string;

Defined in: packages/sms/lib/types/SMSParams.ts:98

An optional content ID for regulatory requirements (optional).

entityId?

optional entityId: string;

Defined in: packages/sms/lib/types/SMSParams.ts:93

An optional entity ID for regulatory requirements (optional).

from

from: string;

Defined in: packages/sms/lib/types/SMSParams.ts:13

The sender's phone number or name.

messageClass?

optional messageClass: MessageClassEnum;

Defined in: packages/sms/lib/types/SMSParams.ts:43

The message class (optional).

protocolId?

optional protocolId: number;

Defined in: packages/sms/lib/types/SMSParams.ts:63

The protocol identifier for binary messages (optional).

statusReportReq?

optional statusReportReq: boolean;

Defined in: packages/sms/lib/types/SMSParams.ts:33

Indicates if a delivery receipt is requested (optional).

text?

optional text: string;

Defined in: packages/sms/lib/types/SMSParams.ts:23

The text content of the SMS message (optional).

title?

optional title: string;

Defined in: packages/sms/lib/types/SMSParams.ts:68

The title of the message (optional).

to

to: string;

Defined in: packages/sms/lib/types/SMSParams.ts:18

The recipient's phone number in E.164 format.

ttl?

optional ttl: number;

Defined in: packages/sms/lib/types/SMSParams.ts:28

The time-to-live (TTL) duration in milliseconds for delivery attempts (optional).

type?

optional type: TypeEnum;

Defined in: packages/sms/lib/types/SMSParams.ts:48

The format of the message body (optional).

udh?

optional udh: string;

Defined in: packages/sms/lib/types/SMSParams.ts:58

The User Data Header (UDH) for binary messages (optional).

url?

optional url: string;

Defined in: packages/sms/lib/types/SMSParams.ts:73

The URL for WAP Push messages (optional).

validity?

optional validity: string;

Defined in: packages/sms/lib/types/SMSParams.ts:78

The validity period of the message (optional).

SMSRequestBody

type SMSRequestBody = object;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:8

Interface representing the request body for sending an SMS.

Describes the structure of the request body used when sending an SMS message.

Properties

body?

optional body: string;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:28

Hex-encoded binary data (optional).

callback?

callback?: string;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:48

The webhook endpoint for the delivery receipt (optional).

client_ref?

client_ref?: string;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:43

Your own reference for the message (optional).

client-ref?

optional client-ref: string;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:78

Your own reference for the message (optional).

content-id?

optional content-id: string;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:88

A string parameter for regulatory requirements (optional).

entity-id?

optional entity-id: string;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:83

A string parameter for regulatory requirements (optional).

from

from: string;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:18

The Alphanumeric senderID (if supported for the destination) or virtual number (specified in E.164 format) that the SMS is being sent from.

message_class?

message_class?: number;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:53

The Data Coding Scheme value of the message (optional).

message-class?

optional message-class: MessageClassEnum;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:73

The Data Coding Scheme value of the message (optional).

protocol-id?

optional protocol-id: number;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:63

The value of the protocol identifier to use (optional).

status-report-req?

optional status-report-req: boolean;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:68

Boolean indicating if a Delivery Receipt is requested (optional).

text?

optional text: string;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:23

The body of the message being sent (optional).

to

to: string;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:12

The recipient's phone number in E.164 format.

ttl?

ttl?: number;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:38

The duration in milliseconds for delivery attempts (optional).

type?

type?: TypeEnum;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:33

The format of the message body (optional).

udh?

udh?: string;

Defined in: packages/sms/lib/types/Requests/SMSRequestBody.ts:58

Custom Hex-encoded User Data Header (optional).

SMSResponse

type SMSResponse = object;

Defined in: packages/sms/lib/types/Responses/SMSResponse.ts:9

Interface representing an SMS response.

Describes the structure of a response containing information about SMS messages or error messages.

Properties

message-count

message-count: number;

Defined in: packages/sms/lib/types/Responses/SMSResponse.ts:13

The count of messages included in the response.

messages

messages: 
  | SMSMessageResponse[]
  | SMSErrorMessageResponse[];

Defined in: packages/sms/lib/types/Responses/SMSResponse.ts:18

An array of SMS message responses or SMS error message responses.

Variables

COLLECTION_FORMATS

const COLLECTION_FORMATS: object;

Defined in: packages/sms/lib/enums/CollectionFormats.ts:6

Collection Formats for API Parameter Serialization.

Defines various collection formats used for serializing API parameters.

Type declaration

csv

csv: string = ',';

Comma-separated values collection format.

pipes

pipes: string = '|';

Pipe-separated values collection format.

ssv

ssv: string = ' ';

Space-separated values collection format.

tsv

tsv: string = '\t';

Tab-separated values collection format.