Documentation

The Marianapolis Text Notification Service (MTNS) is a system designed to alert students, parents, and faculty to important changes and events on campus through text message alerts. The system is designed to require little maintenance and the user is ultimately responsible for managing their own subscription.

Requirements

MTNS supports any device that is capable of receiving text messages and has an active plan with a cellular carrier. The operating system the device uses makes no difference. In order to access any of the web-based tools used to manage the MTNS system, access to a computer or mobile device with a web browser and internet connection is necessary.

Registration and Use

The MTNS registration process is fairly straight forward and simple. The user must register his or her own device and should not complete the registration for anyone other than themselves. Note that once the user has completed the registration form and agreed to the Terms of Use, their registration may take up to 24 hours to be processed.

Carrier

The registration form will first ask the user to select their carrier from the dropdown menu. If a carrier is not listed, then MTNS currently does not support sending messages through them. Check the list below for a complete list of supported carriers.

• Alaska Communications
• Alltel
• AT&T
• Boost Mobile
• China Mobile
• Comcast
• Edge Wireless
• Google Fiber
• Metro PCS
• Nextel
• Simple Mobile
• Sprint
• Straight Talk
• T-Mobile
• Unicel
• Union Wireless
• US Cellular
• Verizon
• Virgin Mobile

Phone Number

Once the user has selected their carrier, they will be required to enter their 10-digit phone number. The country code must be excluded, however the area code, prefix, and line number are all required. It is also critical that the user does not enter any dashes or parenthesis in the field. The number must be entered in the same format as the example below.

User Information

The registration form will also ask the user to provide their first and last name when signing up. Note that this information is only used within the registration records to identify specific users and is never forwarded to the service's main database. This information (as well as any other personally identifiable information) is handled strictly in accordance with the service's Privacy Policy and will only be used for support purposes or as a verification measure if the user decides to unsubscribe.

Channels

There are a number of channels (or "topics") that one can select when registering for MTNS. Having multiple channels allows users to have more control over what kinds of messages they will receive. For more information on the various channels offered and what kinds of messages one can expect to see through those channels, click here.

Opting Out

If a user decides that they no longer want to receive texts from MTNS, or they would like to unsubscribe from a specific channel, they can do so on the MTNS homepage. Just follow the prompts to unsubscribe.

Advanced

SwitchboardSMS

SwitchboardSMS is an open-source project hosted on GitHub originally developed by Tom Nurse '18. The MTNS system is largely based on this software and has been configured in accordance with the included guidelines. Please note however that the MTNS system does not retain the original project's open-source nature and use of the service and any related components is governed by the MTNS Terms of Use.

To view the SwitchboardSMS repository, click here.

Service Architecture

Figure 1.1: This diagram provides a basic understanding of how the service works.

The MTNS Dispatch Console is a web-based utility designed for channel administrators. The console provides a simple form for sending messages through the system.

Getting Started

In order to use the console, you will need to sign in. This requires that you have access to a Marianapolis email account and have been given permission to use this tool. Additionally, you will need to have already set up the MTNS alias and have received your verification code from the Tech Innovations team.

Authentication

Setting up the alias

MTNS attempts to send all of its messages from no-reply.alerts@marianapolis.org. This is done to ensure that our text messages only come from one source when the user finally receives it. Unfortunately some carriers don’t support aliases, meaning some users will see the sender’s userID rather than the alias and messages will be split up by channel. Either way, the alias is still required for all channel administrators.

To set up the alias, administrators must first contact the Tech Innovations Team and ask to be added to the MTNS alias group. The Tech Innovations Team will then follow up with an email confirming when the new administrator has been added. The next step will then be to visit https://mail.google.com and select Settings from under the Gear menu in the top right corner of the window. Next, under Accounts > Send mail as… select Add another email address. In the following window, enter Marianapolis Text Notification Service as the name and no-reply.alerts@marianapolis.org as the email address. Ensure that both are typed exactly as they appear above. Leave Treat as alias checked and do not specify a reply-to address. Hit the Next step button and follow the directions to complete the process. Once the alias has been successfully added, the user may now sign into the Dispatch Console.

Signing in for the first time

To sign into the Dispatch Console, administrators will only need to sign in with their Marianapolis email account. Only accounts ending in @marianapolis.org will have access to this tool, so please be mindful of which Google account is currently signed in. For users who have already signed into the MPrep Alerts system once before, there will be no further actions required once they have entered their password. However, for first-time users, there are a few interim steps that must be completed before they can continue.

First, the user will be required to allow the MPrep Alerts program access to their email account. For more information about exactly what is being accessed by MPrep Alerts, check out Understanding Scopes. Once the user has hit Allow, the user will be brought to the Dispatch Console, however, the user may need to be re-authorized to use the console since the program’s permissions have just changed. To do this, they can simply click the button in the resulting banner to confirm that they have given MPrep Alerts access to their email account (Figure 2.1). Once that is done, the user may begin to use the console.

Figure 2.1: Some users may be prompted to re-authenticate their access to the Dispatch Console after accepting new permissions.

Understanding Scopes

