Implementing Right-to-Left (RTL) Support for Arabic and Hebrew Web Messaging UIs

How-To-Articles
1

Implementing Right-to-Left (RTL) Support for Arabic and Hebrew Web Messaging UIs

What This Guide Covers

This guide details the configuration of Genesys Cloud CX Web Messaging profiles to support Right-to-Left (RTL) language orientations, specifically for Arabic and Hebrew locales. The end result is a fully localized web widget that mirrors layout directionality, aligns text correctly, and handles input field behavior without visual artifacts or encoding errors.

Prerequisites, Roles & Licensing

To implement RTL support effectively, the following infrastructure and permissions are required before configuration begins:

  • Platform: Genesys Cloud CX (Enterprise license required for Web Messaging customization).
  • Web Messaging License: Active Web Chat subscription with custom CSS injection capabilities enabled in the tenant.
  • Roles & Permissions:
    • Web Chat Admin role to modify Web Messaging profile settings.
    • Chat > Configuration > Edit permission to access widget initialization parameters.
    • API > Read/Write permissions if utilizing the Genesys Cloud API for bulk profile updates.
  • OAuth Scopes: If automating configuration via API, the following scopes are mandatory:
    • webchat:read
    • webchat:write
    • schema:read
  • External Dependencies:
    • A supported Content Delivery Network (CDN) for hosting custom CSS files if not using inline injection.
    • UTF-8 compliant font assets (e.g., Google Fonts “Cairo” or “IBM Plex Sans Arabic”) to ensure glyph rendering accuracy.

The Implementation Deep-Dive

1. Web Messaging Profile Initialization and Locale Configuration

The foundation of RTL support lies in the initialization parameters passed when loading the Genesys Cloud Web Messaging widget script. This step dictates the directionality context for the entire DOM container generated by the library.

Configuration Steps:

  1. Navigate to Admin > Contact Center > Web Chat in the Genesys Cloud Admin UI.
  2. Select the specific Web Messaging Profile intended for the target locale (Arabic or Hebrew).
  3. Access the Advanced Configuration tab within the profile settings.
  4. Locate the Widget Initialization section. This area accepts a JSON object passed to the GenesysCloud.WebChat.init function.

Production-Ready Initialization Snippet:
The following JSON payload must be injected into the initialization parameters of the Web Messaging Profile. This ensures the widget explicitly recognizes the directionality requirement during script execution.

{
  "lang": "ar-AE",
  "dir": "rtl",
  "locale": "ar_AE",
  "theme": {
    "primaryColor": "#004d99",
    "fontFamily": "Cairo, sans-serif"
  },
  "customProperties": {
    "encoding": "UTF-8",
    "textDirection": "rtl"
  }
}

The Trap:
A common misconfiguration occurs when developers rely solely on the lang attribute (e.g., lang="ar") to trigger RTL behavior. The Genesys Cloud Web Chat library defaults to Left-to-Right (LTR) directionality regardless of the language code unless the dir property is explicitly set to "rtl".

Catastrophic Downstream Effect:
If dir is omitted, the text content will appear correctly typed, but the container layout will remain anchored to the left side. Input cursors will start at the visual right, but logical flow remains LTR. This results in a disjointed user experience where users type Arabic text that visually aligns left while the cursor moves right, causing confusion and abandonment of the chat session. Additionally, system-generated messages (e.g., “Welcome to support”) may appear reversed or misaligned relative to user input fields.

Architectural Reasoning:
We enforce an explicit dir override because the browser’s default locale detection is often unreliable in embedded widget contexts where the parent page language differs from the chat container context. By hardcoding this in the initialization object, we decouple the widget directionality from the host application’s HTML lang attribute, ensuring consistent behavior across all customer environments.

2. CSS Styling and Logical Properties Injection

Once the widget is initialized with RTL directionality, the default styling provided by Genesys Cloud may not account for logical layout requirements. Standard CSS physical properties (e.g., margin-left, padding-right) break when the content flow flips. You must inject custom CSS to enforce logical alignment.

Configuration Steps:

  1. Navigate to Admin > Contact Center > Web Chat.
  2. Select the target profile and scroll to the Custom CSS section.
  3. Add the following stylesheet rules to override default physical properties with logical equivalents.

Production-Ready Custom CSS:

/* Force container alignment for RTL */
.gm-container {
  direction: rtl;
  text-align: right;
}

/* Logical margins replace physical margins */
.chat-bubble__user {
  margin-inline-start: 8px; /* Replaces margin-right in LTR context */
  margin-inline-end: auto;
}

.chat-bubble__agent {
  margin-inline-end: 8px; /* Replaces margin-left in LTR context */
  margin-inline-start: auto;
}

/* Icon orientation adjustments */
.icon-chevron-down {
  transform: scaleX(-1); /* Flip chevron icons for RTL flow */
}

/* Input field cursor alignment */
.chat-input__field {
  text-align: right;
  direction: rtl;
}

The Trap:
Engineers frequently copy-paste LTR CSS rules and attempt to fix them by manually swapping left and right in the property names (e.g., changing margin-left to margin-right). This approach is fragile and prone to errors during future updates.

