Steps

Set up the application locally

1. Clone sms-reminder

  1. Open a command shell session.
  2. Change the current working directory to the location where you want the cloned directory to be made.
  3. Copy and run the following:
    4. git clone https://github.com/flowroute/sms-reminder.git

2. Update environment variables to work with the Flowroute Messaging API

  1. Change the current working directory to sms-reminder. 
    cd sms-reminder
  2. Run the following pip command. Depending on your pip permissions, you may be required to preface each pip command with sudo. 
    pip install -r requirements.txt
  3. By default Docker Compose will look for an .env file in the same directory as your docker-compose.yml file. Open the .env file in the sms-reminder directory and update the variables with your Flowroute details:
    4. FLOWROUTE_ACCESS_KEY=YOUR_ACCESS_KEY
FLOWROUTE_SECRET_KEY=YOUR_SECRET_KEY
FLOWROUTE_NUMBER=YOUR_FLOWROUTE_NUMBER
ORG_NAME=YOUR_ORG_NAME
DEBUG_MODE=True

Run Appointment Reminder via Docker Compose

  1. Ensure the Docker daemon is running.
  2. Run the following to build the appointment_reminder service.
    3. 
docker-compose build
  3. Run the following to start the components of our application: Redis, Celery, and the Flowroute Messaging API.
    4. docker-compose up

Work with the reminder API endpoint

Create, retrieve, and delete appointment reminders

This tutorial doesn't cover how to set up your webserver with a public IP address. See Additional Resources for more on that topic. The following example requests assume that the appointment_reminder application is listening on 0.0.0.0:8000.

Methods

Create an appointment reminder

Use the POST method to send an appointment reminder. The following is a list of accepted body parameters.

Parameter Required Type Description
contact_number True string The recipient phone number in E.164 format. e.g., 1XXXXXXXXXX
appointment_time True string The scheduled appointment time in ISO 8601 "YYYY-MM-DDTHH:mmZ" format.
notify_window True integer The length of time, in hours, before the scheduled appointment to send a reminder. For example, 1indicates that a reminder is sent one hour before the appointment_time.
location False string The appointment location. Limited to 128 characters. The following SQL characters are disallowed:|,-,*,/,<>,<, >, ,,(comma),=,<=,>=,~=,!=, ^=,(,)
participant False string Provides more information about the appointment. For example, this might be a particular person or department at the location. Limited to 256 characters.

Usage

curl -v -X POST -d '{"contact_number":<contact number> 
"appointment_time": "<appointment_time>",  "notify_window":"<notify_window>", 
"location":"<location>"}' \
-H "Content-Type: application/json" \ 
http://<ip_address>:<port>/reminder

Example Request

curl http://0.0.0.0:8000/reminder -X POST \
-d '{"contact_number":"12067392634", "appointment_time": "2017-07-06T13:00-0800", 
"notify_window":"1", "location":"Seattle Vision Clinic", 
"participant": "Thomas Smith at front desk"}'

Example Response

A successful POST returns a reminder_id and a confirmation message as shown below: 

{
  "reminder_id": "a74d3512583a48a194c2e2a600cc1903",
  "message": "Successfully created a reminder with id a74d3512583a48a194c2e2a600cc1903."
}

Retrieve a reminder list

Use the GET method to retrieve a list of reminders.

Usage

curl -X GET http://<ip_address>:<port>/reminder

Example Request

cURL 
curl -X GET http://192.168.99.100:8000/reminder/2a00aadba83b40aa8a3a6e99a1bd88b9

Example Response

A successful GET returns the following: 

{
    "confirm_sent": true, 
    "contact_number": "12069928996", 
    "participant": "Joe", 
    "location": "West Side Mechanics", 
    "reminder_id": "2a00aadba83b40aa8a3a6e99a1bd88b9", 
    "appt_user_dt": "2016-07-15 11:40:00", 
    "will_attend": true, 
    "notify_sys_dt": "2016-07-15 17:40:00", 
    "reminder_sent": true, 
    "appt_sys_dt": "2016-07-15 18:40:00"}

Retrieve a single reminder

Use the GET method to retrieve information about a specific reminder.

Usage

curl -X GET http://<ip_address>:<port>/reminder/reminder_id

Example Request

cURL 
curl -X GET http://192.168.99.100:8000/reminder/2a00aadba83b40aa8a3a6e99a1bd88b9

Example Response

A successful GET returns the following: 

{
    "confirm_sent": true, 
    "contact_number": "12069928996", 
    "participant": "Joe", 
    "location": "West Side Mechanics", 
    "reminder_id": "2a00aadba83b40aa8a3a6e99a1bd88b9", 
    "appt_user_dt": "2016-07-15 11:40:00", 
    "will_attend": true, 
    "notify_sys_dt": "2016-07-15 17:40:00", 
    "reminder_sent": true, 
    "appt_sys_dt": "2016-07-15 18:40:00"
}

