Articles in this section

Installation Guide for Solve Widget

Use these instructions to install the Forethought Solve Widget on any webpage you have administrator access to. If you don’t, just connect us with your web page administrator, and we’ll work with them to get this up and running!


Embedding the Widget on a Webpage

To access your code snippet, follow these steps.  If additional help is needed, please reach out to your customer success manager.

  1. Access your code snippet
    1. Navigate to the Forethought dashboard -> Solve -> Widget Configuration tab
    2. On the right side of the page click "Embed"Screenshot 2023-11-09 at 3.31.51 PM.png
    3. Add the domain you want to add the widget to into the domain allowlist
    4. Check "Show API key in code snippet and copy the codeScreenshot 2023-11-09 at 3.37.24 PM.png
  2. Then place the snippet in the body of any webpage where you want the Forethought widget to appear.
id="forethought-widget-embed-script" data-api-key="Insert API key here" ></script>


Adding Script Dynamicly to the DOM

The snippet can also be inserted into DOM dynamically (e.g. only on pages that need it) and removed by id (id of the iframe that holds the widget is forethought-chat). An example of adding it dynamically is below:

// Remove old widget, if it exists:

const script = document.createElement("script");
script.setAttribute("src", "");
script.setAttribute("id", "forethought-widget-embed-script");
script.setAttribute("data-api-key", "Insert API key here");
script.setAttribute("data-ft-foo", "bar"); // optional


Mobile SDK Installation

The recommended mobile solution is to use our Android and iOS SDKs found here. Installation and Usage guides can be found there.

For more information see the SDK Installation article here


Manipulating Widget Behavior 

Passing Custom Parameters

To pass parameters that can afterwards be used in conditions that determine behavior, add an attribute prefixed with data-ft- to the script tag.

In the example below, we"ve added a usertype parameter to the script.

data-api-key="Insert API key here"

There are a few ways your engineering team can get necessary values to pass in - take them from the page contents (e.g. if user email is specified in the profile section on the page), by making an API call to one of your services and using the response value, or by taking relevant info from the window object if it is there.

The attributes are all strings, so if you"re looking to pass a list of values, pass it as a delimiter-concatenated string of “|” (e.g.  for [1,2,3] pass “1|2|3”)

Additional 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.
  • config-ft-disable-close - string - "true" | "false" (default) - Hides the "Minimize chat" button in the chat header.

  • config-ft-banner-image-enabled - string - "true" | "false" (default)- Overrides whether the banner image is enabled or not.

  • config-ft-banner-image - string - Image URL. Overrides the banner image if that is enabled.

  • config-ft-banner-image-alt-text - string - Overrides the banner image alt text.

  • config-ft-banner-image-link - string - Overrides the banner redirect URL.

  • config-ft-show-when-conversation-starts - string - "true" | "false" (default) - Overrides whether the privacy consent should be shown when conversation starts

  • config-ft-privacy-policy - string - Overrides the privacy policy shown in the privacy consent modal

  • config-ft-prompt-header - string - Overrides the prompt header of the privacy consent modal

  • config-ft-call-to-action-label - string - Overrides the call to action label of the privacy consent modal

  • initial-intent-id -string - conversation will start the specific workflow ID put here
  • initial-query - string - initialize conversation with a specific query

  • hide-intercom-widget - string - "true" (default) | "false" - when false, Intercom will not be hidden on page load.

  • emit-tracking-events - "true" | "false" (default) - Will make Solve UI Widget emit tracking events that you can subscribe to via `window.addEventListener('message', callback)`.

  • config-ft-persistence-id - string - Creates a separate persistence store for this `config-ft-persistence-id`

    • Example: use `config-ft-persistence-id="my-persistence-id-1"` in one snippet and `config-ft-persistence-id="my-persistence-id-2"` in another to have 2 separate persisted widgets.

    • Note: if you use `config-ft-persistence-id`, it disables the default
      `data-ft-workflow-tag` persistence behavior. So if you need to also have
      separate persistence stores for different workflow tags, you need to make your
      workflow tags be a part of `config-ft-persistence-id` value, e. g. `config-ft-persistence-id="my-persistence-id-1 workflow-tag-1 workflow-tag-2"`

  • auto-open-zd - "true" (default) | "false" - When false, Forethought will show the Zendesk widget if a chat is active on page load but will not open the Zendesk widget.

Display Script Parameters

  • full-screen - "true" | "false" (default)
    • When true, the widget will open automatically on load.
  • hidden - non-empty string, default: absent
    • When set to a non-empty string, the widget iframe will get hidden automatically on load.
  • hide-ft-after-zd - true or false (default)
    • Will keep Solve UI Widget hidden after a Zendesk chat is ended.

Positioning Script Parameters

  • position-x - left or right (default)
  • position-y - top or bottom (default)
  • offset-x - horizontal offset - default 20px (can be px or rem)
  • offset-y - vertical offset - default 20px (can be px or rem)

Parameters Interacting with Forethought Widget

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.

  • window.Forethought("widget", "open") - open Solve UI Widget - picture below
  • window.Forethought("widget", "close") - close Solve UI Widget - picture below
  • 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
  • window.Forethought('widget', 'clearLocalData') - clear data in localStorage (useful for logging out)
  • window.Forethought('widget', 'launchQuery', {payload: {query: string}}) - clears data and initializes a new conversation with provided query

Screen_Shot_2022-03-04_at_2.21.36_PM.png                               Screen_Shot_2022-03-04_at_2.22.05_PM.png

               Opened                                                                         Closed

If you want to make one of these calls on page load please subscribe to the forethoughtWidgetLoaded event, and make your call when the event is received, for example:

window.addEventListener('message', (event) => {
  if ( === 'forethoughtWidgetLoaded') {
    Forethought("widget", "open")


Installing to Zendesk Help Center: Extra Options

Hide the Forethought Solve Widget from Unauthenticated Users

To make sure only signed-in users see the Forethought widget, wrap the embed snippet in a simple if-else block like this:

// Widget embed script: only show to logged-in Zendesk users
{{#if signed_in}}
    data-api-key="Insert Api Token Here"
Was this article helpful?
3 out of 8 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