Embed Spotter experience

Embed Spotter experience

You can embed the full Spotter experience in your applications using the SpotterEmbed component in the Visual Embed SDK. Using the customization settings available in the SDK for each Spotter version, you can configure the Spotter interface to suit the needs of your embedding application.

Before you begin🔗

To embed Spotter, you need the following access and setup:

Import the SDK package🔗

Import the SpotterEmbed SDK library to your application environment:

npm

import {
    SpotterEmbed,
    AuthType,
    init,
    prefetch,
    EmbedEvent,
    HostEvent
}
from '@thoughtspot/visual-embed-sdk';

ES6

<script type = 'module'>
    import {
        SpotterEmbed,
        AuthType,
        init,
        prefetch,
        EmbedEvent,
        HostEvent
    }
from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/index.js';

Initialize the SDK🔗

To initialize the SDK, the following information is required:

  • thoughtSpotHost
    The hostname of your ThoughtSpot application instance.

  • authType
    Authentication type. For testing purposes, you can use AuthType.None. For information about other authentication options, see Authentication.

init({
    thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL
    authType: AuthType.None, // Use the appropriate AuthType for your setup
});

Create an instance of the SpotterEmbed object🔗

Create an instance of the SpotterEmbed object.

If you are embedding the Spotter Classic or Spotter 2 experience, the data source ID is required. If Spotter 3 experience is enabled on your instance, you can either specify the data source ID or enable the Auto mode to allow Spotter to automatically discover and select data sources.

Important

Auto mode is disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support.

const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    worksheetId: '<%=datasourceGUID%>', // ID of the data source object. To use the Auto mode, set the ID to 'auto_mode',
    //... other attributes
});

Customize your embed (Optional)🔗

The SDK provides configuration settings to customize the embedded Spotter interface. For example, you can hide sample questions or disable data source selection using the hideSampleQuestions and disableSourceSelection parameters.

const conversation = new SpotterEmbed(document.getElementById('ts-embed'), {
    //...other embed configuration attributes
    hideSampleQuestions: true,
    disableSourceSelection: true
});

For more information and examples, see Customizing the embedded Spotter interface.

Register event listeners🔗

To listen to the events emitted by the embedded ThoughtSpot component, register embed event handlers.

The following example shows how to register EmbedEvent.Init and EmbedEvent.Load listeners.

// Register event listeners
spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts
spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded

To trigger actions on the embedded interface, use the Host events.

The following example shows the host event to reset a Spotter conversation session:

// Example: Add a host event to reset the Spotter conversation
document.getElementById('resetBtn').addEventListener('click', () => {
    spotterEmbed.trigger(HostEvent.ResetSpotterConversation);
});

Render the embedded object🔗

spotterEmbed.render();

Verify your embed🔗

  • Load the embedded object.

    • If the embedding is successful, you’ll see the Spotter page.

    • Initiate a chat session, ask a question, and view the results.

    • If you see a blank screen:

      • Verify that your embed code has the correct ThoughtSpot host URL. Ensure that your ThoughtSpot instance is accessible.

      • Verify whether the authentication credentials used in your code are valid.

  • Verify whether the customization settings are applied.

Customizing embedded Spotter interface🔗

When you embed Spotter, you’ll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page vary depending on the Spotter version used for embedding.

Spotter Classic and Spotter 2 experiences🔗

If you have embedded Spotter Classic or Spotter 2, the initial page includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session.

Spotter embed

Spotter 3 experience🔗

In Spotter 3 embedding, you can load the page with a pre-selected data source or use the Auto mode to allow Spotter to automatically discover and select a relevant data model for user queries.

Default view:

Spotter 3 interface

With Auto mode enabled:

Spotter 3 interface
Note

When Auto mode is enabled, Preview data and Data Model instructions options will not be available.

New chat interface🔗

Spotter 3 experience is available with a new prompt interface that includes additional features and user elements to enrich your Spotter experience.

To enable the new chat interface in your embed, set the updatedSpotterChatPrompt attribute:

const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
    // ...other embed configuration attributes
    // Enable the updated Spotter chat prompt experience.
    updatedSpotterChatPrompt: true,
});
Spotter 3 new interface

Chat history panel🔗

You can also include the Chat history panel to allow your users to access the chat history from their previous sessions.

To enable chat history features, set the enablePastConversationsSidebar attributes to true. Additionally, you can also customize the appearance and contents of the chat history panel using the configuration parameters available in the SpotterSidebarViewConfig interface and the spotterSidebarConfig object.

import {
    SpotterEmbed,
    SpotterEmbedViewConfig,
    SpotterSidebarViewConfig
} from '@thoughtspot/visual-embed-sdk';

const embed = new SpotterEmbed('#tsEmbed', {
    // ...other embed view configuration options
    // Configuration for the Spotter sidebar UI
    spotterSidebarConfig: {
        enablePastConversationsSidebar: true, // Show chat history sidebar
        spotterSidebarTitle: 'My Conversations', // Update the title of the sidebar
        spotterSidebarDefaultExpanded: true, // Expand Spotter chat history sidebar by default on load
    },
})
Note

The standalone enablePastConversationsSidebar attribute is deprecated in v1.47.0 and can no longer be used to enable or disable the chat history.

MCP connectors and resource selection icon🔗

A connector is an external MCP server or tool, such as Google Drive, Slack, Notion, Confluence, or Jira, which can be used as a data source in Spotter sessions. ThoughtSpot administrators can configure connectors to enable Spotter users to include both structured and unstructured data in their conversation sessions.

If the new prompt interface in Spotter 3 is enabled, the Spotter page displays the MCP Connectors menu along with a '+' icon in the prompt panel. Your application users can connect to a tool preconfigured by your ThoughtSpot administrator directly from the Spotter 3 prompt interface using the '+' icon and add resources to their conversation context.

Note

The MCP connector module and the '+' icon are displayed by default if the new prompt interface is enabled in your embed. However, we do not recommend using this feature in your production environments.

Currently, the Visual Embed SDK does not provide any attributes or action IDs to hide these elements. As a workaround, you can use the CSS selectors to hide these elements:

init({
   thoughtSpotHost: 'https://your-thoughtspot-host', // URL of your ThoughtSpot instance
   authType: AuthType.None, // Authentication type; use appropriate AuthType for your environment
   customizations: {
    style: {
      customCSS: {
        rules_UNSTABLE: {
          // Hide the MCP connectors module in the Spotter prompt panel
          ".button-module__buttonWrapper.chat-connector-resources-module__addConnectorResourceButton": {
            "display": "none !important"
          },
          // Hide the add resources (+) icon in the Spotter prompt panel
          "button.button-module__button.button-module__buttonWithIcon.button-module__tertiary.button-module__sizeM.button-module__backgroundLight.button-module__both": {
            "display": "none !important"
          }
        }
      }
    }
  },
  // ...other configuration attributes
});

Customizing styles and interface elements🔗

The Visual Embed SDK provides a comprehensive style customization framework for overriding icons, text strings, and the appearance of UI elements.

The customizations object allows you to add custom CSS definitions, replace text strings, and override icons. If your customization framework uses external sources or hosting servers, ensure they are added to the CSP allowlist. For more information, see the CSS customization framework, Customize text strings, and Customize icons sections.

Customize using CSS variables🔗

You can customize the background color of the conversation and prompt panels, button elements, and the components of the charts generated by Spotter using CSS variables.

If Theme Builder is enabled on your ThoughtSpot instance, you can find the variables for Spotter customization by navigating to Develop > Customizations > Theme Builder in the ThoughtSpot UI and downloading the CSS variables.

