> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zixflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Communication Channels Overview

> Available communication channels and when to use each.

Overview of available communication channels in the Zixflow event system, their capabilities, delivery mechanisms, and when to use each channel. Currently implemented: Push notifications. Future channels documented for reference only.

***

## What are Communication Channels?

Communication channels are the different ways you can reach your users to deliver messages, notifications, or content. Each channel has unique characteristics, delivery mechanisms, and use cases.

Think of channels as the **delivery methods** for your messages — like choosing between calling someone, texting them, emailing them, or knocking on their door. Each method works differently and is appropriate for different situations.

### The Simple Definition

A communication channel is a **pathway** through which you send messages from your product to your users.

**Examples:**

* **Push notifications**: Alert that appears on their phone lock screen
* **Email**: Message delivered to their inbox
* **In-app messages**: Banner or modal that appears while they're using your app
* **SMS**: Text message to their phone number

### Why Multiple Channels Matter

Different channels excel at different things:

1. **Urgency varies**: Push for "Your order shipped!" (immediate), Email for "Here's our monthly newsletter" (can wait)
2. **Content complexity differs**: Email can include rich HTML and images, Push has 1-2 lines of text
3. **User availability changes**: In-app messages reach active users, Email reaches everyone (even if they haven't opened your app in weeks)
4. **Permission requirements differ**: Push requires explicit permission, Email just needs an email address
5. **Engagement patterns vary**: Some users check email religiously, others ignore it but always tap push notifications

### How Channels Work Together

Smart messaging uses multiple channels in coordination:

**Example: Abandoned cart recovery**

1. **1 hour later**: In-app message (if they're still browsing)
2. **3 hours later**: Push notification (quick reminder)
3. **24 hours later**: Email (detailed reminder with product images)
4. **3 days later**: SMS (final urgent reminder with discount code)

Each channel plays to its strengths: in-app for immediate context, push for quick attention, email for rich content, SMS for urgent final appeal.

### Channel Characteristics to Consider

**Reach**: How many users can you message?

* Email: Nearly universal (most users provide email)
* Push: Requires app install + permission (50-70% grant rate)
* In-app: Only active users (subset of total users)
* SMS: Requires phone number + explicit opt-in (5-20% typically)

**Speed**: How fast does message arrive?

* Push: \<5 seconds (real-time)
* SMS: \<10 seconds (near real-time)
* In-app: Instant (but only when app is open)
* Email: \<1 minute (but users check infrequently)

**Visibility**: How likely are they to see it?

* Push: Very high (lock screen, notification badge)
* SMS: Very high (most people read texts immediately)
* In-app: High (if they're actively using app)
* Email: Medium-low (cluttered inboxes, spam filters)

**Cost**: What does each message cost?

* Push: Free (after platform fees)
* Email: \~$0.0001 - $0.001 per email
* In-app: Free
* SMS: \~$0.01 - $0.05 per message

**Content richness**: How much can you say?

* Email: Unlimited (HTML, images, videos, buttons)
* In-app: High (full app UI capabilities)
* Push: Low (1-2 lines of text, maybe image)
* SMS: Very low (160 characters, plain text)

### Choosing the Right Channel

Ask yourself:

1. **How urgent is this message?**
   * Critical/immediate → Push or SMS
   * Important but not urgent → Email
   * FYI/nice-to-have → In-app

2. **How much information do I need to convey?**
   * Quick alert → Push or SMS
   * Detailed explanation → Email
   * Interactive experience → In-app

3. **Where is the user right now?**
   * In the app → In-app message
   * Away from app → Push or Email
   * Unknown → Email (reaches everyone)

4. **What action do I want them to take?**
   * Immediate action → Push (tap to open app)
   * Considered decision → Email (read details, think, decide)
   * In-app behavior → In-app message ("Try this feature")

***

## Available Channels

### Channel Opt-Out Model

Every user profile stores an opt-out status for each channel. The system uses three states:

| Status          | Value | Meaning                                                                  |
| --------------- | ----- | ------------------------------------------------------------------------ |
| `NOT_OPTED_OUT` | 1     | User is reachable on this channel (default for Push, SMS, WhatsApp, RCS) |
| `OPTED_OUT`     | 2     | User explicitly opted out — all sends suppressed                         |
| `UNKNOWN`       | 3     | Intent not yet established (default for Email — pending confirmation)    |

Each channel also stores an `_opt_out_at` timestamp recording when the opt-out occurred.

**Setting opt-out status via SDK:**

```dart theme={null}
// User opts out of SMS
Zixflow.instance.setProfileAttributes({
  'sms_opt_out': 2,        // OPTED_OUT
  'sms_opt_out_at': DateTime.now().toIso8601String(),
});

// User opts back in to push
Zixflow.instance.setProfileAttributes({
  'push_opt_out': 1,       // NOT_OPTED_OUT
});
```

**User Suppression** (blocks ALL channels at once):

```dart theme={null}
// Triggered server-side via lifecycle event "User Suppressed"
// Sets is_suppressed = true on the profile — no outbound messages of any kind
// Reversed by "User Unsuppressed" lifecycle event
```

See [User Preferences & Consent](/documentation/events/user-preferences) for full preference management.

***

### 1. **Push Notifications** ✅ IMPLEMENTED

**Platform:** Mobile apps (iOS, Android)
**Delivery:** Apple Push Notification service (APNs) and Firebase Cloud Messaging (FCM)
**Latency:** \<5 seconds (real-time)
**Opt-in required:** Yes (system permission dialog)
**Opt-out field:** `push_opt_out` (default: `NOT_OPTED_OUT`)

**What's implemented:**

* ✅ Device token registration (`profile_devices` table)
* ✅ Multi-device support (one user = N tokens)
* ✅ Platform routing (iOS via APNs, Android via FCM)
* ✅ `push_opt_out` / `push_opt_out_at` fields on user profile
* ✅ Deep linking support

**When to use:**

* Time-sensitive transactional alerts (order shipped, payment failed)
* Re-engagement (dormant users, abandoned cart)
* Real-time updates (price drop, new message)

***

### 2. **Email**

**Platform:** Universal (all devices with email client)
**Delivery:** SMTP via SendGrid/AWS SES (planned)
**Latency:** \<1 minute
**Opt-in required:** Yes (CAN-SPAM, GDPR compliance)
**Opt-out field:** `email_opt_out` (default: `UNKNOWN` — email defaults to pending confirmation unlike other channels)

**When to use:**

* Complex onboarding sequences
* Transactional receipts (order confirmations, invoices)
* Newsletters and product updates

**Not yet available.** The `email_opt_out` / `email_opt_out_at` fields are already stored on user profiles.

***

### 3. **SMS**

**Platform:** Mobile phones (all devices)
**Delivery:** Twilio/AWS SNS (planned)
**Latency:** \<10 seconds
**Opt-in required:** Yes (TCPA compliance in US)
**Opt-out field:** `sms_opt_out` (default: `NOT_OPTED_OUT`)

**When to use:**

* Critical alerts (fraud detection, account security)
* Two-factor authentication codes
* Time-sensitive transactions (delivery today, pickup ready)

**Not yet available.** The `sms_opt_out` / `sms_opt_out_at` fields are already stored on user profiles in preparation for SMS delivery.

***

### 4. **In-App Messages**

**Platform:** Mobile apps (while app is open)
**Delivery:** SDK renders message in-app
**Latency:** Real-time (no server delay)
**Opt-in required:** No (native to app experience)

**When to use:**

* Feature announcements (new feature available on this screen)
* Tooltips/onboarding (guide users through workflows)
* Upsell prompts (hit paywall → show upgrade modal)

**Not yet available.**

***

### 5. **WhatsApp**

**Opt-out field:** `whatsapp_opt_out` (default: `NOT_OPTED_OUT`)

**Not yet available.** The `whatsapp_opt_out` / `whatsapp_opt_out_at` fields are already stored on user profiles.

***

### 6. **RCS (Rich Communication Services)**

**Opt-out field:** `rcs_opt_out` (default: `NOT_OPTED_OUT`)

**Not yet available.** The `rcs_opt_out` / `rcs_opt_out_at` fields are already stored on user profiles.

***

### 7. **Web Push**

**Platform:** Web browsers (Chrome, Firefox, Safari 16+)
**Delivery:** Browser Push API
**Latency:** \<5 seconds
**Opt-in required:** Yes (browser permission)

**Not yet available.**

***

## Channel Selection Matrix

| Use Case              | Best Channel | Backup Channel | Rationale                                      |
| --------------------- | ------------ | -------------- | ---------------------------------------------- |
| Order shipped         | Push         | Email          | Real-time + tracking link                      |
| Cart abandoned (2h)   | Push         | Email          | Immediate reminder while intent is high        |
| Cart abandoned (24h)  | Email        | Push           | Longer content, include product images         |
| Password reset        | Push + Email | SMS            | Both for redundancy, SMS for critical security |
| Weekly newsletter     | Email        | N/A            | Rich content, not time-sensitive               |
| Flash sale (4 hours)  | Push         | SMS            | Urgency + broad reach                          |
| Feature announcement  | In-App       | Push           | Contextual (show when user would use it)       |
| Payment failed        | Email        | Push           | Important, needs resolution steps (complex)    |
| Trial ending (3 days) | Email        | Push           | Detailed upgrade info, pricing comparison      |
| User inactive 14 days | Push         | Email          | Re-engage quickly, low friction                |

***

## Multi-Channel Orchestration

### Sequential Delivery

**Use case:** Maximize reach by trying multiple channels

```yaml theme={null}
Campaign: Cart Abandonment Recovery
Step 1 (2 hours after cart add):
  Channel: Push
  Fallback: If push not delivered within 10 minutes → Send Email
  
Step 2 (24 hours):
  Channel: Email
  Condition: If no Order Completed
  
Step 3 (72 hours):
  Channel: Push + Email
  Condition: If no Order Completed
  Offer: 15% discount
```

**Implementation note:** Multi-channel orchestration not yet built. Currently push-only.

***

### Preference-Based Routing

**Use case:** Respect user's channel preferences

```javascript theme={null}
// User sets preferences
setProfileAttributes({
  notification_preferences: {
    transactional: ['push', 'email'],     // Send both
    promotional: ['email'],                // Email only
    product_updates: ['push']              // Push only
  }
});

// Campaign respects preferences
Campaign: Product Launch
Category: product_updates
→ System checks user preferences
→ Sends via 'push' only (per user preference)
```

**Implementation note:** Preference management not yet built.

***

### Channel Suppression

**Use case:** Don't send via channel if user recently engaged elsewhere

```
User receives Order Shipped email at 10:00 AM
User opens email at 10:05 AM
→ Suppress push notification scheduled for 10:10 AM
   (User already engaged, no need for redundant push)
```

**Implementation note:** Cross-channel suppression not yet built.

***

## Performance Benchmarks

### Industry Averages (2026)

**Push Notifications:**

* Permission grant rate: 60% (iOS), 80% (Android)
* Delivery rate: 95% (devices online within 7 days)
* Open rate: 5-10% (promotional), 15-25% (transactional)
* Click-through rate: 40-60% of opens

**Email:**

* Deliverability rate: 95% (excluding bounces)
* Open rate: 15-25% (promotional), 30-50% (transactional)
* Click-through rate: 2-5% (promotional), 10-20% (transactional)
* Unsubscribe rate: 0.1-0.5% per send

**SMS:**

* Delivery rate: 98%
* Open rate: 98% (within 3 minutes)
* Click-through rate: 15-30%
* Opt-out rate: 1-3% per send

**In-App Messages:**

* Display rate: 100% (if conditions met)
* Dismissal rate: 30-50% (without action)
* Action rate: 5-15% (click CTA)

***

## Cost Comparison

| Channel  | Cost per Message | Monthly Cost (100k users) | Notes                            |
| -------- | ---------------- | ------------------------- | -------------------------------- |
| Push     | \$0              | \$0                       | Free (only infrastructure costs) |
| Email    | \$0.0001-0.001   | \$10-100                  | Volume pricing, SendGrid/SES     |
| SMS      | \$0.01-0.05      | \$1,000-5,000             | Expensive, use sparingly         |
| In-App   | \$0              | \$0                       | Free (part of app)               |
| Web Push | \$0.0001         | \$10                      | Browser infrastructure costs     |

**ROI considerations:**

* Push: Highest ROI for mobile apps (free + high engagement)
* Email: Best for complex content, nurture campaigns
* SMS: Reserve for high-value conversions (abandoned cart \$500+)
* In-App: Best for onboarding, feature adoption

***

## Channel-Specific Best Practices

### Push Notifications

✅ **Do:**

* Request permission after showing value
* Personalize with user's name, behavior
* Use emojis sparingly (draws attention)
* Include clear CTA and deep link
* Respect quiet hours (9am-9pm)

❌ **Don't:**

* Ask for permission on first app launch
* Send generic messages ("Check out our app!")
* Spam multiple pushes per hour
* Send promotional pushes at 3am
* Ignore user preferences

***

### Email (When Implemented)

✅ **Do:**

* Use responsive design (mobile-first)
* Include plain-text version (accessibility + spam filters)
* Test subject lines (A/B test 2-3 variants)
* Personalize beyond "Hi {{first_name}}"
* Include unsubscribe link (legal requirement)

❌ **Don't:**

* Use "no-reply@" sender address
* Embed only images (triggers spam filters)
* Send from inconsistent sender names
* Forget mobile optimization
* Ignore bounce rates (clean list regularly)

***

### SMS (When Implemented)

✅ **Do:**

* Get explicit opt-in (double opt-in recommended)
* Include brand name in message
* Provide opt-out instructions (reply STOP)
* Keep under 160 characters
* Use for high-value, time-sensitive messages

❌ **Don't:**

* Send without explicit consent
* Use URL shorteners (looks spammy)
* Send at night (respects quiet hours even more than push)
* Forget to register shortcode/long code
* Ignore opt-outs (legal violation)

***

## Implementation Status Summary

**Opt-out fields currently stored on every user profile:**

| Channel  | Field                                      | Default         |
| -------- | ------------------------------------------ | --------------- |
| Email    | `email_opt_out` / `email_opt_out_at`       | `UNKNOWN`       |
| SMS      | `sms_opt_out` / `sms_opt_out_at`           | `NOT_OPTED_OUT` |
| WhatsApp | `whatsapp_opt_out` / `whatsapp_opt_out_at` | `NOT_OPTED_OUT` |
| RCS      | `rcs_opt_out` / `rcs_opt_out_at`           | `NOT_OPTED_OUT` |
| Push     | `push_opt_out` / `push_opt_out_at`         | `NOT_OPTED_OUT` |

**Delivery currently available:**

* ✅ Push Notifications (mobile — iOS/Android)

**Delivery planned:**

* ⏳ Email (planned Q3 2026)
* ⏳ SMS (planned Q4 2026)
* ⏳ WhatsApp (2027)
* ⏳ RCS (2027)
* ⏳ In-App Messages (2027)
* ⏳ Web Push (2027)

***

**Next:** How users manage their communication preferences → [User Preferences & Consent](/documentation/events/user-preferences)