After an administrator configures the messaging Web Widget in Admin Center and a developer adds it to your website, you can work together to further customize the widget’s behavior and experience. This cookbook gives an overview of what’s possible with the messaging Web Widget and includes recipes. For detailed implementation and additional code samples, seeWeb Widgetin our developer documentation.

Verified AI summary ◀▼

Customize the messaging Web Widget to enhance customer interactions on your website. Configure options like widget language, multi-conversations, and color themes. Control widget visibility, position, and embedded mode for seamless integration. Collaborate with developers to implement changes using JavaScript APIs, ensuring the widget fits your specific needs and improves user experience across different pages and devices.

After an administrator configures the messaging Web Widget in Admin Center and a developer adds it to your website, you can work together to further customize the widget’s behavior and experience. This cookbook gives an overview of what’s possible with the messaging Web Widget and includes recipes. For detailed implementation and additional code samples, see Web Widget in our developer documentation.

Note: This article applies to accounts using the messaging Web Widget. If you’re using Web Widget (Classic), see Advanced customization of Web Widget (Classic).

This article contains the following topics:

  • Planning for customizing the messaging Web Widget
  • Opening and closing the widget
  • Displaying the widget in a different language
  • Configuring multi-conversations
  • Repositioning the launcher
  • Customizing the color of the widget elements
  • Changing visible ordering in the widget
  • Displaying the widget in embedded mode

Planning for customizing the messaging Web Widget

Most Zendesk administrators aren’t web developers and work with a developer to implement customizations to the messaging Web Widget. Typically, an administrator configures messaging settings in Admin Center, while a developer updates the website code to control widget behavior using the messaging Web Widget JavaScript APIs. For example, the APIs can change when the widget shows or when it opens.

Even if a developer handles the implementation, administrators still play an important role of understanding what’s possible and clearly communicating the desired experience.

Customizing the messaging Web Widget usually involves the following steps:

  1. Review this cookbook to understand what some customization options are available.
  2. Meet with stakeholders to define requirements for the widget experience. For example, when it should appear, where it should be placed, whether to use a custom launcher, and whether to authenticate users.
  3. Create a specific list of desired changes and include links to any relevant developer documentation your developer can reference.
  4. Have your developer implement the changes by updating your website's HTML and JavaScript (and CSS for positioning the launcher or styling any custom launcher button), then test the experience across key pages and devices. The messaging Web Widget renders inside an iframe added to the page, so site CSS can help with positioning, but can't style the widget UI itself.
Note: This article includes several JavaScript examples. Place them after your messaging Web Widget code so zE is available. 
<!-- Messaging Web Widget -->
<script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=YOUR_KEY"></script>

<!-- After the Web Widget code -->
<script>
  zE("messenger:set", "locale", "es");
</script>
If your site loads the widget in the background (for example, a single-page app that loads scripts after the initial render), make sure the widget is fully loaded before calling zE(...).

Opening and closing the widget

You can control when the messaging window and launcher are available and when they open. This is useful if you want the launcher visible only on certain pages, or if you want to open messaging in response to a user action, like clicking a Help button. The launcher is the small button (usually in the bottom corner) that users click to start messaging. The messaging window is the expanded chat interface that opens after the user clicks the launcher. Available API properties:
  • show and hide controls whether the launcher is visible.
  • open and close controls whether the messaging window is expanded.

Hiding the launcher doesn't prevent you from opening the messaging window using zE("messenger", "open").

Controlling the launcher visibility:
zE("messenger", "show"); // show launcher
zE("messenger", "hide"); // hide launcher
Controlling the messaging window state:
zE("messenger", "open");  // open messaging window
zE("messenger", "close"); // close messaging window
Example custom Help button that shows the launcher and opens the messaging window:
<button id="help-button" type="button">Help</button>
<script>
  document.getElementById("help-button").onclick = function () {
    zE("messenger", "show"); // ensure launcher is available
    zE("messenger", "open"); // open messaging window
  };
</script>

For more information, see Displaying the messaging Web Widget.

Displaying the widget in a different language

By default, the messaging Web Widget uses the end user’s browser language. To override this behavior (for example, to match a language selector on your site), set the locale at runtime by placing this code immediately after the Web Widget embed script. If your site loads the widget asynchronously (for example, in a single-page application), run this as soon as zE is available and before you call other messaging Web Widget commands.

<!-- Messaging Web Widget snippet -->
<script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=YOUR_KEY"></script>

<!-- Immediately after the snippet -->
<script>
  zE("messenger:set", "locale", "es");
</script>

For a list of supported locales and locale codes, see https://support.zendesk.com/api/v2/locales/public.json. For more information on setting the locale, see Set locale.

Configuring multi-conversations

Multi-conversations lets end users have more than one active conversation with your organization at the same time (for example, separate threads for different issues). To use multi-conversations, a Zendesk admin must enable it and your account must have access to Sunshine Conversations. For information, see Configuring multi-conversations.

If you use authentication, authenticate users before showing the launcher. Delaying authentication can result in anonymous conversations and make it harder for users to access prior conversations. For example:

zE("messenger", "hide");

zE("messenger", "loginUser", function (callback) {
  callback("new-jwt-for-user");
}, function (error) {
  if (error) return;
  zE("messenger", "show");
});

If you have access to the Sunshine Conversations UpdateConversation endpoint, you can set a custom title and avatar for each conversation. Updates aren’t reflected immediately in the user’s current messaging screen; they appear the next time the user reloads the messaging UI. 

{
  "displayName": "My conversation",
  "iconUrl": "https://www.someplace.com/image.jpg"
}

Users can switch between threads using a conversation list screen. If you want to show a single-conversation interface, Sunshine Conversations supports a canUserSeeConversationList setting to hide the conversation list and show only the most recently updated conversation.

{
  "canUserSeeConversationList": false
}

Repositioning the launcher

By default, the messaging Web Widget launcher appears in the bottom-right corner of the browser. To move the launcher, use one of these approaches:

  • CSS positioning (recommended for simple moves): Adjust the launcher’s placement by targeting the widget element (often an iframe) and updating left, right, and bottom offsets. Use browser DevTools to inspect the widget iframe and container and adjust the selector if needed.
  • Custom launcher button (recommended for full control): Hide the default launcher and place your own “Help” button anywhere in your layout, then open the widget programmatically.

Example: Moving the default launcher using CSS

This example moves the default launcher to the bottom left corner using CSS.
/* Move the Zendesk messaging Web Widget launcher to the bottom left */
/* Use your browser's DevTools to find the widget iframe and adjust the selector as needed */
iframe[title*="Zendesk"],
iframe[aria-label*="Zendesk"] {
  right: auto !important;
  left: 24px !important;
  bottom: 24px !important;
}
Note: The messaging Web Widget may add multiple iframes to the page. For example, the launcher and the conversation window. If your CSS affects more than the launcher, narrow your selector to the specific iframe or container you want to reposition.

Example: Hiding the default launcher and using a custom Help button

This example shows how to use your own Help button as the only entry point to messaging. In Admin Center, configure a custom launcher so the default launcher isn’t shown. In your site code, call zE("messenger","hide") to ensure the default launcher stays hidden. If you use authenticated messaging (JWT), authenticate the user before calling open().

zE("messenger","hide")

document.getElementById("help-button").onclick = function () {
  zE("messenger", "open");
};

Example: Using a custom Help button and keeping the default launcher available

This example shows how to use a Help button to open messaging while still allowing the default launcher to appear after authentication succeeds (for example, so users can reopen messaging later without navigating back to your Help button). If authentication fails, the Help button opens the widget anonymously.

zE("messenger", "hide");

let authSucceeded = false;

zE("messenger", "loginUser", function (callback) {
  // Fetch or provide a JWT for the signed-in user
  callback("new-jwt-for-user");
}, function (error) {
  if (error) {
    // Auth failed — user can still open messaging anonymously via the Help button
    return;
  }
  authSucceeded = true;
  zE("messenger", "show"); // show launcher after successful auth
});

document.getElementById("help-button").onclick = function () {
  // If auth didn't succeed (or hasn't completed yet), open anonymously
  if (!authSucceeded) {
    zE("messenger", "show");
  }
  zE("messenger", "open");
};

Customizing the color of the widget elements

You can configure the overall color scheme for the messaging Web Widget, including launcher styling and brand colors from Admin Center. See Configuring the name and appearance of the Web Widget.

If you need more control over individual UI elements, you can customize widget colors at runtime using JavaScript. The messaging Web Widget customization API lets you set specific theme colors (such as launcher and header colors, end-user and agent message bubble colors, action button colors, and background colors) by calling
zE("messenger:set", "customization", { theme: ... })

These JavaScript-based overrides:

  • apply immediately after the widget loads
  • apply only on pages where the script runs
  • revert to your Admin Center colors when the script is removed or the user visits a page without it
For more information, see Customizing Web Widget colors. Here's an example updating theme colors with JavaScript:
zE("messenger:set", "customization", {
  theme: {
    primary: "#0B5FFF",
    onPrimary: "#FFFFFF",
    message: "#F1F8FF",
    onMessage: "#003366",
    action: "#0B5FFF",
    onAction: "#FFFFFF"
  }
});
The theme object supports properties such as:
  • primary and onPrimary for launcher and key UI elements
  • message and onMessage for end-user bubbles
  • businessMessage and onBusinessMessage for agent and bot bubbles
  • action and onAction for action buttons
  • background and onBackground for widget background and default text and icon color

Changing visible ordering in the widget

Messaging Web Widget supports a zIndex setting that applies to the widget’s iframes, allowing you to control whether the launcher and widget UI appear above or below other fixed elements on your page (such as cookie banners, sticky headers, or floating buttons). Increasing the value brings the widget forward; decreasing it pushes the widget behind other elements.

// Set the z-index for the messaging Web Widget iframes (default is typically 999999)
zE("messenger:set", "zIndex", 1000000);

For more information, see Set zIndex in our developer documentation.

Displaying the widget in embedded mode

In embedded mode, you create a container element in your page and render the messaging Web Widget into that container. You typically disable the floating launcher so only the embedded experience is shown. This is useful when you want messaging to appear inside your page layout (for example, on a dedicated “Contact support” page) instead of as a floating launcher in the corner. This can help avoid overlap with other fixed UI elements and gives you more control over where messaging appears.

Disable auto-rendering by setting window.zEMessenger.autorender = false before loading the widget snippet.

<script>
  window.zEMessenger = {
    autorender: false
  };
</script>

Then call render after the snippet loads.

<!-- Container where the embedded messaging Web Widget will render -->
<div id="embedded-messaging"></div>

<script>
  // Render the widget in embedded mode into the container
  zE("messenger:set", "render", {
    mode: "embedded",
    widget: {
      target: "#embedded-messaging"
    }
  });
</script>
In embedded mode, messaging renders directly inside your target element (not the floating launcher), so it doesn’t use the same open or close behavior. Make sure the container is visible and has enough space (for example, set a min-height or place it in a layout region that provides height) or the embedded experience may appear clipped or too small. For example:
#embedded-messaging { min-height: 520px; }

For more information, see Web Widget embedded mode.

Powered by Zendesk