// Initialize the SDK with CSS variables with custom style definitions
init({
  // ...
  customizations: {
    style: {
      // Use CSS variables to customize styles
      customCSS: {
        variables: {
          "--ts-var-button--primary-background": "#008000",
          "--ts-var-spotter-prompt-background": "#F0EBFF",
          "--ts-var-root-color": "#E3D9FC",
          "--ts-var-root-background": "#F7F5FF",
        },
      },
    },
  },

Customizing text strings🔗

To replace text strings, you can use the stringsIDs and strings properties in the content customization object.

The following example shows how to replace "Spotter" and other text strings on the Spotter interface.

// Initialize the SDK with custom text string replacements
init({
    // ...
    customizations: {
        content: {
            // Use the strings object to replace the visible UI text with custom labels.
            strings: {
                // Change all instances of "Preview data" to "Show data"
                "Preview data": "Show data",
                // Change all instances of "Spotter" to "dataAnalyzer"
                "Spotter": "dataAnalyzer",
            }
        }
    }
});

Customizing the Spotter icon🔗

To override an icon, you must find the ID of the icon, create an SVG file to replace this icon, and add the SVG hosting URL to your embed customization code. The most common icon to override is the default Spotter icon and its icon ID is rd-icon-spotter.

The following example uses the alternate-spotter-icon.svg file hosted on https://cdn.jsdelivr.net/ to override the Spotter icon.

 init({
     //...
     customizations: {
    // Specify the SVG hosting URL to override the icon, for example Spotter (`rd-icon-spotter`) icon
         iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/alternate-spotter-icon.svg"
     }
 });

The following figures show the customized Spotter icon:

Spotter icon customization

Hiding the Spotter icon and ThoughtSpot branding chat interface🔗

To hide the Spotter logo and branding in the chat interface, use the following parameters in the SpotterChatViewConfig interface:

  • hideToolResponseCardBranding
    When set to true, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via toolResponseCardBrandingLabel.

  • toolResponseCardBrandingLabel
    Custom label to replace the ThoughtSpot prefix in tool response cards. Set to an empty string ('') to hide the prefix entirely.

    Example
    import {
        SpotterEmbed,
        SpotterEmbedViewConfig,
        SpotterChatViewConfig
    } from '@thoughtspot/visual-embed-sdk';
    
    spotterChatConfig: {
        //Hide the default logo and label on tool response cards in Spotter chat UI
        hideToolResponseCardBranding: true,
        // Set a custom label to display as the branding on tool response cards
        toolResponseCardBrandingLabel: 'CompanyName',
    }

Customizing menu actions and elements🔗

The SDK provides action IDs to disable, show, or hide the following elements and menu actions via disabledActions, visibleActions, or hiddenActions arrays.

For example, you can hide the Preview data, Reset in the prompt panel, or Pin, Download, and other actions from a Spotter-generated response.

The following code sample disables actions and menu elements using the disabledActions array:

 // Hide these actions
 hiddenActions: [Action.Pin,Action.ResetSpotterChat,Action.DeletePreviousPrompt],
 // Disable actions
 disabledActions:[Action.PreviewDataSpotter,Action.Edit],
 disabledActionReason: "Contact your administrator to enable this feature"

For a comprehensive list of supported actions, see Spotter menu actions.

Code samples🔗

Code sample for embedding Spotter Classic and Spotter 2 experience

import {
    SpotterEmbed,
    AuthType,
    init,
    EmbedEvent,
    HostEvent
} from '@thoughtspot/visual-embed-sdk';
// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type.
init({
    thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL
    authType: AuthType.None, // Use the appropriate AuthType for your setup
});

//Define event handler to show a loading indicator when the embed is initializing.
function showLoader() {
    // Show loading indicator
}

// Define event handler to hide the loading indicator when the embed has loaded.
function hideLoader() {
    // Hide loading indicator
}

// Find the container element in your HTML where the SpotterEmbed will be rendered.
const container = document.getElementById('ts-embed');
if (container) {
    // Create and configure the SpotterEmbed
    const spotterEmbed = new SpotterEmbed(container, {
        frameParams: {
            height: '100%', // Set the height of the embedded frame
            width: '100%', // Set the width of the embedded frame
        },
        worksheetId: 'your-worksheet-id', // ID of the data source object to query data from
        //... other configuration attributes
    });

    // Register event listeners
    spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts
    spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded

    // Render the SpotterEmbed in the container.
    spotterEmbed.render();
    // Example: Add a host event to reset the Spotter conversation
    document.getElementById('resetBtn').addEventListener('click', () => {
        spotterEmbed.trigger(HostEvent.ResetSpotterConversation);
    });
}

Code sample for embedding Spotter 3 experience

import {
    SpotterEmbed,
    AuthType,
    init,
    EmbedEvent,
    HostEvent
} from '@thoughtspot/visual-embed-sdk';
// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type.
init({
    thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL
    authType: AuthType.None, // Use the appropriate AuthType for your setup
});

//Define event handler to show a loading indicator when the embed is initializing.
function showLoader() {
    // Show loading indicator
}

// Define event handler to hide the loading indicator when the embed has loaded.
function hideLoader() {
    // Hide loading indicator
}

// Find the container element in your HTML where the SpotterEmbed will be rendered.
const container = document.getElementById('ts-embed');
if (container) {
    // Create and configure the SpotterEmbed
    const spotterEmbed = new SpotterEmbed(container, {
        frameParams: {
            height: '100%', // Set the height of the embedded frame
            width: '100%', // Set the width of the embedded frame
        },
        worksheetId: 'your-worksheet-id', // ID of the data source object to query data from. For automatic model discovery and selection (Auto mode), specify 'auto_mode'
        updatedSpotterChatPrompt: true, // Enable new chat interface
        enablePastConversationsSidebar: true, // Enable chat history
        //... other configuration attributes
    });

    // Register event listeners
    spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts
    spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded

    // Render the SpotterEmbed in the container.
    spotterEmbed.render();
    // Example: Add a host event to reset the Spotter conversation
    document.getElementById('resetBtn').addEventListener('click', () => {
        spotterEmbed.trigger(HostEvent.ResetSpotterConversation);
    });
}
© 2026 ThoughtSpot Inc. All Rights Reserved.