Messaging Web Widget cookbook

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:

Review this cookbook to understand what some customization options are
available.
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.
Create a specific list of desired changes and include links to any relevant
developer documentation your developer can reference.
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.

&lt;script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=YOUR_KEY"&gt;&lt;/script&gt;

&lt;!-- After the Web Widget code --&gt;
&lt;script&gt;
zE("messenger:set", "locale", "es");
&lt;/script&gt;
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: Help
&lt;script&gt;
document.getElementById("help-button").onclick = function () {
zE("messenger", "show"); // ensure launcher is available
zE("messenger", "open"); // open messaging window
};


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.

&lt;script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=YOUR_KEY"&gt;&lt;/script&gt;

&lt;!-- Immediately after the snippet --&gt;
&lt;script&gt;
zE("messenger:set", "locale", "es");
&lt;/script&gt;

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.

window.zEMessenger = {
autorender: false
};

Then call render after the snippet loads.

&lt;div id="embedded-messaging"&gt;&lt;/div&gt;

&lt;script&gt;
// Render the widget in embedded mode into the container
zE("messenger:set", "render", {
mode: "embedded",
widget: {
target: "#embedded-messaging"
}
});
&lt;/script&gt;

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.



//
const ai_summary_style = document.createElement('style');
ai_summary_style.innerHTML = `#styled-article-body{padding:0 0 0}#article-body #docs-ai-summary{background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 6px;margin-bottom:16px}#article-body #docs-ai-summary #docs-ai-summary-toggle{font-size:.9em;font-weight:700;margin-bottom:4px;cursor:pointer;display:flex;justify-content:space-between;align-items:center}#article-body #docs-ai-summary #docs-ai-summary-toggle #up-triangle{margin-left:auto;padding-right:10px;display:none}#article-body #docs-ai-summary #docs-ai-summary-toggle #down-triangle{margin-left:auto;padding-right:10px}#article-body #docs-ai-summary #docs-ai-summary-content{font-size:.9em;padding-left:25px;padding-right:25px;margin-bottom:12px}`;
document.head.appendChild(ai_summary_style);

const toggleAISummary = () => {
const summary = document.getElementById("docs-ai-summary-content");
const upTriangle = document.getElementById("up-triangle");
const downTriangle = document.getElementById("down-triangle");
if (summary.style.display === "none") {
summary.style.display = "block";
upTriangle.style.display = "none";
downTriangle.style.display = "inline";
} else {
summary.style.display = "none";
upTriangle.style.display = "inline";
downTriangle.style.display = "none";
}
};

document.getElementById("docs-ai-summary-toggle").addEventListener("click", toggleAISummary);
//