Successful Response Fields

The following fields are returned in the JSON response for both a single reminder and for a list of reminders:

Parameter Nullable Description
confirm_sent False Confirmation that the reminder was received. This will be true for received or false that the confirmation was not received.
contact_number False The recipient number for the appointment reminder.
participant False Any additional context for the appointment - this might be the name of a particular person or department at the location.
location True The location for the appointment. This might be the name of a business.
reminder_id False The appointment's original reminder_id.
appt_user_dt False The user's appointment time, based on the time zone passed in the original reminder.
notify_sys_dt False The user's appointment time, in UTC, minus the time set for notify_window.
appt_sys_dt False The user's appointment time, in UTC, based on the time zone passed in the original reminder.
reminder_sent False A 200 response was received from the Flowroute Messsaging API. This field will be either true or false.
will_attend True Displays null if the user hasn't responded; otherwise, this will display a yes or no boolean if the user has responded.

Delete a reminder

Use the DELETE method and pass an existing reminder_id to delete an appointment reminder.

Usage

curl -v -X DELETE http://<ip_address>:<port>reminder/reminder_id

Example Request

curl -v -X DELETE http://192.168.99.100:8000/reminder/00795872bc554893bde41f3f9cb807d0

Example Response

A successful DELETE returns the appointment reminder_id and message: 

{
  "reminder_id": "fce20ff252d7490eb44311c7f18ed6be",
  "message": "Successfully deleted reminder with id fce20ff252d7490eb44311c7f18ed6be."
}

Error Responses

The appointment_reminder app can return the following error responses:

  • 400 for an invalid argument
  • 500 if Redis is unavailable

The reminder endpoint will return a 500HTTP status code if there is any internal error.

Change app settings (Optional)

Change messages and DateTime language

appointment_reminder/settings.py contains default templates for appointment reminders, confirmation, cancellation, and unparsable responses. You can accept these default messages or optionally change any or all of the messages.

Within appointment_reminder/settings.py, you can customize the appointment reminder messages as well as change the LANGUAGE_DEFAULT value used for the DateTime in reminder messages.

MSG_TEMPLATE

Change the appointment reminder message sent to recipients. 

MSG_TEMPLATE = ("[{}] You have an appointment on {}{}. "  # company, datetime, additional details            "Please reply 'Yes' to confirm, or 'No'to cancel.")

Important

Do not remove or change the brackets (`{}`)within the message template.

CONFIRMATION_RESPONSE

Change the response message sent to the recipient upon a successful appointment confirmation received from the recipient.

CONFIRMATION_RESPONSE = (u"[{}]\nThank you! Your appointment has been marked confirmed.").format(ORG_NAME)

CANCEL_RESPONSE

Change the cancellation response message sent to the recipient upon a successful appointment cancellation response received from the recipient.

      
CANCEL_RESPONSE = (u"[{}]\nThank you! Your appointment has been\"                   
                  u" marked canceled.").format(ORG_NAME)",

UNPARSABLE_RESPONSE

An unparsable response is a response received from a recipient that cannot be understood. For example, if the MSG_TEMPLATE asks the recipient to reply witheither Yes or No, but the recipient sends something other than either of those two options, the Appointment Reminder service will be unable to determine the response. The unparsable response message is a return message to the recipient prompting them again to respond witheither Yes or No. 

UNPARSABLE_RESPONSE = (u\"[{}]\nSorry, we did not understand your response. "\n                                               u"Please reply 'Yes' to confirm, or 'No' "                       
                        u"to cancel.").format(ORG_NAME)"

Change the default DateTime language

In settings.py, you can set the DateTime of the reminder message to use any language supported by arrow.locales. Changing the default language translates only the DateTime values sent in the message to use those languages, not the content of the message itself.

To change the default language use the names identifying the language in arrow.locales. For example, to change the default language to French, edit LANGUAGE_DEFAULT as follows: 

LANGUAGE_DEFAULT = 'fr'

Some languages in arrow.locales also include abbreviated forms for months and days. If the language has abbreviated forms, that abbreviated form will be used in the message. For example, in French, the abbreviated form of mercredi (Wednesday) is mer, and juillet (July) is juil. An appointment reminder using a French DateTime will send the abbreviated forms.

If your language is English your reminder message might be: "You have an appointment on Wednesday, July 21 at 2:00 PM. Please reply Yes to confirm, or No to cancel." If French is set as the default language, the same message except for the abbreviated French DateTime will be sent: "You have an appointment on mer 21 juil à 14:00. Please reply Yes to confirm, or No to cancel."

Additional Resources

To learn more about setting up a UNIX-based web server and running Python on it, read this blog series. The following articles are available for other environments: