Implementing Progressive Web App (PWA) Push Notifications for Asynchronous Chat Updates

How-To-Articles
1

Implementing Progressive Web App (PWA) Push Notifications for Asynchronous Chat Updates

What This Guide Covers

  • Architecting a push notification pipeline for Genesys Cloud Web Messaging using a PWA wrapper.
  • Implementing the Web Push API and Service Workers to notify customers of agent replies when the browser tab is closed.
  • Designing a secure notification relay using Firebase Cloud Messaging (FCM) or a custom VAPID-based push server.

Prerequisites, Roles & Licensing

  • Licensing: Genesys Cloud CX 1/2/3 with Web Messaging.
  • Client Side: A PWA-enabled website (HTTPS required) with a registered Service Worker.
  • Permissions:
    • Messaging > Web Messaging > View
    • Integrations > Webhooks > Add

The Implementation Deep-Dive

1. The Strategy: The “Asynchronous Wake-Up” Call

Standard Web Messaging relies on the browser being open to receive WebSocket events. For asynchronous messaging (where replies might take hours), you need a persistent background channel.

The Architecture:

  1. The Subscription: When the customer opens the PWA chat, you prompt for notification permission. If granted, the browser generates a PushSubscription object.
  2. The Association: Send this subscription (or a unique FCM_Token) to your middleware and store it against the Genesys Guest_Session_ID in a database (e.g., Redis or DynamoDB).
  3. The Event: Configure a Genesys Cloud Webhook Integration to listen for v2.detail.events.conversation.{id}.message events.
  4. The Push: When an agent sends a message, Genesys fires the webhook. Your middleware looks up the subscription ID and triggers a push notification to the user’s device.

2. Implementing the Service Worker Listener

The Service Worker is the “heart” of the PWA that lives in the background.

The Implementation:

  • Create a service-worker.js file.
  • Register a push event listener.
  • The Workflow:
    • Receive the push payload (containing the message snippet and conversation ID).
    • Use self.registration.showNotification() to display the alert.
    • Listen for the notificationclick event to open the PWA and navigate directly to the chat interaction.
  • Architectural Reasoning: This ensures the customer stays engaged without having to keep the mobile browser tab active, significantly improving CSAT for asynchronous support.

3. Handling VAPID Authentication and Security

To prevent unauthorized parties from sending notifications to your users, you must use VAPID (Voluntary Application Server Identification).

The Implementation:

  1. Generate a VAPID Key Pair (Public and Private).
  2. The Public Key is used in the browser to initialize the subscription.
  3. The Private Key is kept on your middleware server to sign the outgoing push requests.
  4. The Trap: Payload Encryption. The Web Push protocol requires the payload to be encrypted using the keys provided by the browser in the PushSubscription. Use a library like web-push (Node.js) or pywebpush (Python) to handle the complex ECDH key exchange.

4. Deep-Linking and State Reconciliation

When a user clicks a notification, the PWA must “re-sync” with the Genesys session.

The Strategy:

  1. Include the conversationId in the push data.
  2. Upon clicking, check if the PWA is already open. If so, focus it. If not, open it.
  3. Once the UI loads, use the Web Messaging Guest SDK to re-authenticate the session.
  4. The Trick: Use the customAttributes in the initial Genesys session to store a “Re-auth Token” that allows the PWA to pull the message history instantly without waiting for a new agent assignment.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Notification Fatigue

Failure Condition: An agent sends 10 small messages in quick succession, causing the customer’s phone to buzz 10 times in a minute.
Solution: Implement Push Debouncing in your middleware. Wait 30 seconds after the first message event before sending the push. If more messages arrive, aggregate them into a single notification: “Agent Smith sent 3 new messages.”

Edge Case 2: Expired Subscriptions

Failure Condition: The browser periodically rotates the push endpoint, causing your middleware to get a 410 Gone error.
Solution: Handle the 410 error in your middleware by deleting the stale subscription from your database. The next time the user opens the PWA, perform a “Subscription Refresh” to get the new endpoint.

Edge Case 3: iOS/Safari Limitations

Failure Condition: Push notifications don’t appear on iPhones.
Root Cause: Prior to iOS 16.4, PWAs did not support Web Push.
Solution: Verify the user’s OS version. For older iOS devices, fall back to SMS/Email notifications using Genesys Cloud’s native digital channel orchestration.

Official References