Customer Notifications

Levy Fleets uses push notifications to keep customers informed about their rides, account status, promotions, and important updates. This guide covers notification types, how to send manual notifications, automatic system notifications, and troubleshooting delivery issues.

Overview

The notification system uses Expo Push Notifications to deliver messages to customer mobile devices. Notifications are sent for:

• Ride-related events (start, end, issues)
• Zone alerts (entering/leaving zones)
• Payment notifications (successful charges, failed payments)
• Wallet updates (credits added)
• Promotional messages (promos, announcements)
• System alerts (maintenance, updates)
• Identity verification (required, cleared)

Notification Types

System-Generated Notifications

These are automatically triggered by events in the system:

Manual Notifications

Operators can send custom notifications to individual customers or groups:

Sending Manual Notifications

To Individual Customer

1. Navigate to Dashboard > Customers
2. Click on the customer to open their detail page
3. Click Actions (three-dot menu)
4. Select Send Notification
5. Fill in the notification form:
   • Title: Notification heading (shown bold)
   • Body: Main message text
   • Type: Category for the notification
6. Click Send

Notification Form Fields

Type Options

API Reference

Send Notification Endpoint

Endpoint: POST /api/customers/notify

Request Body:

{
  "customerId": "customer-uuid-here",
  "title": "Special Offer!",
  "body": "Get 20% off your next ride with code SAVE20",
  "type": "promo"
}

Response (Success):

{
  "success": true,
  "ticketId": "XXXX-XXXX-XXXX-XXXX"
}

Response (Failure):

{
  "success": false,
  "error": "Customer has no push token"
}

Required Parameters

Optional Parameters

Deep Linking

Notifications can include data that opens specific screens in the app:

Ride Detail

{
  "customerId": "xxx",
  "title": "Ride Complete",
  "body": "View your ride summary",
  "data": {
    "screen": "ride",
    "rideId": "ride-uuid"
  }
}

Wallet

{
  "customerId": "xxx",
  "title": "Credit Added",
  "body": "Check your new balance",
  "data": {
    "screen": "wallet"
  }
}

Identity Verification

{
  "customerId": "xxx",
  "title": "Verify Your Identity",
  "body": "Complete verification to continue riding",
  "data": {
    "screen": "identity_verification"
  }
}

Automatic Notifications

Ride Notifications

Payment Notifications

Wallet Notifications

Negative Balance Notification

Trigger Conditions:

• Wallet balance was $0 or positive before the charge
• Balance becomes negative after the charge
• Only triggered by "Charge Fee" action, not "Reduce Balance"

Notification Content:

• Title: "Wallet balance negative"
• Body: "A charge of $X.XX was applied to your account. Your wallet balance is now -$Y.YY."
• Type: wallet

Identity Notifications

Notification Settings

Customer Preferences

Customers can control notifications in the mobile app:

• All Notifications: Master toggle
• Ride Updates: Start, end, alerts
• Promotions: Marketing messages
• Payment Alerts: Transaction confirmations

Subaccount Configuration

Operators can configure notification behavior:

Push Token Management

How Tokens Work

1. Customer installs app and grants notification permission
2. App receives push token from Expo/APNs/FCM
3. Token is stored on customer record (expo_push_token)
4. Notifications sent to this token
5. Token may change (reinstall, device change)

Token Status

When Tokens Become Invalid

• Customer uninstalls the app
• Customer revokes notification permission
• Device is reset or replaced
• Token expires (rare)

Delivery Status

Expo Push Receipts

When a notification is sent, Expo provides:

1. Ticket ID: Immediate confirmation of submission
2. Receipt: Eventual delivery status

Receipt Status Values

Error Handling

Common errors and resolutions:

Best Practices

Message Content

1. Keep titles short: 30-50 characters maximum
2. Be specific: Tell customer what happened or what to do
3. Include value: Why should they care?
4. Use personalization: Include name or relevant details
5. Call to action: What should they do next?

Frequency

1. Don't over-notify: Limit promotional messages
2. Batch when possible: Combine related updates
3. Respect time zones: Send during waking hours
4. Emergency only: Reserve for truly important alerts

Timing

Tone

• Friendly: "Your ride is complete!"
• Clear: "Payment of $5.00 processed"
• Actionable: "Verify your identity to continue riding"
• Avoid: ALL CAPS, excessive punctuation, emoji overload

Bulk Notifications

Current Limitations

The dashboard currently supports individual notifications only. For bulk notifications:

1. Use the API with a loop
2. Implement rate limiting (max 400/minute to Expo)
3. Consider a separate notification campaign tool

API Bulk Pattern

// Example: Send to multiple customers
const customerIds = ['cust1', 'cust2', 'cust3'];
const message = {
  title: 'Special Offer',
  body: 'Get 20% off this weekend!'
};

for (const customerId of customerIds) {
  await fetch('/api/customers/notify', {
    method: 'POST',
    body: JSON.stringify({ customerId, ...message })
  });
  // Rate limit: wait 150ms between sends
  await new Promise(r => setTimeout(r, 150));
}

Troubleshooting

Notification not received

Check these in order:

1. Customer has push token?

   • View customer detail page
   • Check expo_push_token field
   • If empty, customer hasn't granted permission

2. Permission enabled?

   • Customer must grant notification permission in iOS/Android settings
   • They may have disabled it after initial grant

3. App installed?

   • Token becomes invalid if app is uninstalled
   • Customer needs to reinstall and re-grant permission

4. Correct customer?

   • Verify the customerId matches intended recipient
   • Check for duplicate accounts

5. Message delivered?

   • Check Expo push receipt status
   • Look for delivery errors in logs

6. Device issues?

   • Do Not Disturb mode on device
   • Focus mode blocking notifications
   • Low power mode limiting background activity

Customer says they get "too many" notifications

• Review automatic notification triggers
• Check for duplicate sends in logs
• Verify notification preferences are respected
• Consider throttling configuration

Notification shows but with wrong content

• Check for encoding issues in title/body
• Verify data isn't truncated
• Look for special characters being escaped
• Test with plain ASCII text

Notifications delayed

• Expo uses batching, may delay up to few seconds
• APNs/FCM can delay based on device/network
• Check if device is in power save mode
• Verify network connectivity on device

"DeviceNotRegistered" errors

This is normal when:

• Customer uninstalled the app
• Customer got a new device
• Token expired (rare)

Resolution: Remove invalid token from customer record. Token will be refreshed when customer opens app again.

Integration with Other Systems

Ride System

The ride engine sends notifications for:

• Ride start confirmation
• Pause/resume events
• Battery/zone warnings
• Ride completion with summary
• Auto-end notifications

Payment System

Payment processing triggers:

• Successful charge confirmation
• Failed payment alerts
• Refund notifications
• Card expiration warnings

Identity System

Identity verification triggers:

• Verification required prompt
• Verification success confirmation
• Requirement cleared notification
• Failed attempt notification