Articles in this section

Widget UI for Developers

Here is a comprehensive guide for all Forethought widget UI-related issues. Whether you are a developer or just curious, we are here to help!

All default states of the widget are managed through Forethought. If you would like to variate from default behavior or customizations not changeable in the dashboard, maintenance responsibility will be on your teams side. 

Script Attributes and Values

  • data-api-key (UUID, Forethought provided)
    • the required unique org authentication
  • data-workflow-version (string, default is absent)
    • which version of the workflows are live
  • data-builder-preview (true | false, default is false)
    • Specifies if this widget is showing a preview or is live (if actions / hand-off should really execute)
  • data-intent-id (string, default is absent)
    • used to execute a specific widget workflow
  • data-intent-title (string, default is absent)
    • used to Display the workflows title
  • data-is-model-training (true | false, default is false)
    • Indicated if the workflow routing model is still training or not
  • full-screen (true | false, default is false)
    • controls if the widget automatically opens on load
  • hidden (non-empty string, default is absent)
    • when a string is present widget will hide on load
  • hide-ft-after-zd (true | false, default is false)
    • Keeps the Forethought widget hidden after ZD chat ends 
  • emit-tracking-events (true | false, default is false)
    • Will make Solve UI Widget emit tracking events that you can subscribe to via window.addEventListener('message', callback)


Aesthetic Attributes

config-ft-theme-color - string

Overrides the theme color. Example - #7b33fb

config-ft-agent-avatar-image - string

Overrides the image URL to be used as the avatar image next to messages.

config-ft-widget-header-image - string

Overrides the image URL to be used as the header image.

config-ft-widget-button-image - string

Overrides the image URL to be used as the widget button when the widget is closed.

config-ft-widget-header-title - string

Overrides the header title.

config-ft-greeting-message - string

Overrides the initial greeting message when the widget is open.

config-ft-proactive-prompt-greeting-message - string

Overrides the proactive prompt greeting message. Does nothing if proactive prompt is not enabled.

config-ft-hide-nav - string - true | false (default)

Hides the widget header.

Widget Position Customizations

By default, the widget is placed at 20px away from the bottom right corner



We can customize it with placement attributes however:

  • position-x (left | right)
  • position-y (left | right)
  • offset-x (/^[-]?\d+(px|rem)$/)
  • offset-y (/^[-]?\d+(px|rem)$/)

Note: using position-x="left" and/or position-y="top" along with Proactive Bubbles is not supported for all widget placements (UI will look weird).

Example Embedding Script:




- Chat and widget open-close state persistence is managed on the Forethought side

- State Widget placement and view persistence are managed on your development side.


Changing Widget Behavior with Javascript API

By default, the Forethought widget will be displayed on any page where the embed snippet is present. You can change this and other behavior using the Javascript functions below.

type Forethought = (
  selector: 'widget',
  action: 'open' | 'close' | 'hide' | 'show' | 'triggerEventComplete',
  data?: {
    identifier?: string;
    payload?: Record<string, unknown>;
) => void;

declare global {
  interface Window {
    Forethought: Forethought;
  • window.Forethought('widget', 'open') - open Solve UI Widget
  • window.Forethought('widget', 'close') - close Solve UI Widget
  • window.Forethought('widget', 'hide') - hide Solve UI iframe
  • window.Forethought('widget', 'show') - show Solve UI iframe
  • window.Forethought('widget', 'triggerEventComplete', {identifier: 'trigger_event', payload: {'another cv': 'my updated context value'}}) - used to continue the conversation after a trigger event step which comes from a trigger event action
Was this article helpful?
0 out of 0 found this helpful

More resources

  • Need support?

    Submit a request and our support team will assist you

  • Business hours

    Monday to Friday 8am - 5pm PST excluding US holidays

  • Contact us