How to Build Twilio Appointment Reminders with Node.js and Express

Many of us have a love/hate relationship with appointment reminders. The last thing anyone wants is another email, or worse — a phone call from an agent, either live or automated. Perhaps the least annoying notification is a text message, and it's also the easiest, leading many companies to use this approach as part of their customer service strategy and more!

Not only is using SMS appointment reminders a way for consumers to streamline their to-do list but using them is an excellent way for businesses to communicate with customers. Nonprofits, doctors' offices, political groups, and all types of businesses and organizations are using SMS to connect with their customers and members who prefer texting as a communication channel. Whether you're on the move or stuck in a meeting, receiving an SMS is a quick and convenient way to help manage your schedule.

Using the Twilio API to build intelligent SMS reminders

The Twilio REST APITrack this API is one way you can create intelligent reminders, and you can also benefit from simple Integration with your CRM and reservation systems. For example, you can reduce customer no-shows by notifying them of upcoming appointments and allowing them to make changes all without ever involving a live agent.

Below, you'll learn the key bits of code and how to use them to build this capability. Although Twilio supports any language capable of talking to a REST API and has libraries for many popular web languages (such as Java and C#), let's focus on implementation in Node.js. Node.js is a JavaScript runtime which can be used to create web applications.

Before we start, make sure Node is installed on the machine where your sample app is going to run. We'll be using MongoDB on the backend – you can grab it here if you don't yet have it installed. (MongoDB is not a required for storing data - you can just as easily use the database of your choice.) Also, make sure you create a free Twilio account to follow the tutorial today.

Configure the application with your account credentials

Before you can use the Twilio API to send reminder text messages, you need to grab your Twilio account credentials. Locate these in the Twilio Console and copy them somewhere safe. You'll also need an SMS-enabled phone number (you can purchase one from the Phone Number console).

  1. In a terminal window on the server that will host your application, clone our appointment reminder starter using git using the following command (if needed, here are git install instructions for your platform):
    git Clone
  2. Change into that directory then install the dependencies using npm:
    npm install
  3. Copy the environment variable example file:
    cp .env .env.local
  4. Edit the new .env file, pasting in your Account SID, Auth Token, and Twilio Phone Number for the placeholders. You'll also need to change MONGO_URL; to run locally with a default installation you can reuse the URL from
 Configure the application with your account credentials

When satisfied, you can start the application using npm start

Let's look at how it all works next.

Create a new test appointment

To begin, you need to have the data that's associated with some scheduled appointment. The controller will take the required information (a customer's name and phone number, plus a time and date for the appointment) and save the information as a basic appointment.

If you're using MongoDB for your database, then for this application, you'll use the mongoose package to store appointments in MongoDB. The JavaScript Source Code in a file called appointment.js provides the scaffolding.

Create a new test appointment

Now that you have an appointment created, let's schedule a reminder for it.

Schedule a job to send reminders

Every minute, the application should check the appointment database for any appointments that require reminders.

We put the code in scheduler.js. To make this happen, you'll use node-cron. You'll configure both the job you'd like to run and the interval on which to run it. Then, when you'll start the application you'll call it using scheduler.start()

Schedule a job to send reminders

Create a worker Function to run the job

To execute this recurring job logic, there's a worker function in the file Create a worker function to run the jobworkers/notificationsWorker.js that uses a Static Model Method to query the database for upcoming appointments and send reminders as necessary.

 Create a worker function to run the job

Next, let's see how the Appointment job works in detail.

Find appointments that need reminders

The recurring job uses an Appointment static method to query the database for approaching appointments and sends out reminder messages by using a Twilio REST Client (which you initialized previously with your Twilio account credentials).

Because appointment times could be in different time zones, we'll use the Moment.js Library in order to properly query every upcoming appointment accordingly.

We do this in the file models/appointment.js:

Find appointments that need reminders

After we're happy with models/appointment.js, all that is left to do is send the actual SMS.

Send reminder messages with the Twilio API

This next block of code in appointment.js is called every time you need to send a SMS reminder. You'll receive a configuration object with a To: field, which is the customer's phone number, a From: field, which is the number in our Twilio account established earlier, and a body field, which contains the text of the message. Then it's sent to the sendMessage() method along with a Callback to log errors and success.

Send reminder messages with the Twilio API

Test and run the code

At this point, you're ready to try everything out. Assuming you already ran npm start, your application will be waiting for you at http://localhost:3000.

Test and run the code
  1. Load up http://localhost:3000
  2. Click the 'New appointment' link in the header
  3. In the form that opens, enter your name, cell phone number, appointment data, notification time, and time zone.
    Be sure to enter your number in E.164 format (e.g. +18005551212)
  4. Wait until the proper time and verify you get a SMS!

And that's it! Your application is now all set to send out reminders for upcoming appointments, be it a restaurant reservation or a dentist appointment. Now that you're familiar with how to create an appointment reminder using Node.js and Express, you have a sense of the various projects you can build with Twilio's programmable technology.

If you're interested in this application, also see our step by step Node appointment reminders tutorial which covers the above in more detail. Whether it's SMS appointment reminders or something else, we can't wait to see what you build with Twilio.

Be sure to read the next Messaging article: How to Integrate Chat Features into Client Apps Via Sendbird's API