Customizing Web Widget colors

The Web Widget messenger customization API lets you control the widget's appearance in real-time by updating its color theme through JavaScript.

API usage

Call zE("messenger:set", "customization") from your web page to update the widget's 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"  }})

Notes:

This function can be called at any time. The widget will immediately apply the new colors.
The theme object defines colors for the widget interface.
Unknown properties or invalid color values trigger an error in the browser console. Updates are rejected and no colors will change.
All values must be valid CSS color strings: hex, rgb, hsl, or named colors.

Theme color properties

The theme object supports these properties:

Property	Description
primary	Background color for the widget header and launcher.
onPrimary	Text and icon color on primary backgrounds.
message	Background color for end-user messages.
onMessage	Text and icon color on message backgrounds.
businessMessage	Background color for business messages (messages from the business or agents).
onBusinessMessage	Text and icon color on business message backgrounds.
action	Background color for action buttons such as creating new conversation, message, forms and carousel buttons.
onAction	Text and icon color on action backgrounds.
background	Background color for the entire widget (message log, conversation list, channel linking, voice).
onBackground	Color for descriptive elements on background (timestamps, names, message status), with 65% opacity.
error	Background color for alert elements such as failed messages or upload errors.
onError	Text and icon color on error backgrounds.
notify	Color for unread message badges and new message divider in the conversation log.
onNotify	Text color on unread badge backgrounds.
onSecondaryAction	Color overriding border and text for secondary action buttons, also used as for composer's active state.

Fallback behavior

If primary, message, or action colors are not set, the widget uses the colors configured in Admin Center. The default colors are:

Property	Default Color
primary	Admin Center primary color
onPrimary	Black or white for accessibility
message	Admin Center message color
onMessage	Black or white for accessibility
action	Admin Center action color
onAction	Black or white for accessibility
businessMessage	`#F4F6F8`
onBusinessMessage	`#000000`
background	`#FFFFFF`
onBackground	`#000000`
error	`#FFF0F1`
onError	`#8C232C`
notify	`#CC3340`
onNotify	`#FFFFFF`
onSecondaryAction	Falls back to action color

Unsupported elements

The following widget elements use fixed colors and cannot be customized with this API:

Wait time banner
Forms and form inputs, including text fields
Settings dropdown menus
Carousel UI elements

Visual examples of customizable properties


primary	Click to view full size
onPrimary	Click to view full size
message	Click to view full size
onMessage	Click to view full size
action	Click to view full size
onAction	Click to view full size
businessMessage	Click to view full size
onbusinessMessage	Click to view full size
background	Click to view full size
onBackground	Click to view full size
error	Click to view full size
onError	Click to view full size
notify	Click to view full size
onNotify	Click to view full size
onSecondaryAction	Click to view full size