whoosh-node

Supported Node.js Versions

This library supports the following Node.js implementations:

• Node.js 14
• Node.js 16
• Node.js 18

TypeScript is supported for TypeScript version 2.9 and above.

Warning Do not use this Node.js library in a front-end application. Doing so can expose your Whoosh credentials to end-users as part of the bundled HTML/JavaScript sent to their browser.

Installation

npm install whoosh-sms or yarn add whoosh-sms

Test your installation

To make sure the installation was successful, try sending yourself an SMS message, like this:

// Your AccountSID and Auth Token from console.whoosh.totogidemos.com
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';

const client = require('whoosh-sms')(accountSid, authToken);

client.messages
  .create({
    body: 'Hello from whoosh-node',
    to: '+12345678901', // Text your number
    from: '+12345678901', // From a valid Whoosh number
  })
  .then((message) => console.log(message.sid));

After a brief delay, you will receive the text message on your phone.

Warning It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out How to Set Environment Variables for more information.

Usage

Check out these code examples in JavaScript and TypeScript to get up and running quickly.

Environment Variables

whoosh-node supports credential storage in environment variables. If no credentials are provided when instantiating the Twilio client (e.g., const client = require('whoosh-sms')();), the values in following env vars will be used: TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN.

If your environment requires SSL decryption, you can set the path to CA bundle in the env var TWILIO_CA_BUNDLE.

Client Initialization

If you invoke any V2010 operations without specifying an account SID, whoosh-node will automatically use the TWILIO_ACCOUNT_SID value that the client was initialized with. This is useful for when you'd like to, for example, fetch resources for your main account but also your subaccount. See below:

// Your Account SID, Subaccount SID Auth Token from console.whoosh.totogidemos.com
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const subaccountSid = process.env.TWILIO_ACCOUNT_SUBACCOUNT_SID;

const client = require('whoosh-sms')(accountSid, authToken);

Lazy Loading

whoosh-node supports lazy loading required modules for faster loading time. Lazy loading is enabled by default. To disable lazy loading, simply instantiate the Whoosh client with the lazyLoading flag set to false:

// Your Account SID and Auth Token from console.whoosh.totogidemos.com
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;

const client = require('whoosh-sms')(accountSid, authToken, {
  lazyLoading: false,
});

Enable Auto-Retry with Exponential Backoff

whoosh-node supports automatic retry with exponential backoff when API requests receive an error. This retry with exponential backoff feature is disabled by default. To enable this feature, instantiate the Whoosh client with the autoRetry flag set to true.

Optionally, the maximum number of retries performed by this feature can be set with the maxRetries flag. The default maximum number of retries is 3.

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;

const client = require('whoosh-sms')(accountSid, authToken, {
  autoRetry: true,
  maxRetries: 3,
});