Customizing the messaging Web Widget colors with the Web Widget API

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.


{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/9944875856666",
"url": "https://support.zendesk.com/hc/en-us/articles/9944875856666-Customizing-the-messaging-Web-Widget-colors-with-the-Web-Widget-API",
"headline": "Customizing the messaging Web Widget colors with the Web Widget API",
"description": "You can customize the colors of a messaging Web Widget in real time on specific web pages using a JavaScript API that applies changes immediately and reverts when the code is removed.",
"articleSection": "Web Widget documentation",
"datePublished": "2025-11-13T17:19:59+00:00",
"dateModified": "2025-11-20T21:33:26+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/9944875856666"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"@id": "https://support.zendesk.com/hc/"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
}
}