Overview

Overview

The messaging hub provides message delivering services for notifiers that may be behind transient or unreliable data connections. Notifiers can connect to the messaging hub and drop off messages that need to be delivered either immediately or in the future. Notifiers can also query the messaging hub for the delivery status of an individual message or collection of messages.

Supported Delivery Endpoints

• SMS
• IVR (Interactive Voice Response)

Database

Message Templates

The messaging hub is responsible for keeping a database of notification messages that can be delivered via each endpoint. Notifiers do not provide message content directly, but rather selects a message template from the notification database for delivery. Notifiers can request a list of supported message templates to cache locally.

Record Format

• id: a unique identifier used to track/update a message
• action: new, update or cancel
• first_name: first name of recipient
• phone_number: phone number to deliver message to
• template_id: template id of message to deliver
• delivery_method: sms, ivr
• delivery_date: preferred delivery date
• delivery_expires: if specified, don't attempt delivery on or after this date
• preferred_time: hour or hour range in 24-hour UTC format (i.e. 10, 9-18)

Queuing (Bulk)

Initial Drop-off

When a notifier connects to the messaging hub, it can upload a list of one or more notifications for delivery. Each notification must contain a unique identifier that will be used for tracking delivery status and for preventing accidental duplication of message delivery (idempotence). The notifier may also use this identifier for canceling or updating a specific message. Once the data payload has been uploaded, the message hub will perform a quick data validation check and either accept or reject the entire payload. If rejected, it will almost always be because the notifier provided data in a format the messaging hub could not understand.

Data Preparation and Validation

Unique identifiers provided in data payloads are only considered to be unique across messages for a single notifier. Each identifier is combined with the notifier's account identifier to create a universally unique identifier (UUID) across the messaging hub. Once a payload has been accepted, the messaging hub goes through each message in the payload, generating a UUID and performing a series of operations based on the message's requested action.

Basic Validations (applies to all messages)

1. The action must be supported (new, update or cancel). Rejected with INVALID_ACTION error if not supported.
2. A first name must be provided. Rejected with MISSING_FIRST_NAME if not present.
3. A phone number must be provided. Rejected with _MISSING_PHONE_NUMBER if not present.
4. The template id must exist in the database. Rejected with INVALID_TEMPLATE if doesn't exist.
5. The delivery date must be a valid date. Rejected with INVALID_DELIVERY_DATE if not valid.
6. The delivery expires date must be a valid date or blank. Rejected with INVALID_DELIVERY_EXPIRES if not valid. A blank delivery expires date is assumed to be 7 days after the delivery date.
7. The preferred time must be a valid hour, hour range or blank. If invalid, the preferred time will be changed to blank which allows delivery to occur at any reasonable time.

new action

1. If the record already exists in the database with the respective UUID, the message record is rejected with an ALREDY_EXISTS error.
2. A new message record is created in the database with the message's UUID.
3. The message is added to the future events message queue using a combination of the delivery date and preferred time as its trigger time. The preferred time will only be used as a guide; the closer to the expires date, the further the trigger time will deviate from the preferred time (i.e. get more aggressive the closer we are to expiring).

update action

1. If the record doesn't exist in the database, it will be treated as if it was a new action.
2. If message data is the same as in the database, nothing further will occur.
3. If message data is different but has already been delivered successfully, reject with ALREADY_DELIVERED error.
4. Otherwise, an attempt will be made to remove the message from the future events message queue.
5. An attempt will be made to remove the message from the active events message queue if it exists and can be removed safely.
6. If successfully removed from the queue, the message record is updated and a new message is enqueued in the future events message queue.
7. If message could not be removed from one of the queue because its delivery was active/imminent, the database update is added to the future queue to attempt again later.

cancel action

1. If the record doesn't exist in the database, reject with MESSAGE_NOT_FOUND error.
2. If message has already been canceled, nothing further will occur.
3. If message has already been delivered successfully, reject with AREADY_DELIVERED error.
4. Otherwise, an attempt will be made to remove the message from the future events message queue.
5. An attempt will be made to remove the message from the active events message queue if it exists and can be removed safely.
6. If successfully removed from the queue, the message record is updated with a status of canceled.
7. If message could not be removed from one of the queues because its delivery was active/imminent, the cancel request is added to the future queue to attempt again later.