SMS

Provider

NotifyBC depends on underlying SMS service providers to deliver SMS messages. The supported service providers are

• Twilio (default)
• Swift

Only one service provider can be chosen per installation. To change service provider, add following config to file /src/config.local.js

module.exports = {
  sms: {
    provider: 'swift',
  },
};

Provider Settings

Provider specific settings are defined in config sms.providerSettings. You should have an account with the chosen service provider before proceeding.

Twilio

Add sms.providerSettings.twilio config object to file /src/config.local.js

module.exports = {
  sms: {
    providerSettings: {
      twilio: {
        accountSid: '<AccountSid>',
        authToken: '<AuthToken>',
        fromNumber: '<FromNumber>',
      },
    },
  },
};

Obtain <AccountSid>, <AuthToken> and <FromNumber> from your Twilio account.

Swift

Add sms.providerSettings.swift config object to file /src/config.local.js

module.exports = {
  sms: {
    providerSettings: {
      swift: {
        accountKey: '<accountKey>',
      },
    },
  },
};

Obtain <accountKey> from your Swift account.

Unsubscription by replying a keyword

With Swift short code, sms user can unsubscribe by replying to a sms message with a keyword. The keyword must be pre-registered with Swift.

To enable this feature,

1. Generate a random string, hereafter referred to as <randomly-generated-string>

2. Add it to sms.providerSettings.swift.notifyBCSwiftKey in file /src/config.local.js

   module.exports = {
     sms: {
       providerSettings: {
         swift: {
           notifyBCSwiftKey: '<randomly-generated-string>',
         },
       },
     },
   };
   

3. Go to Swift web admin console, click Number Management tab

4. Click Launch button next to Manage Short Code Keywords

5. Click Features button next to the registered keyword(s). A keyword may have multiple entries. In such case do this for each entry.

6. Click Redirect To Webpage tab in the popup window

7. Enter following information in the tab

   • set URL to <NotifyBCHttpHost>/api/subscriptions/swift, where <NotifyBCHttpHost> is NotifyBC HTTP host name and should be the same as HTTP Host config
   • set Method to POST
   • set Custom Parameter 1 Name to notifyBCSwiftKey
   • set Custom Parameter 1 Value to <randomly-generated-string>

8. Click Save Changes button and then Done

Throttle

All supported SMS service providers impose request rate limit. NotifyBC by default throttles request rate to 4/sec. To adjust the rate, create following config in file /src/config.local.js

module.exports = {
  sms: {
    throttle: {
      // minimum request interval in ms
      minTime: 250,
    },
  },
};

When NotifyBC is deployed from source code, by default the rate limit applies to one Node.js process only. If there are multiple processes, i.e. a cluster, the aggregated rate limit is multiplied by the number of processes. To enforce the rate limit across entire cluster, install Redis and add Redis config to sms.throttle

module.exports = {
  sms: {
    throttle: {
      /* Redis clustering options */
      datastore: 'ioredis',
      clientOptions: {
        host: '127.0.0.1',
        port: 6379,
      },
    },
  },
};

If you installed Redis Sentinel,

module.exports = {
  sms: {
    throttle: {
      /* Redis clustering options */
      datastore: 'ioredis',
      clientOptions: {
        name: 'mymaster',
        sentinels: [{ host: '127.0.0.1', port: 26379 }],
      },
    },
  },
};

Throttle is implemented using Bottleneck and ioredis. See their documentations for more configurations. The only deviation made by NotifyBC is using jobExpiration to denote Bottleneck expiration job option with a default value of 2min as defined in config.ts.

When NotifyBC is deployed to Kubernetes using Helm, by default throttle, if enabled, uses Redis Sentinel therefore rate limit applies to whole cluster.

To disable throttle, set sms.throttle.enabled to false in file /src/config.local.js

module.exports = {
  sms: {
    throttle: {
      enabled: false,
    },
  },
};