These OAuth 2.0 Scopes identify the specific ways in which the MPrep Alerts system will have access to your Google account. The program will only utilize the scopes (shown in Figure 2.2) for the purposes outlined below. We highly recommended that all of our users read through this information carefully before clicking Allow. Although, please keep in mind that you will need to hit Allow in order to use the console. The program requesting these permissions may be displayed as either MPrep Alerts or mprep-alerts.firebaseapp.com.

Figure 2.2: Users of the console will need to allow the MPrep Alerts system access to their Google account as described in this section. This includes allowing the program to send email on your behalf.

Basic account info

You may be asked to allow the program access to your basic account information. This will only ever be used to obtain your userID and/or email address. Your userID helps us identify your account in our system and determine when you last signed in. Your email address will be attached to every message you send through the Dispatch Console to aid us in tracking down the sender of each message if the message fails to reach users.

Read, send, delete, and manage your email

This scope allows the program to check your email settings for the presence of a specific alias (see Setting up the alias). If the MTNS alias has not yet been added to your account, the program may encounter an error when attempting to send a message. The system requires this alias to be in use by everyone who uses the console to ensure that users receive text messages from a single source, if possible. This is the only action that has been implemented for this scope. The MPrep Alerts system is incapable of reading, modifying, or deleting any of your emails.

Send email as you

This is probably the most important scope the MPrep Alerts system utilizes to send messages. MTNS takes advantage of the Gmail API to send messages to end-users. In order to prevent overrunning daily quotas, MTNS uses the account that is currently signed in to send these messages. This means that your userID and email address will be attached to each message as if you sent it yourself. For most users, they will never know where the message originated, but for some users on carriers that don't support aliases, your userID will be displayed in the from field of the text to prove to users that the message is legitimate.

The MPrep Alerts system will never send messages from your account without your direct input. Additionally, checks are in place to ensure that sending a message through the Dispatch Console doesn't use up your entire daily quota. If the recipient base exceeds the limits, the console will halt once there are 10 credits remaining. This will ensure that you can continue to use your account to send and receive emails. Quotas reset every 24 hours.

Using the Console

Using the console is simple. First, select the topic you are authorized to send messages from, then type your message into the box below. Once you are ready to send the message, hit the Submit button.

For security purposes, some channels require users to enter a verification code to continue. This is to prevent students (who technically also have access to the console) from sending messages through channels such as Delays and Cancellations. Your message will not be sent until you enter the code exactly as you were instructed. If you have lost or forgotten this code, please contact the Tech Innovations Team for a replacement.

Advanced For Developer Use

Error Handling

There are a lot of things that can go wrong with such a dynamic system as MTNS. The successful processing of a message relies on a number of programs and services that all need to work together. Unfortunately, sometimes certain parts of the system are temporarily unavailable or badly formatted information somehow gets through and causes the program to stop. Some of these errors can easily be corrected and sometimes the message just needs to be sent again. But on occasion, dropped connections elsewhere can make the problem hard to diagnose. Included below are some common issues which may occur and solutions for detecting and/or solving some of them.

Phone number not found

This error will occur if the phone number provided is incorrectly formatted (i.e. contains dashes, country code, or parenthesis) or the provided number is not for a cell phone. This error may also occur if the user has selected the wrong carrier. Users will typically report that they are not receiving texts and emails mentioning that a message has bounced may appear in the MTNS Messages Archive.

To solve this issue, get an accurate phone number from the user and confirm their carrier. Replace the current entry for that user in the registration database with the correct information. If the user has multiple entries in the registration database, remove and/or merge the duplicates.

“Message has been queued”, but no message(s) received

This usually indicates that there was an error with the message after it has left our system and these problems are often out of our control. However, developers and Tech Innovations Team members can determine what went wrong by viewing the API data at https://console.developers.google.com. In order to view this data, you must have access to the MPrep Alerts project and it must be selected in the top navigation bar. Under APIs & Services > Dashboard, there should be enough data to determine what happened.

The most common responses one might see in the Google Cloud API Console are 200 (Success), 400 (Authentication error or bad request), and 500 (Internal error). In the event that you are presented with some sort of 400 error, it is recommended that you sign out of the Dispatch Console, sign back in, and try again. If the problem persists, check the console’s source code and ensure that the batch request is being formatted properly. Additionally, check the web development console for any warning messages that may have been produced.

If you receive a 500 error, just try to send the message again, but note that if it continues to fail, this may indicate that the information being sent by the console does not meet the standards of the Gmail API. Review the documentation thoroughly to ensure that all of the requirements are being met.

If the Google Cloud Console data shows no indication of any requests being processed and no text messages have been received, despite the fact that a message was "successfully" sent from the console, visit https://status.firebase.google.com and check to see if the Realtime Database system is experiencing some downtime*. This situation usually occurs whenever the console fails to load information stored in the User Database. This may also occur if the User Database is busy processing new registrations while the console is attempting to connect.

*Errors that result from situations outside of our control (i.e. Firebase downtime) are of little concern. If possible, attempt to re-send the original message. Although it is preferable that those with access to the Google Cloud Console attempt to identify the error code prior to re-sending messages, as this will help ensure that users do not receive duplicate messages if the request in question does happen to pass through the system.

Last updated: March 21, 2018

Unless otherwise stated, any code samples on this site are licensed under the Apache 2.0 license.