What's my plan?
All Suites Team, Growth, Professional, Enterprise, or Enterprise Plus
Note: This article applies to accounts using the messaging Web Widget. If you're using Web Widget (Classic), see Configuring the components in Web Widget (Classic).

You can configure many appearance-related settings for the Web Widget from the Style tab of the Web Widget page. For example, you can set your company's primary color, widget position, and the appearance details. These settings apply globally, so every visitor sees the same branding.

However, there may be times when you want to test different color schemes, use special colors just on certain pages, or change colors based on the type of visitor. For these scenarios, the messaging Web Widget customization API lets you control your widget's colors in real time using JavaScript.

This article includes the following topics:
  • Understanding the Web Widget customization API
  • Customizing the widget colors
  • Theme tips and best practices

 

Understanding the Web Widget customization API

The Web Widget API is a JavaScript API. When you use JavaScript to change your Web Widget’s colors, your code sends a real-time instruction to the widget to update its appearance. These changes are applied immediately, but only for the people visiting the specific pages where your custom code is running.

If you keep your JavaScript customization on the page, the widget shows your chosen colors every time the page loads. If a visitor goes to a page where your code is not present, or if you remove the code, the widget goes back to its default Admin Center appearance.

How you set it Who sees the changes? When does it revert?
Admin Center brand color Everyone, everywhere When you update the color in Admin Center
API customization Only on pages with the custom code When the code is removed from the page
Note: API customization runs wherever your code is present, including on test and staging sites. It does not work in the Admin Center preview window.

Customizing the widget colors

To customize colors using the Web Widget API, call zE("messenger:set", "customization") from your web page any time once the widget is loaded. The widget immediately applies the new colors.

zE("messenger:set", "customization", {
  theme: {
    primary: "#FE5E41",
    onPrimary: "#FFFFFF",
    message: "#F3C178",
    onMessage: "#5F0F00",
    action: "#B0DB43",
    onAction: "#000000",
    businessMessage: "#fff",
    onBusinessMessage: "#F10404",
    background: "#DFE0E2",
    onBackground: "#F10404",
    error: "#FF1744",
    onError: "#FFFFFF",
    notify: "#FF007F",
    onNotify: "#FFFFFF"
  }
})

The theme object defines colors for various properties of the widget interface. You don’t have to specify every property. Any property you leave out uses your Admin Center default.

All color values must be standard color codes like hex, rgb, hsl, or named colors. Unknown properties or invalid color values will trigger an error in the browser console and no colors will change.

The image below shows you the theme properties that control various aspects of the Web Widget's appearance.

Property Description
primary The widget’s main color, used for the messenger launcher button, top bar, footer highlights, and other key UI elements.
onPrimary The color of text and icons displayed on top of primary-colored backgrounds, such as the launcher button icon or main action buttons.
message Background color chat bubbles from the end user.
onMessage Text color inside end user chat bubbles.
businessMessage Background color for chat bubbles from agents or bots—messages sent by Zendesk or your team.
onBusinessMessage Color of text and icons within agent or bot chat bubbles.
background The main background color of the widget window behind chat bubbles and input fields.
onBackground Default text and icon color displayed on the widget’s background.
error Background color for alert elements, such as error messages or upload failures.
onError Text and icon color for error messages.
notify Background color for certain notification banners or messages. It applies to specific system messages and may not always be visible.
onNotify Text and icon color used in certain notification banners or messages over the notify background.
action Background color for action buttons, such as creating a new conversation, submitting messages, forms, or carousel buttons.
onAction Text and icon color on action button backgrounds.
onSecondaryAction Text and icon color for secondary action buttons inside the widget, such as “Cancel” or “Back.”

If you don't specify a theme property, it uses the default value. For more information on using the Web Widget API to customize your web widget colors, see Customizing Web Widget colors in the developer documentation.

Theme tips and best practices

Here are some design tips for customizing the colors of a messaging Web Widget:

  • Test your color scheme by intentionally using bold, high-contract colors for a property to easily observe what changes in the widget interface.
  • Start simple by changing just a few prominent colors, like primary or action, that match your brand before updating everything.
  • Always choose enough contrast between text (the on* properties) and backgrounds to meet accessibility standards.
  • If any color combination makes text hard to read or looks confusing, even if it matches your brand, change it for clarity.
  • Widget elements like notification banners or error messages may have fixed colors or behave differently depending on your account. Always test critical workflows after making changes.
Powered by Zendesk