Messaging Service

Twilio Functions application used to manage our centralized messaging and automated alert system.

Here are all of the commands it supports:

• subscribe: Add a phone number to a channel used for general announcements and calendar event updates.
• broadcast <Message text>: Sends a message to all numbers subscribed to the announcements and calendar events channel.
• help*, info*, information*: Determine whether your number is enrolled in any active channels.
• status: Determine whether your number is enrolled in any active channels.
• start*, unstop*: Restart a user's subscription to any existing channels.
• cancel*, stop*, unsubscribe*: Stop receiving all messages from this service.

The broadcast command is gated to prevent unauthorized phone numbers from sending broadcast messages. Several commands dispatch an event via a webhook for any additional post-processing by the service owner.

* = Acts as a follow-up message to Twilio's built-in, automatic handling of these regulatory-required keywords. That mean's the messages specified in a Messaging application's Opt-Out Managment portal will be sent first, followed by a more user-specific response from this application.

Get Started

This project requires the Twilio CLI and the Serverless Toolkit to run on your machine. It is also very convenient to use NVM to help you select and manage particular versions of Node.JS and NPM on your machine. Here are the steps to do that:

1. Install NVM, per their directions:

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/<latest version tag>/install.sh | bash 

2. Restart your terminal

3. Install the Twilio CLI for your platform. If you install this with NPM, it is most convenient to install it globally, with the -g switch.

4. Install the Serverless Toolkit using the Twilio CLI, like this:

   twilio plugins:install @twilio-labs/plugin-serverless
   twilio autocomplete zsh  # Optional, to update the autocomplete cache
   twilio autocomplete bash # Either/or, depending on your shell

5. Verify that version 3 of the Serverless Toolkit is installed with: twilio plugins

6. Log into your Twilio account, using the Account SID and Auth Token from the console: twilio login

7. Install the necessary dependencies: npm i

8. Setup up all of the necessary environment variables per the Environment Variables section

9. Run the project with: npm start or twilio serverless:start

   • Note 1: If you get a warning that you do not have a compatible version of NodeJS running on your machine, run: nvm install xx && nvm use xx, where xx is the major version of Node that the toolkit requires.
   • Note 2: Check the required runtime version here.

Run and Debug

This project is already setup for use with Visual Studio Code. Simply open the project with that IDE to get started.

To run your project, select either the Run Local configuration for localhost testing or the Run ngrok configuration to publish your local instance on the WAN for testing with Twilio via an ngrok tunnel. To debug this application, run the application with either of the above configurations, and then run the Attach Debugger profile to attach the VS Code debugger to the running Node instance.

Environment Variables

While most of the configuration is stored inside of the Config.private.js file, more sensitive information is offloaded into environment variables.

Here are all of the environment variables this application expects during development and production. All are required, but Twilio can automatically add in some of them, as indicated by the Added By Twilio Automatically column.

Variable Name	Purpose	Added By Twilio Automatically	Used By
ACCOUNT_SID	Acts like a username to authorize this application to your Twilio account	✅	App
AUTH_TOKEN	Acts like your API key, or account password	✅	App
AUTHORIZED_BROADCAST_PHONE_NUMBERS	A comma-separated list of E.164 formatted phone numbers that are authorized to perform a broadcast command	❌	App
NOTIFY_SERVICE_SID	The ID of the Notify service which will collect phone numbers and send messages	❌	App
SERVICE_NAME	The name of the Twilio Functions service to deploy to	❌	Deployment
TWILIO_API_KEY	Like an ACCOUNT_SID, but created specifically for the purpose of CI deployment, to prevent compromise of the master key	❌	Deployment
TWILIO_API_SECRET	Like an AUTH_TOKEN, but created specifically for the purpose of CI deployment, to prevent compromise of the master key	❌	Deployment
WEBHOOK_URL	A webhook which can process events of interest, as described below	❌	App

Webhooks

Webhooks are triggered under a few circumstances:

• a new subscriber is recorded, or a user resubscribes
• an unknown message is received
• a user unsubscribes from the messaging service

That webhook is determined by the WEBHOOK_URL environment variable.

When receiving new subscriber or resubscribing a user, a POST request with the following payload is sent:

{
    "phoneNumber": "<E.164 formatted phone number>",
    "tags": ["<tag 1>", "<tag 2>"],
    "type": "New Subscriber"
}

For an unknown message event, a POST request with the following payload is sent:

{
    "message": "<entire message>",
    "phoneNumber": "<E.164 formatted phone number>",
    "type": "Invalid Message"
}

For unsubscribe events, a POST request with the following payload is sent:

{
    "phoneNumber": "<E.164 formatted phone number>",
    "type": "Invalid Message"
}

Usage on Twilio

Twilio has a guide for setting up their services to work with a broadcast application, like this. The major differences between that article and this application are as follows:

1. Create a new Functions service on Twilio, not a Classic Functions service
2. Ensure that your Functions instance on Twilio has all of the environment variables, as described above
3. Deploy this service from your machine to Twilio functions with: npm run deploy:prod
4. Proceed to use your new Functions service in place of the Classic service used in that article