Building Custom Chat UI Extensions for Web Messaging using the Messaging SDK

How-To-Articles
1

Building Custom Chat UI Extensions for Web Messaging using the Messaging SDK

What This Guide Covers

This masterclass details the advanced customization of the Genesys Cloud Web Messaging experience. By the end of this guide, you will be able to use the Messenger JavaScript SDK to build custom UI components-such as dynamic banners, “Mini-Apps” inside the chat window, and proactive status updates-that go beyond the standard CSS styling options provided in the Admin UI. This is critical for brands that want to provide a “Native” look-and-feel that aligns perfectly with their own web applications.

Prerequisites, Roles & Licensing

Customizing the messaging UI requires frontend development skills and access to the Genesys Cloud deployment settings.

  • Licensing: Genesys Cloud CX 1, 2, or 3.
  • Permissions:
    • Messaging > Deployment > View/Edit
    • Architect > Flow > View/Edit
  • Developer Tools: Familiarity with JavaScript, HTML, and CSS.
  • Infrastructure: A provisioned Web Messaging Deployment with the Messenger snippet installed on your site.

The Implementation Deep-Dive

1. Initializing the Messenger SDK Commands

The Messenger SDK provides a “Command/Event” architecture. Instead of modifying the core Genesys iframe (which is restricted), you “talk” to it using the Genesys global function.

Implementation Pattern:
You must wait for the Messenger.ready event before firing commands.

Genesys("subscribe", "Messenger.ready", function() {
  console.log("Messenger is ready for custom extensions.");
});

2. Building a “Mini-App” using Custom Attributes

One of the most powerful features is the ability to send and receive Custom Attributes between the website and the Architect flow.

Scenario:
You want to show a “Tracking Progress” bar inside the chat window when a user asks about their order status.

Implementation Steps:

  1. Architect Flow: The bot fetches the order status via a Data Action and sets a Participant Attribute Task.OrderStatus = "In-Progress".
  2. Website Listener: The SDK listens for the MessagingService.messagesReceived event.
  3. UI Injection: If the message contains the OrderStatus attribute, your website triggers a local DOM update to display a progress bar overlaying the chat widget.
Genesys("subscribe", "MessagingService.messagesReceived", function(data) {
  const status = data.messages[0].metadata.customAttributes.OrderStatus;
  if (status) {
    updateLocalProgressBar(status);
  }
});

3. Implementing “On-Page” Proactive Banners

Instead of a generic “Chat with us” invitation, you can use the SDK to display dynamic banners on your site that directly correlate to the chat state.

Architectural Reasoning:
If a customer is already in a chat, do not show them a “New Chat” invitation. Use the Messenger.opened and Messenger.closed events to toggle the visibility of other support elements on your page (like a phone number or a static FAQ link) to reduce channel confusion.

4. Customizing the “Launcher” Button

The standard Genesys launcher (the floating bubble) may not fit your design. You can hide the default launcher in the Admin UI and build your own.

Implementation Step:
Use the Messenger.open command to trigger the chat window from any element on your page (e.g., a “Contact Support” button in your footer).

document.getElementById('my-custom-chat-button').onclick = function() {
  Genesys("command", "Messenger.open");
};

Validation, Edge Cases & Troubleshooting

Edge Case 1: State Persistence across Subdomains

  • The failure condition: A customer starts a chat on shop.example.com but the chat disappears when they move to billing.example.com.
  • The root cause: The Messenger cookie is scoped to the subdomain by default.
  • The solution: In your deployment configuration, set the cookieDomain to the root domain (e.g., example.com). This ensures the deploymentId and conversationId persist as the user traverses your entire ecosystem.

Edge Case 2: Mobile Browser “Viewport” Issues

  • The failure condition: The custom UI extension looks perfect on desktop but covers the text input field on mobile devices.
  • The root cause: Inconsistent handling of the “Virtual Keyboard” in mobile browsers.
  • The solution: Use the MessagingService.opened event to add a no-scroll class to the body and adjust your custom component’s z-index and height based on the window.visualViewport API.

Official References