# Notification

A **Notification** is a configuration rule that binds a system event trigger (like a completed challenge, streak about to break, completed mission, or unlocked reward) to a specific template (`email_template`, `push_notification_template`, `sms_template`, or `whatsapp_template`) and an optional provider integration (such as Firebase Cloud Messaging, AWS SMS, or Gamopanda Email). When the defined event occurs, the platform automatically resolves the associated template, merges recipient data, and dispatches the transactional message.

---

## How it works

1. **Design a template** — set up a template for your target communication channel (e.g. an [Email Template](/email-template), [Push Notification Template](/push-notification-template), [SMS Template](/sms-template), or [WhatsApp Template](/whatsapp-template)).
2. **Create a notification rule** — map a system event trigger (`eventCode`) to a template type (`templateType`), template ID (`templateId`), and optionally an integration provider (`integrationProvider`) and integration ID (`integrationId`).
3. **Activate the rule** — set the status to `live`. The system will now listen for matching platform events.
4. **Trigger notification** — when a member triggers the target event (e.g. completes a streak or unlocks a reward), the platform evaluates active notification rules, renders the template, and sends the message via the configured provider.
5. **Log delivery** — each dispatch attempt creates a record in the [Notification Log](/notification-log) for debugging and auditing.

---

## Fields

### Basic information

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `eventCode` | enum | ✅ | — | The system event code that triggers the notification rule. See [Trigger Events](#trigger-events) below. |
| `templateType` | enum | ✅ | — | The communication channel template type: `email_template` · `push_notification_template` · `sms_template` · `whatsapp_template`. |
| `templateId` | UUID | Conditionally | — | Unique identifier of the associated template record. Required when `templateType` is set. |
| `integrationProvider` | enum | Conditionally | — | The messaging service provider: [`firebase_cloud_messaging`](/firebase-cloud-messaging) · [`aws_sms`](/aws-sms) · [`gamopanda_email`](/gamopanda-email) · [`aws_whatsapp`](/aws-whatsapp). Required for Push, SMS, Email, and WhatsApp template types. |
| `integrationId` | UUID | Conditionally | — | Unique identifier of the associated integration configuration record. Required when `integrationProvider` is set. |
| `status` | enum | ✅ | `draft` | The rule status: `draft` · `live` · `paused`. Only `live` notifications trigger outgoing dispatches. |

---

## Trigger events

The `eventCode` determines which platform action triggers this notification rule:

### Streak Events

| Event Code | Trigger Condition |
|---|---|
| `streak_progress_broken` | Sent when a user fails to maintain their streak and it resets |
| `streak_progress_to_be_broken` | Warning reminder sent before a streak period expires |
| `streak_progress_completed` | Sent when the user completes the overall target streak |
| `streak_progress_milestone_completed` | Sent when the user completes a milestone in a streak |
| `streak_progress_non_milestone_completed` | Sent when the user completes a non-milestone step in a streak |
| `streak_progress_in_progress` | Sent when the user makes progress in a streak but does not reach a milestone |

### Challenge Events

| Event Code | Trigger Condition |
|---|---|
| `challenge_progress_failed` | Sent when a challenge window ends and target is not met |
| `challenge_progress_to_be_failed` | Warning reminder before a challenge window closes |
| `challenge_progress_completed` | Sent when the user completes the challenge target |
| `challenge_progress_milestone_completed` | Sent when the user reaches a milestone in a challenge |
| `challenge_progress_in_progress` | Sent when the user makes progress in a challenge |

### Mission Events

| Event Code | Trigger Condition |
|---|---|
| `mission_progress_failed` | Sent when a mission window ends and target is not met |
| `mission_progress_to_be_failed` | Warning reminder before a mission window closes |
| `mission_progress_completed` | Sent when the user completes the mission target |
| `mission_progress_milestone_completed` | Sent when the user reaches a milestone in a mission |
| `mission_progress_in_progress` | Sent when the user makes progress in a mission |

### Reward Unlocked Events

| Event Code | Trigger Condition |
|---|---|
| `streak_reward_unlocked_on_milestone_completion` | Sent when a streak reward is unlocked upon milestone completion |
| `challenge_reward_unlocked_on_milestone_completion` | Sent when a challenge reward is unlocked upon milestone completion |
| `mission_reward_unlocked_on_completion` | Sent when a mission reward is unlocked upon completing a mission |
| `mission_reward_unlocked_on_milestone_completion` | Sent when a mission reward is unlocked upon milestone completion |

---

## Real-world examples

**🛍️ E-commerce — Challenge Completed Email Notification**

Automates sending a congratulatory email via Gamopanda Email when a challenge is successfully finished:

```json
{
  "eventCode": "challenge_progress_completed",
  "templateType": "email_template",
  "templateId": "c123e456-e89b-12d3-a456-426614174000",
  "integrationProvider": "gamopanda_email",
  "integrationId": "d123e456-e89b-12d3-a456-426614174000",
  "status": "live"
}
```

**📱 Mobile App — Streak Expiry Push Notification**

Automates sending a push notification via Firebase Cloud Messaging (FCM) before a streak expires:

```json
{
  "eventCode": "streak_progress_to_be_broken",
  "templateType": "push_notification_template",
  "templateId": "e123e456-e89b-12d3-a456-426614174000",
  "integrationProvider": "firebase_cloud_messaging",
  "integrationId": "f123e456-e89b-12d3-a456-426614174000",
  "status": "live"
}
```

---

## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | CREATE · GET · LIST · UPDATE · DELETE | Full control over notification rules |
| End user | *(none)* | No access |
| Guest user | *(none)* | No access |

---

## Related resources

| Resource | Description |
|---|---|
| [Email Template](/email-template) | Template containing layout and HTML content for email notification rules |
| [Push Notification Template](/push-notification-template) | Template containing title, body, and deep link for push notification rules |
| [SMS Template](/sms-template) | Template containing message body content for SMS notification rules |
| [WhatsApp Template](/whatsapp-template) | Configured template linked to provider integrations for WhatsApp notification rules |
| [AWS WhatsApp](/aws-whatsapp) | AWS WhatsApp integration credentials and sender setup |
| [AWS SMS](/aws-sms) | AWS SMS integration credentials and sender setup |
| [Firebase Cloud Messaging](/firebase-cloud-messaging) | FCM integration credentials for push notifications |
| [Gamopanda Email](/gamopanda-email) | Gamopanda Email sender domain configuration and verification |
| [Notification Log](/notification-log) | Read-only delivery logs recording the execution history of notifications |
| [Member](/member) | The recipient of outgoing notifications |
| [Event Log](/event-log) | The source system event log that triggers notification rules |

---

## API reference

See the [API Reference](/api/notification) for full request/response schemas and interactive examples for:

- `GET /schema/notification/record` — list notifications
- `POST /schema/notification/record` — create a notification
- `GET /schema/notification/record/{id}` — get a notification by ID
- `PATCH /schema/notification/record/{id}` — update a notification
- `DELETE /schema/notification/record/{id}` — delete a notification