Voice Notifications powered by Twilio
Table of Contents
- About
- Features
- Setup
- Cloud deployment
- Development considerations
- Resources
- Open Contribution
- License
About
This web-based reference app built in ReactJS and demonstrates how to leverage Twilio Programmable Voice and Twilio SDKs to create a voice notification system to make calls to your customers to deliver time-sensitive messages. This reference app can be used as a starting point, whether you are building a voice notification solution for Emergency Alerts or Sales & Marketing use cases.
Access to the source code should help you understand how to use the Twilio platform “building blocks” and Programmable Voice APIs to build an application for your own notification use case and accelerate your development.
How it works
This fully functional reference app allows you to send voice notifications to hundreds of recipients. All you need to do is specify a notification name for reference, write down the message, and upload a list of the recipients’ phone numbers in a .txt file. That’s it!
Once you broadcast the voice notification, the application will start placing outbound calls to deliver your message and listen for call updates in real-time using Twilio Voice Webhooks. Changes in call status are received asynchronously in the form of status callbacks and results are stored in the database as soon as they occur. The application is polling data from the database every 5 seconds to display progress and call updates in the UI.
For a more detailed exploration of the technology involved, please refer to the Technical Overview.
Technology stack
Features
- Send voice notifications to up to 500 recipients (configurable)
- Read message to recipients by using the text-to-speech capabilities
- Make a phone call to test the notification before sending to the complete list of recipients
- Automatically detect invalid and duplicated recipients phone numbers
- Track delivery progress of outbound calls in real-time
- Performance reports available for download in JSON format
Please note that using the application will incur in charges for Programmable Voice minutes.
Setup
Requirements
- Node.js v10+
- NPM v6+ (comes installed with newer Node versions)
- A PostgreSQL server (local or cloud)
Twilio Account Settings
| Variable | Description |
|---|---|
| Account Sid | Twilio Account Sid. This information can be found on your Account Dashboard in the Twilio Console |
| Auth Token | Twilio Auth Token. This information can be found on your Account Dashboard in the Twilio Console |
| Phone Number | A Twilio phone number. You can buy one on your Account Dashboard in the Twilio Console |
Application Settings
| Variable | Description |
|---|---|
| Passcode | Passcode to protect your Voice Notification App. This will be required to use the application |
Local Development
1. Clone the repository
$ git clone [email protected]:twilio/twilio-voice-notification-app.git
2. Install Dependencies
$ npm install
This application uses Twilio credentials to create the Call resources. It also requires a PostgreSQL database for storing the notifications and related call data. Add the following parameters to your .env file (use .env.example as a reference):
PASSCODE=XXXXXX
DATABASE_URL=postgres://username:password@hostname:port/dbname
ACCOUNT_SID=ACXXXXXXXXXXXXXXXXXXXXXXX
AUTH_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXX
Please note that you may need to install PostgreSQL and start it up or leverage some DBaaS provider to create a free cloud database (such as https://www.elephantsql.com)
3. Install Dependencies
$ npm start
The first time you run the app, it will create the database schemas, tables and relationships. In addition, this command will run the NodeJS server and will expose the ReactJS application via ngrok. An ngrok server is required so that Twilio can locate your server and invoke the webhooks on every call status update.
Alternatively, you can start UI and Server separately for a more granular development experience:
$ npm run start:ui
$ npm run start:server
Tests
Run unit tests locally with the following command
$ npm test
Cloud deployment
Additionally to trying out this application locally, you can deploy it to a host service. Here you have some 1-click deploy alternatives.
| Service | |
|---|---|
| Heroku |  |
Please notice that some free plans might have limitations. We encourage you to research about the hosting services and plans before using them.
Development considerations
Twilio
- The time it takes to complete delivering all the messages depends on the number of recipients, as well as, the Calls Per Second (CPS) setting on your Twilio account. Twilio accounts default to throttling 1 Call Per Second. You can increase your account's CPS threshold under your Voice Settings in the console
- Twilio has API concurrency limits. If you send too many concurrent calls, Twilio might respond to your requests with Error 429 - Too many requests. Refer to this guide for best practices for avoiding Error 429 responses.
- Twilio protects your account from fraud and abuse with Voice Dialing Geo Permissions to allow only legitimate calls. Voice Dialing Geographic Permissions control which countries and subsets of phone numbers you are able to dial out to from your Twilio project. Please note that the destinations you need to call should be enabled. You can manage call destinations from Twilio Console Voice Geographic Permission.
Cloud
Heroku free account
- This reference app can be deployed to Heroku in minutes. Please note that the Heroku free tier account has limits and is not suited for processing and storing large volumes of data. Before using Heroku for production purposes, consider upgrading to one of their paid plans.
- Heroku provides a PostgreSQL database for free which has a limit of 10,000 database row insertions. After this limit is reached, the DB is made read-only. This means you won’t be able to send new notifications, but you will still be able to access the application and review your voice notification history. To continue sending more notifications under the same deployed application, you will need to upgrade the plan. Alternatively, if you have a PostgreSQL database server hosted somewhere and want to use it instead of the one provided by Heroku, you can edit the
DATABASE_URLvariable in Heroku application settings and set your own PostgreSQL database connection.
Security
This reference app requires a passcode to control the access to the application. Please note that this represents very basic protection and you should replace it with an authentication mechanism of your choice (OAuth, JWT, etc).
Other
- For local development the application uses an ngrok server. Without it, Twilio cannot invoke the call-status-update webhook that runs from your local server. Ngrok enforces a limit of 40 connections per minute so be mindful about this limitation.
Resources
Open Contribution
This project is open source and welcomes contributions. All contributions are subject to our Code of Conduct.