Catastrophic Downstream Effect:
When a new version of the Genesys Web Chat library releases, it may change the DOM structure or class naming conventions. Manually swapped properties do not adapt to logical flow changes automatically. If the widget updates its internal flexbox direction, the manually swapped physical margins will cause overlap issues, causing messages to stack incorrectly or buttons to become unclickable due to hidden elements behind the viewport edge.

Architectural Reasoning:
We utilize CSS Logical Properties (e.g., margin-inline-start) instead of Physical Properties (margin-left). This approach ties layout constraints to the flow direction rather than screen coordinates. When dir="rtl" is set, inline-start resolves to the right side automatically. This ensures that if the browser language setting changes dynamically or if the widget re-renders, the layout remains consistent without code modifications. This is critical for global enterprises where a single profile might serve multiple regional endpoints with varying user preferences.

3. Character Encoding and Font Rendering

Proper glyph rendering requires explicit declaration of UTF-8 encoding in the HTML document hosting the widget and selection of appropriate font families that support Arabic or Hebrew glyphs. Genesys Cloud defaults to standard sans-serif fonts which often lack ligatures required for cursive Arabic scripts.

Configuration Steps:

  1. Ensure the host webpage containing the chat widget link sets the charset explicitly.
  2. Inject a <link> tag in the head of the host page to load specialized web fonts.
  3. Update the fontFamily parameter in the Web Messaging Profile initialization (as shown in Step 1) to prioritize these fonts.

Production-Ready HTML Injection:
Add this snippet to the <head> section of every page utilizing the chat widget:

<meta charset="UTF-8">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Cairo:wght@400;700&family=IBM+Plex+Sans+Hebrew&display=swap" rel="stylesheet">

The Trap:
Organizations often assume that modern browsers handle font fallback automatically for Arabic scripts. However, without explicit font family declarations, the browser may render text using a system default sans-serif font (like Arial) which lacks specific diacritical marks required for accurate Arabic pronunciation and Hebrew vowel points (nikkud).

Catastrophic Downstream Effect:
Users will see broken or missing glyphs where vowels should appear. In Hebrew, this renders the text as a sequence of consonants that may be unrecognizable to the average reader. In Arabic, missing diacritics can change word meanings entirely, leading to customer support misunderstandings regarding product names or service details. This creates a trust deficit immediately upon session start.

Architectural Reasoning:
We enforce explicit font loading via Google Fonts (or a self-hosted CDN) because system fonts vary significantly by operating system and region. A Windows user in Riyadh may have different default fonts than a Mac user in Tel Aviv. By forcing a specific web font that includes the necessary OpenType features for Arabic ligatures and Hebrew vowel points, we guarantee a consistent typographic experience regardless of the client device’s OS configuration. This reduces support tickets related to “broken text” by standardizing the rendering engine input.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Mixed LTR/RTL Content in Input Fields

The Failure Condition:
A customer types a phone number or a URL (e.g., +1-555-0199 or www.example.com) within an Arabic text message. The cursor jumps to the wrong side of the numbers, making editing difficult.

The Root Cause:
The Genesys Cloud Web Messaging engine attempts to auto-detect directionality for individual words. However, standard Latin numerals and symbols are treated as LTR by default even within an RTL context. If the CSS does not explicitly handle bidirectional text isolation, these segments break the flow.

The Solution:
Implement the unicode-bidi CSS property on the input field container to isolate bidirectional text blocks. Add the following rule to your custom CSS:

.chat-input__field {
  unicode-bidi: embed; /* Isolates LTR numbers from RTL text */
}

This ensures that when a user types an English phone number inside an Arabic message, the cursor remains logical to the surrounding text flow rather than jumping abruptly.

Edge Case 2: Agent Desktop Rendering Mismatch

The Failure Condition:
The customer sees the chat interface correctly aligned in RTL, but the agent viewing the conversation on their desktop sees the history reversed or misaligned.

The Root Cause:
This discrepancy often arises from the Genesys Cloud Architect flow logic. If a message is tagged with an LTR locale code during transfer (e.g., via a custom property in the conversation object), the agent’s view may revert to LTR rendering based on the agent’s language preference settings rather than the customer’s context.

The Solution:
Ensure that when routing the chat to an agent, the conversation metadata includes the directionality flag explicitly. If using the Genesys Cloud API to transfer conversations, include direction in the payload:

{
  "conversationId": "01234567-89ab-cdef-0123-456789abcdef",
  "direction": "rtl"
}

Additionally, verify that the Agent Desktop layout settings allow for dynamic text direction overrides based on conversation locale.

Edge Case 3: File Upload Icon Orientation

The Failure Condition:
The upload button icon (usually a paperclip or arrow) appears mirrored incorrectly, pointing in the wrong direction relative to the input field.

The Root Cause:
Genesys Cloud default icons are vector assets designed for LTR orientation. When the widget flips the layout, these icons do not automatically reflect horizontally unless explicitly styled.

The Solution:
Target the specific icon class within the custom CSS and apply a horizontal transform. Use the transform: scaleX(-1) property on the upload button container to mirror the icon visually without affecting the text direction logic. This maintains logical flow while correcting visual orientation cues for the user.

Official References