Your widget should match your brand. From the Widget settings page, scroll down to configure your agent’s colors, icons, launcher style, interface type, and more. You can also add placeholder text and privacy policy links. Customers on a Business plan can disable Voiceflow branding.
The widget supports two modalities: chat and voice. You can configure this in Widget → Modality & Interface → Modaility.Chat modality is the default. Users type messages and see responses as text. This works well for most web use cases. With chat modality, you can optionally enable voice features:
Dictation allows users to input text using speech-to-text.
Voice output lets users hear responses using the text-to-speech model configured in your project settings.
Voice mode enables hands-free conversation. Once the user presses the voice button, they can speak naturally without pressing it again for each message.
Voice modality makes the conversation behave like a phone call. Message history isn’t displayed to the user, and they don’t need to press a button to speak. Users can interrupt the agent by speaking while it responds. The written transcript is still saved for your records.
If you’re a developer, you can extend the widget’s functionality through the web chat API, custom styling, and extensions.For most use cases, the built-in widget customization options in Widget settings are sufficient. But if you need more visual control, you can customize the widget’s appearance with your own CSS or by passing additional configuration options in the chat.load() function.
You can control the widget’s appearance directly in your chat.load() configuration using the assistant object. Here’s an example with the available styling parameters:
window.voiceflow.chat.load({ verify: { projectID: 'YOUR_PROJECT_ID' }, url: 'https://general-runtime.voiceflow.com', assistant: { title: 'Support Chat', description: 'How can I help you today?', image: 'https://example.com/avatar.png', color: '#3D82E2', launcher: 'https://example.com/launcher-icon.png', stylesheet: 'https://example.com/custom-styles.css' }});
These override the remote publishing configuration fetched from the Voiceflow API. All fields are optional but local overrides take priority over remote settings.
Type:string (any valid CSS color parseable by chroma-js)Default:#387dffThe primary brand color used throughout the widget (buttons, links, active states, header accents). The value is parsed by chroma-js, which supports multiple formats:
Format
Example
Notes
Hex (6-digit)
#387dff
Most common, recommended
Hex (3-digit)
#38f
Shorthand hex
Hex with alpha
#387dff80
8-digit hex with alpha
Named CSS color
tomato, cornflowerblue
CSS named colors
RGB
rgb(56, 125, 255)
CSS rgb() function
HSL
hsl(220, 100%, 61%)
CSS hsl() function
When color is provided without a palette, the widget auto-generates a full 10-shade palette using HSL interpolation. The color value becomes shade 500 (the base), and lighter/darker shades are computed by varying the lightness.Examples:
// Default blueassistant: { color: '#387dff' }// Brand redassistant: { color: '#dc2626' }// Using a named colorassistant: { color: 'tomato' }// Dark greenassistant: { color: 'hsl(150, 60%, 30%)' }
Type: Object with 10 required shade keys (all hex strings)Default: Auto-generated from color via HSL interpolationA full color palette that gives you precise control over every shade the widget uses. If provided, this overrides the auto-generated palette entirely. All 10 shades are required.
How auto-generation works: When only color is provided, createPalette(color) extracts the hue (H) and saturation (S) from the color, then generates shades by varying lightness from 95% (shade 50) down to 5% (shade 900). The original color is used as-is for shade 500.
Tip: When providing both color and palette, make sure palette[500] matches color for consistency. If they differ, palette takes priority for rendering while color is effectively ignored.
Type:{ side?: string, bottom?: string }Default:{ side: '30', bottom: '30' } (30 pixels each)Controls the position of the widget relative to the viewport edges. The value is a numeric string representing pixels The px unit is appended automatically. Only effective in overlay mode.
spacing.side Distance from the left or right edge (determined by the side property)
spacing.bottom Distance from the bottom edge
Examples:
// Default positioning (30px from side and bottom)assistant: { spacing: { side: '30', bottom: '30' },}// Tight to the cornerassistant: { side: 'right', spacing: { side: '10', bottom: '10' },}// Large offset from the leftassistant: { side: 'left', spacing: { side: '60', bottom: '40' },}// Only override bottom spacingassistant: { spacing: { bottom: '80' },}
To go beyond the built-in options, you can write CSS rules that override the widget’s default styles. Web chat elements use class names prefixed with .vfrc-.For example, to change the background color of agent messages:
Voiceflow provides a list of supported CSS classes that you can modify. While the widget has additional classes beyond those listed below, modifying them is at your own risk. Only the classes listed below are officially supported.
Once you’ve written your CSS, you can pass it to the widget in two ways.Option 1: Link a hosted stylesheetHost your CSS file and provide the URL in the assistant.stylesheet property:
