A pretty history of the conversations with your users.

• Features
• Getting started
• How to use
  • 1. Model
  • 2. API
    • POST /api/notifications
    • POST /api/notifications/:notificationId/events
  • 3. Options
  • 4. In production
• Contributing
• Need help? Found a bug?
• Related Projects

Features

• Pretty history — Display all the conversations with your users, along with events associated with the notifications (no more "Did user X received the Y SMS?" from the client service team).

• Configure data retention — Decide until when each notification must be kept and set a capping on your MongoDB database.

• Real-time data — The displayed notifications are automatically refreshed when they change or when new ones are created (with the help of Meteor).

• Search by user info — All user fields are indexed and you can make complex searches with negations and phrases.

• User management — An administrator can easily give or revoke access to any user.

• Simple API — The model of the extra data (users, notification details) you send to the API is up to you.

• MIT license — Use it like you want.

Getting Started

You can find a demo here or run it locally with docker:

$ docker run -d -p 80:3000 --name notifme-history notifme/history:dev-latest

✨ Then open http://localhost in your favorite browser.

You will need an OAuth client ID and secret from Google (the steps to create one will be detailed in the application).

notifme/history:dev-* images are not suited for production use. They include MongoDB and if you delete the container all the data is lost. See 4. In production

How to use

• 1. Model
• 2. API
  • POST /api/notifications
  • POST /api/notifications/:notificationId/events
• 3. Options
• 4. In production

1. Model

Data is distributed into 3 main tables: Notifications, NotificationDetails, and NotificationUsers.

Table	Use
Notifications	This is the only table with an imposed model. Data corresponds with the notification list view and is intended to be a summary of the content (datetime, channel, title, text, tags...) to be kept longer than all the details. You choose how long to keep each notification by setting an expiration date.
NotificationDetails	This is where you can store all the (possibly lengthy) details of your notifications. You can use the model you want. The table can be capped to a given size in MB so you don't exceed your quota.
NotificationUsers	This table is used for the search feature. All field are indexes, so you should keep this data simple. The only required field is id. You choose how long to keep each user by setting an expiration date, or it will expire when the last notification associated expires.

2. API

POST /api/notifications

Usage: when you send a notification to a user, call this API to add it to the history.

Field	Required	Type	Description
id	false	String	The external identifier of the notification. Required if you want to add events later on.
channel	true	String	Type of the notification, you can put any string you want (email, sms, push, webpush, slack...).
datetime	true	Date	Datetime ISO format.
title	true	String	Notification's title.
text	false	String	Notification's text content or summary.
tags	false	String[]	Visual tags associated with the notification.
user	false	Object	User information (for search feature). Only one field is required: id. The rest is up to you (but beware of the search index size, keep your data simple).
details	false	Object	Any detail you want to keep.
events	false	Object[]	Initial events. Fields: type (String, required), datetime (Date, required), info (String, optional).
isFromUser	false	boolean	If the message comes from a user.
expireAt	false	Date	Time until when to keep the notification (ISO format).

Minimal example:

curl -X POST http://localhost:3000/api/notifications \
  -H 'authorization: ...' \
  -H 'content-type: application/json' \
  -d '{ "title": "Minimal notification", "channel": "sms", "datetime": "2019-12-24 12:00:00" }'

Complete example:

curl -X POST http://localhost:3000/api/notifications \
  -H 'authorization: ...' \
  -H 'content-type: application/json' \
  -d '{ "id": "notification-1", "title": "Complete notification", "channel": "email", "datetime": "2019-12-24 12:00:00", "text": "Hello!", "tags": [ "John Doe" ], "user": { "id": "user-1", "name": "John Doe", "email": "[email protected]", "phone": "+15000000000" }, "details": { "subject": "Test email!", "html": "<h1>Hello!</h1>" }, "events": [ { "type": "sent", "datetime": "2019-12-24 12:00:00" } ], "expireAt": "2024-12-24 12:00:00" }'

User answer example:

curl -X POST http://localhost:3000/api/notifications \
-H 'authorization: ...' \
-H 'content-type: application/json' \
-d '{ "title": "Re: Minimal notification", "channel": "sms", "datetime": "2019-12-25 12:00:00", "isFromUser": true, "text": "this is my answer" }'

POST /api/notifications/:notificationId/events

Usage: set up webhooks in all your favorite notification providers, then call this API to save the event.

Field	Required	Type	Description
notificationId	true	String	The external identifier of the notification. (This parameter is part of the URL).
type	true	String	Type of your event, you can put any string you want (sent, delivered, errored...).
datetime	true	Date	Datetime ISO format.
info	false	String	Any information you want to keep about this event.

Example:

curl -X POST http://localhost:3000/api/notifications/notification-1/events \
  -H 'authorization: ...' \
  -H 'content-type: application/json' \
  -d '{ "type": "delivered", "datetime": "2019-12-24 12:00:00" }'

3. Options

Name	Description
NOTIFICATION_DETAILS_LIMIT_MB	Optional. Capping in MB for the NotificationDetails table. Changing this value on a non-empty table is possible, but the operation will require a global write lock and block all other operations until it has completed.
GOOGLE_CONSUMER_KEY	Required (but not necessarily at startup). OAuth client ID from Google.
GOOGLE_CONSUMER_SECRET	Required (but not necessarily at startup). OAuth secret from Google.

You can pass them when you run docker:

$ docker run -d -e NOTIFICATION_DETAILS_LIMIT_MB=256 ...

4. In production

To run in production, simply use the notifme/history:latest image.

$ docker run -d \
  -e MONGO_URL=mongodb://<dbuser>:<dbpassword>@<url>:<port>/<dbname> \
  -e ROOT_URL=https://example.com \
  -e NOTIFICATION_DETAILS_LIMIT_MB=512 \
  -p 80:3000 --name notifme-history notifme/history:latest

On a budget?

• 1. Open an mLab account (free tier with 500MB), create a database and a user for this database. You'll get an URL of the form mongodb://<dbuser>:<dbpassword>@<url>:<port>/<dbname>.
• 2. Deploy it with Now: npm i -g now && now login && now --public notifme/notifme-history. Use https://notifme-history-[your-company].now.sh as ROOT_URL and 128 for NOTIFICATION_DETAILS_LIMIT_MB.
• 3. Alias you deployment: now alias https://notifme-history-[your-company]-[xxxxxxxxxx].now.sh notifme-history-[your-company] and scale it: now scale notifme-history-[your-company].now.sh 1

And... there you go! 😺

Contributing

Contributions are very welcome!

To get started: fork this repository to your own GitHub account and then clone it to your local device.

$ # Install meteor 1.6 (if not already installed)
$ curl https://install.meteor.com/ | sh

$ git clone [email protected]:[YOUR_USERNAME]/notifme-history.git && cd notifme-history
$ meteor npm install
$ npm run start

Before making a pull request, check that the code respects the Standard JS rules.

$ npm run lint

Need Help? Found a bug?

Submit an issue to the project Github if you need any help. And, of course, feel free to submit pull requests with bug fixes or changes.

Related Projects

A Node.js library to send all kinds of transactional notifications.