# Notifications and the public endpoints of OpenPlatform

> Send a notification to a user from your application, and use the token API for the list of users, the image upload and the sync socket of several instances.

Framework: openplatform
Product: OpenPlatform (openplatform@5)
Language: en
Content-SHA256: 172196f9c0e9c57455997c1066130953d232b02c2d6225f6a4538bce1f431188
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Besides the launch and the verification, OpenPlatform has a few endpoints for the applications and for other systems. They are in `controllers/verify.js`, `controllers/api.js` and `controllers/socket.js`.

## Send a notification

The answer of the verification contains `notify`, an address of the form `<platform url>/notify/?token=<checksum of user and application>`, when the user accepts notifications. The application sends a `POST` to it with the header `x-token` and a JSON body:

| Field | Meaning |
|---|---|
| `body` | the text of the notification |
| `path` | the path inside the application that the notification opens |
| `icon`, `color` | optional: they replace the icon and the colour of the application |

The value of `x-token` is the **notify token** that OpenPlatform derives for that user and application: the MD5 of the notify address salted with the `reqtoken` of the application, and the MD5 of that result salted with its `restoken` (`FUNC.makenotify` in `definitions/func.js`). Both secrets are the same ones that the application shares for the launch ([register an app](/en/openplatform/register-an-app/)).

OpenPlatform answers `Invalid token` when the checksum or the header do not match, and `Not allowed notifications` when the user or the application does not accept them. It also checks the allowed addresses of the application and that the user is confirmed, enabled and active. When everything is right it:

1. stores the notification (table `tbl_notification`) and increases the unread counter of the user;
2. updates the sessions of that user that are open in the portal, so the counter appears at once;
3. publishes `Notifications.create` by TMS when the setting `$tms` is on;
4. returns the identifier of the notification.

For users that are offline and have unread notifications, a service job sends **an email digest** ("Unread notifications") when the mail settings are configured, at most once every three days per user (`definitions/init.js`).

## The users API (a token)

`GET /users/` returns the groups and the users of the platform as JSON. It is **disabled** until the settings `allow_token` and `token` are set. The caller sends the token as the query parameter `token` or as the header `x-token`; repeated wrong tries are blocked. The users come without secrets: identifier, reference, language, gender, photo (an absolute address), name, email, colour, preferences, flags (`sa`, `isdisabled`, `isinactive`, `isonline`), dates and the ids of their groups.

## Upload an image

`POST /upload/base64/` (up to 2 MB) accepts a JSON body with the file name and `file` as a data URI, and only **JPEG**. It needs a signed-in user or the query token of the setting `servicetoken` (see [settings and database](/en/openplatform/settings-and-database/) for where that key comes from). The image is stored in the file storage `files` and the answer is its address, `/files/<id and checksum>.jpg`; the address only works with the checksum.

## Several instances: the sync socket

`SOCKET /sync/` connects instances of OpenPlatform. A client is accepted when the setting `sync` is on and the query `token` equals `sync_token`; any other client is closed with the code `4001` half a second after opening. The messages of a confirmed client are relayed to the others, and while a confirmed client is reconnecting the messages are queued for up to ten seconds.