# Push Notification Segment Rules

This document defines the segment-rule behavior used by Push Notification V1 and Push Notification V2.

## Applies To

- Push Notification V1
- Push Notification V2

## Audience Resolution Order

1. Try Elasticsearch first for supported segment rules.
2. Fall back to PostgreSQL when Elasticsearch is disabled, not configured, not responding, or the rule is not supported by the Elasticsearch audience resolver.

## Segment Matching Logic

- Rules inside one segment are matched with `AND`.
- Multiple selected segments are matched with `OR`.
- Final notification delivery still depends on valid device-token resolution during send processing.

## Supported Rule Definitions

### 1. Active Subscribed

Rule label:
- `Subscription Status` -> `Active Subscribed`

Canonical value:
- `subscriber`

Logic:
- `tbl_customer_subscriptions.status = 2`
- `tbl_customer_subscriptions.start_date <= now()`
- `tbl_customer_subscriptions.end_date >= now()`

### 2. UnSubscribed

Rule label:
- `Subscription Status` -> `UnSubscribed`

Canonical value:
- `unsubscribed`

Logic:
- No row exists in `tbl_customer_subscriptions` for the customer and app.

### 3. Cancelled

Rule label:
- `Subscription Status` -> `Cancelled`

Canonical value:
- `cancelled`

Logic:
- `tbl_customer_subscriptions.status = 3`

Accepted legacy aliases normalized to `cancelled`:
- `canceled`
- `cancel`
- `cancle`
- `unsubscriber`

### 4. Expired

Rule label:
- `Subscription Status` -> `Expired`

Canonical value:
- `expired`

Logic:
- `tbl_customer_subscriptions.status = 7`

Accepted legacy alias normalized to `expired`:
- `expire`

### 5. Guest User

Rule label:
- `User Type` -> `Guest User`

Canonical value:
- `guest`

Logic:
- `customers.email_id` is empty or null
- `customers.phone_number` is empty or null
- Matching active device exists in `customer_devices`

Device requirements:
- Match by `customer_devices.sms_cust_id = customers.sms_cust_id`
- `customer_devices.push_device_token` must be present and non-empty
- `customer_devices.status = 1` when the `status` column exists
- `customer_devices.app_id = current app_id` when the `app_id` column exists

## Device Token Source

Push notification delivery uses device tokens from:

- Table: `customer_devices`
- Column: `push_device_token`
- Join key: `sms_cust_id`

For guest users, this device-token check is part of the rule logic in PostgreSQL and is still enforced during final recipient/device resolution before sending.

## Elasticsearch Support

Elasticsearch-first audience resolution currently supports these rule types:

- `subscription_type`
- `user_type`
- `customer_status`
- `email`

If a segment contains unsupported rule types, the audience resolver falls back to PostgreSQL.

Current examples of PostgreSQL-fallback rule types:

- `gender`
- `age`
- `contact_number`

## Notes

- Elasticsearch results are filtered back through the `customers` table to stay aligned with the legacy PostgreSQL audience path.
- Guest-user Elasticsearch matching checks for missing `email_id` and `phone_number`, while active device-token enforcement is still guaranteed before send dispatch.