# Notifications

Tap the right people on the shoulder in the app: a notification with an unread badge and a link straight to the record.

Something needs a person's attention: a certificate expires next week, a request is waiting for approval, a reading went out of range. **Notifications** put it in front of them inside the app, with an unread count and a click that opens the right record.

## Where people see them

Notifications land under **Messages** in the sidebar (the bell icon), in **Activity**: *alerts and reminders from your modules*. The unread count shows on **Messages**. Clicking a notification opens your module at the screen you linked.

## Who gets a notification

Your module picks the people in one of two ways, or both:

| By | Use it when | Example |
|---|---|---|
| **Person** | You know exactly who | The employee whose training is due |
| **Permission** | Anyone allowed to act should know | Everyone who can approve requests |

Choosing by permission keeps working as people change jobs: the Workspace Admin changes roles, and the right people get the next one. Notifications only ever reach active people in the same workspace.

## Info, warning and critical

Each notification has a level, shown with its own color:

- **Info**: good to know. *"New request from Ana."*
- **Warning**: needs action soon. *"Forklift inspection due in 3 days."*
- **Critical**: needs action now. *"Freezer 2 is above temperature."*

Keep **critical** rare, so people still trust it.

## Never twice: the dedupe key

A daily job that checks for due training would tell the same person every morning. Give each notification a **dedupe key**, such as *training 123, due Dec 4, due soon*. The platform posts it once per person; a repeat with the same key does nothing. When the situation changes (a new due date, or *overdue* instead of *due soon*), the key changes too, and they hear about it again.

## Notifications or email: which to use

| Use | When |
|---|---|
| **Notification** | People who work in the app; things to act on there. |
| **[Email](article:00b75e30-6ac5-4c87-a12e-af4178a09f87)** | People outside the workspace (customers, applicants), or something that must reach someone who isn't signed in. |
| **Both** | Important and urgent, such as a critical alarm. |

## Ask the Module Builder

> *"Every morning, notify each employee whose forklift certificate expires in the next 14 days, and warn the safety managers about any that already expired. Don't repeat yourself."*

## For developers

```python
await notify_users("TRAINING", tenant_id, "Forklift certificate due in 12 days",
                   user_ids=[employee_id], permission="TRAINING.MANAGE",
                   body="Due Dec 4.", link="/modules/training/ui/index.html",
                   severity="warning", dedupe_key=f"{cert_id}:{due}:due_soon")
# -> {"recipients": 3, "posted": 1}  (posted counts only new ones)
```

## Good to know

- **Links stay inside your module.** A notification can only open your own module's screens.
- **Up to 500 people** per notification. For more, notify by a narrower permission.
- **Included**: notifications aren't metered.
- **Running on a timetable?** See [Schedules and triggers](article:6fdf08ad-f3dc-4641-9c6c-457de97ebf29).


Source: https://datavisions.ai/docs/creators/platform-services/notifications
