# Notifications

> Players choose whether your app may notify them. Your server sends each notification, within limits Lia sets so the people who say yes stay glad they did. From the Lia developer docs: https://docs.lialabs.org/concepts/notifications

## How they work

<ol class="flow">
<li><b>The person allows them</b><span>Your page calls <code>Lia.requestNotifications()</code> at a good moment, and Lia asks in its own sheet. People can also turn your app's notifications on or off from its ⋯ menu.</span></li>
<li><b>Your server sends one</b><span><code>POST /notifications</code> with the player's id, the text and an optional <code>startParam</code>.</span></li>
<li><b>It reaches their phone</b><span>Under your app's name, as a push and in Lia's bell. Tapping it opens your app with your <code>startParam</code>.</span></li>
</ol>

## Asking

Ask when a notification would clearly help the person: their turn in a game, a delivery, a friend joining. Don't ask the moment your app opens.

```js
if (!Lia.notificationsAllowed) {
  const { allowed } = await Lia.requestNotifications();
  if (allowed) tellYourServer(); // so it knows it may notify this player
}
```

- If they already allowed them, `requestNotifications()` answers `{ allowed: true }` without asking.
- If your app may not send notifications at all (the Lia team turned them off), it fails with `notifications_off`.
- `Lia.notificationsAllowed` says where things stand, and the `notificationsChanged` event fires when the person changes it, from your ask or the ⋯ menu.

Lia doesn't tell your server when someone allows or stops notifications. Tell it yourself, or just send and handle `not_allowed`.

## Sending

```json
{ "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "text": "It's your move against @amara.", "startParam": "match-8k2d" }
```

See [`POST /notifications`](/reference/server-api#post-notifications) for every field and answer.

## Limits

Notifications are a privilege people give your app, so Lia keeps them few:

| Limit | Live | Test |
| --- | --- | --- |
| Who | Players who allowed your app's notifications | Your testers who allowed them |
| A day, from your app to one person | Your app's daily number, 3 unless the Lia team changed it | That number, and at least 20 |
| Apart, from your app to one person | 1 hour | 30 seconds |
| A day, from all apps together to one person | 6 | Not counted |
| Text | 1 to 180 characters, spaces and new lines become single spaces | Same |
| Not allowed in the text | Links, phone numbers and words used in scams (as in Lia's chats) | Same |

When a limit is reached, `POST /notifications` answers `429 rate_limited`. For your app's own limits it also says when you may try again, as `retryAt` (milliseconds since 1970).

"A day" is the last 24 hours for your app's limits, and the person's calendar day for the total from all apps.

## Opening your app from one

A notification opens your app with its `startParam` (1 to 64 of letters, digits, `_` and `-`), which your page reads from `Lia.startParam`. If your app is already open when the person taps it, your page hears a `startParam` event instead.

```js
function route(param) {
  if (param && param.startsWith("match-")) openMatch(param);
}
Lia.init().then(function () { route(Lia.startParam); Lia.ready(); });
Lia.on("startParam", function (data) { route(data.startParam); });
```

## Pushes and the bell

Every notification goes to Lia's bell. It's also pushed to the person's phone when they have Lia's pushes on; `POST /notifications` answers `pushed: false` when it only reached the bell.