# Notifications

## Purpose

Pluscare sends notifications to users and their contacts through configurable channels (email and WhatsApp). Notifications are used for reminders, alerts, registration, and other system events.

## How it works

### Delivery channels

Each user sets their preferred notification channels in their profile. The value is stored in `users.notification_channels`.

Examples: `["mail"]`, `["mail","whatsapp"]`

Reminders and other features inherit the recipient's channel preferences — the channel does not need to be configured per notification.

### Email

During local development, all emails are captured by Mailpit at http://localhost:8025/.

### WhatsApp

WhatsApp notifications are sent via the WhatsApp Business API through a dedicated [Meta App](https://developers.facebook.com/apps/1133990871534824/dashboard/?business_id=977057774056489).

Message templates and API integration are managed in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/overview?business_id=977057774056489&asset_id=679759214507935).

### Reminder confirmation via notification (CTA)

The application supports confirmation of reminders directly from notification messages (email or WhatsApp).

When a reminder is generated — either from a **drug prescription** or from **system alerts** — the recipient receives a notification containing a confirmation button (call-to-action link).

1. A reminder is created by the system (prescription schedule or alert).
2. A notification is sent to the recipient including a secure URL with a unique token:
   ```
   /cta/confirm?token=REMINDER_TOKEN
   ```
3. When the user clicks the confirmation link:
   - the reminder is marked as confirmed
   - `confirmed_at` timestamp is stored
   - confirmation channel is saved (`confirmed_via`: email or whatsapp)
   - the reminder is disabled
   - future executions are cancelled (`next_run_at = null`)
4. The user is shown a confirmation page.

This allows patients or caregivers to acknowledge that an action has been completed (e.g. medication taken or alert handled) without logging into the platform.

## Key entities & DB

| Field / concept | Description |
|-----------------|-------------|
| `users.notification_channels` | Preferred delivery channels per user |
| `confirmed_at` | Timestamp when a reminder was confirmed via CTA |
| `confirmed_via` | Channel used for confirmation (`email` or `whatsapp`) |

## Technical flow

1. A feature (reminder, alert, etc.) triggers notification dispatch.
2. The system reads each recipient's `notification_channels`.
3. Notifications are sent via the configured channels (mail driver, WhatsApp API).
4. For CTA-enabled reminders, the notification includes a tokenized confirmation URL.

## Notes / edge cases

- CTA confirmation links are **public** and do not require authentication.
- The token uniquely identifies the reminder.
- The confirmation operation is **idempotent** — clicking multiple times does not change the result.
- Invalid or missing tokens return `404`.

## Related documentation

- [Reminders](reminders.md) — scheduling and dispatch
- [Business Logic](../business-logic.md) — alerts and drug prescriptions
- [Development Guide](../development.md) — integration dashboards