diff --git a/modules/ROOT/pages/.write-test b/modules/ROOT/pages/.write-test new file mode 100644 index 000000000..0e808f9c2 --- /dev/null +++ b/modules/ROOT/pages/.write-test @@ -0,0 +1 @@ +write access test - delete me \ No newline at end of file diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index cb2867e9c..b5ca29e8c 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,20 +8,164 @@ This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +== Version 1.52.x, September 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# +a| +[discrete] +===== Spotter conversation sharing in embedded views +Embedding application users can now share a saved Spotter conversation with other users and groups directly from the embedded interface. Recipients can view the shared conversation in a read-only view. +Conversation sharing is turned off by default in embedded views. To enable it, set `enableShareConversation` to `true` in the `spotterShareConversationConfig` object. + +Interface customization settings:: +The SDK also provides the following controls for conversation sharing: + +* `SpotterShareConversationConfig` + +Includes object properties for enabling conversation sharing, label and text overrides for the share button, share modal, recipient picker, and the read-only shared view. For more information, see xref:customize-spotter-sharing.adoc[Customize conversation sharing experience]. +* `sharedConversationId` + +Allows passing conversation ID to the SpotterEmbed when the sharing link is generated for the recipient users in the embedded app. For more information, see xref:customize-spotter-sharing.adoc#_customizing_conversation_sharing_link[Conversation sharing link] + +New action IDs:: +* `Action.SpotterShareConversationButtonHeader` for **Share** button in the Spotter conversation header. +* `Action.SpotterShareConversationMenuItemSidebar` for **Share** menu action in the chat history panel in the sidebar. +* `Action.SpotterShareIncludeNewMessagesCheckbox` for the `include new messages since last shared version` checkbox in the share modal. +* `SpotterSharedConversationBannerDismissButton` for the dismiss button of the data access banner displayed in the shared conversation view. +* `Action.SpotterShareUpToCurrentInfo` for the share modal footer note. +* `Action.SpotterSharedConversationBanner` for the data access banner shown when a recipient opens a shared conversation. +* `Action.SpotterShareStaleInfoBannerDismissButton` for the banner that shows the message, "This data may have changed since the last time you had a chat." +* `Action.SpotterSharedConversationExitButton` for *Exit* button in the read-only view of the shared conversation. + +New host events:: +* `HostEvent.ShareSpotterConversation` + +Opens the Spotter share conversation modal for the given conversation ID. +* `HostEvent.ExitSpotterSharedConversation` + +Exits the read-only view of the shared conversation. +* `HostEvent.CloseSpotterShareConversation` + +Closes the Spotter share conversation modal. + +New embed events:: +* `EmbedEvent.SpotterConversationShared` + +Emitted when a Spotter conversation is shared with the intended recipients. +* `EmbedEvent.SpotterConversationShareRevoked` + +Emitted when access to a shared Spotter conversation is revoked. +* `EmbedEvent.SpotterSharedConversationViewed` + +Emitted when a recipient opens a shared Spotter conversation. +* `EmbedEvent.SpotterShareConversationButtonHeaderClicked` + +Emitted when the Share button in the conversation header is clicked. +* `EmbedEvent.SpotterShareConversationMenuItemSidebarClicked` + +Emitted when the Share action in the menu displayed for a chat in the chat history sidebar. +* `SpotterShareIncludeNewMessagesCheckboxToggled` + +Emitted when the user toggles the "include new messages since last shared version" checkbox in the share modal. +* `EmbedEvent.SpotterShareModalCancelButtonClicked` + +Emitted when the Cancel button in the share conversation modal is clicked. +* `EmbedEvent.SpotterShareStaleInfoBannerDismissed`+ +Emitted when the user dismisses the banner that shows the text, "This data may have changed since the last time you had a chat." +* `EmbedEvent.SpotterSharedConversationExitButtonClicked` + +Emitted when a user exits the shared conversation read-only view. + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Browser history management in embedded application +To override the browser history behavior for embedding application users, you can now set `overrideHistoryState` in the Visual Embed SDK. Use this setting in your embed when the in-app navigation between objects pushes multiple entries onto the host application's browser history stack. When set to `true`, this feature prevents users from getting trapped in back-button loops inside the embedded iframe. + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Customization controls for Collections in full application embedding +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +|[tag greenBackground]#MODIFIED# a| + +[discrete] +===== Lazy loading defaults for Liveboards +When `fullHeight` is enabled on `LiveboardEmbed` or `AppEmbed`, the following lazy-loading parameters now default to `true`: + +* `lazyLoadingForFullHeight` + +Enables lazy loading of visualizations when fullHeight is enabled. +* `enableScrollableContainerLazyLoading` + +Enables lazy loading for scrollable container elements. +* `lazyLoadingMargin` + +Sets the margin for lazy loading to `'500px 0px'`. + +These defaults apply automatically. Any value you set explicitly, including `false`, overrides the default. If `fullHeight` is disabled or not specified, the behavior is not affected. + +For more information, see xref:lazy-loading-fullheight.adoc[Full height and lazy loading options for Liveboards]. + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Pre-render configuration object +The SDK introduces the `PreRenderConfig` interface, which bundles the existing prerender settings such as `preRenderId`, `preRenderContainer`, and `doNotTrackPreRenderSize` into a single object. + +The existing individual `preRenderId`, `preRenderContainer`, and `doNotTrackPreRenderSize` properties at the top-level are deprecated in this version. Update your integration to use the new `preRenderConfig` property on `BaseViewConfig` instead of the individual top-level properties. + +For more information, see xref:prerender.adoc[Pre-rendering ThoughtSpot embed components]. + +|[tag greenBackground]#NEW# +a| + +[discrete] +===== CSS customization + +CSS variable for unsaved filter indicator:: +A new CSS variable `--ts-var-unsaved-filter-indicator-color` is available to customize the color of the "unsaved changes" indicator dot shown on filter and parameter chips. + +Insight tile CSS variables:: +New CSS variables are available to customize the Liveboard insight tile appearance: + +* `--ts-var-liveboard-insight-tile-background` + +Background color of the insight tile. +* `--ts-var-liveboard-insight-tile-icon-color` + +Color of the insight tile icon. +* `--ts-var-liveboard-insight-tile-success-color` + +Color used for positive/success indicators. +* `--ts-var-liveboard-insight-tile-failure-color` + +Color used for negative/failure indicators. + +For more information, see xref:css-customization.adoc[CSS customization framework]. + +|| +|==== + +//// +|[tag greenBackground]#NEW# a| + + +[discrete] +===== Exported host-event contract types +The SDK now publicly exports host-event contract types that were previously internal-only. This allows TypeScript consumers to strongly type `embed.trigger(HostEvent.X, payload)` calls without importing internal modules. + +Newly exported types include: + +* `UIPassthroughContractBase`, `UIPassthroughRequest`, `UIPassthroughResponse`, `UIPassthroughArrayResponse` +* `HostEventRequest`, `HostEventResponse` +* `TriggerPayload`, `TriggerResponse` +* `LiveboardTab`, `LiveboardGroup` +* `Applicability`, `ApplicabilityLevel` +* `FilterUpdate`, `LiveboardFilter`, `LiveboardParameter` +* `SpotterAnalystConfig` +* `StarterPromptsConfig`, `StarterPromptCategory`, `StarterPreviewDataCategory`, `StarterPromptQuestion` +//// + == Version 1.51.x, August 2026 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Spotter embedding Spotter Analysts:: -The Visual Embed SDK introduces controls for the Spotter Analysts feature in embedded applications. The Analysts section in the Spotter sidebar is disabled by default in the embed mode. For more information, see xref:customize-spotter-embed.adoc#_spotter_analysts[Spotter Analysts in embed view]. +The Visual Embed SDK introduces controls for the Spotter Analysts feature in embedded applications. The Analysts section in the Spotter sidebar is disabled by default in the embed mode. For more information, see xref:customize-spotter-analysts.adoc#_spotter_analysts[Spotter Analysts in embed view]. Starter prompts:: -If quick starter prompts are enabled and configured for data models on a ThoughtSpot instance, you can display these prompts in the embed using the `enableStarterPrompts` parameter. For more information, see xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. +If quick starter prompts are enabled and configured for data models on a ThoughtSpot instance, you can display these prompts in the embed using the `enableStarterPrompts` parameter. For more information, see xref:customize-spotter-chat-experience.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. |[tag greenBackground]#MODIFIED# a| @@ -42,34 +186,19 @@ Enables interactive filter chips that allow users to add, update, or remove filt For more information, see xref:embed-pinboard.adoc#common-customizations[Common customization options in Liveboard embedding]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Object format support in HostEvent.Navigate The `HostEvent.Navigate` event now supports an object format in addition to the existing string path format. Use the object format to replace the current browser history entry instead of pushing a new entry. -//// -[source,JavaScript] ----- -// String format — push new history entry (existing behavior, unchanged) -appEmbed.trigger(HostEvent.Navigate, 'home'); ----- - -[source,JavaScript] ----- -// Object format — replace current history entry (new in SDK 1.51.0) -appEmbed.trigger(HostEvent.Navigate, { path: 'home', replace: true }); ----- -Supported embed types: `AppEmbed`. -//// - |==== == Version 1.50.x, July 2026 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== SpotterViz embed customization @@ -77,7 +206,7 @@ The Visual Embed SDK 1.50.0 introduces the `SpotterVizConfig` interface and `Spo A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` for the `spotterViz` object. This object provides branding customization controls for customizing the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Home page customization in full application embedding @@ -90,7 +219,7 @@ For more information, see xref:full-app-customize.adoc[Customize full applicatio [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Visual overrides for charts and tables The SDK introduces the `visualOverrides` object in `SearchViewConfig` and @@ -107,7 +236,7 @@ The `visualOverrides` object provides the following customization controls to mo * `updateMaskPaths` property for partial updates. For more information, see xref:viz-overrides.adoc[Visualization overrides]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Liveboard browser cache refresh @@ -124,7 +253,7 @@ Action ID to show or hide the cache refresh button. For more information, see xref:embed-pinboard.adoc#liveboard-data-cache[Enable Liveboard refresh]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Spotter file upload The SDK introduces the following configuration parameters in `SpotterChatConfig` object to enable and control file uploads in the embedded Spotter chat interface. @@ -142,7 +271,7 @@ For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploa == Version 1.48.x, May 2026 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Liveboard embedding The SDK includes the following new features and enhancements in Liveboard embedding. @@ -181,7 +310,7 @@ Programmatically triggers the Send now action to send a test email notification * `Action.SendTestScheduleEmail` + Action ID to disable, show, or hide the **Send now** button on the Liveboard schedule page. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Spotter embedding @@ -195,7 +324,7 @@ For the connectors panel section in the Spotter chat interface. * `Action.SpotterChatModeSwitcher` + For the mode switcher in the Spotter chat interface. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Event handling @@ -215,7 +344,7 @@ host event has been updated to include a `type` discriminator field, making it consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Personalized View selection via host event @@ -242,7 +371,7 @@ The following events are deprecated and replaced with new event IDs. == Version 1.47.x, April 2026 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat history sidebar customization** +|[tag greenBackground]#NEW# a| **Spotter chat history sidebar customization** The SDK introduces the `SpotterSidebarViewConfig` interface and the `spotterSidebarConfig` object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the `spotterSidebarConfig` object to enable or disable chat history panel and customize the contents of the sidebar when enabled: @@ -297,7 +426,7 @@ spotterSidebarConfig: { } ---- -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat UI branding** +|[tag greenBackground]#NEW# a| **Spotter chat UI branding** The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. @@ -312,7 +441,7 @@ Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to These settings do not affect the external MCP tool branding. ==== -|[tag greenBackground]#NEW FEATURE# a|**Liveboard embed enhancements** +|[tag greenBackground]#NEW# a|**Liveboard embed enhancements** Personalized Liveboard view:: @@ -322,7 +451,7 @@ Centralized Liveboard filter setting:: When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. -|[tag greenBackground]#NEW FEATURE# a|**Option to include current period in rolling date filters** +|[tag greenBackground]#NEW# a|**Option to include current period in rolling date filters** If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. @@ -333,7 +462,7 @@ To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| **Host events with page context framework** +|[tag greenBackground]#NEW# a| **Host events with page context framework** The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. @@ -347,7 +476,7 @@ For more information, refer to the xref:events-context-aware-routing.adoc[Host e The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. -|[tag greenBackground]#NEW FEATURE# a| **Spotter experience** +|[tag greenBackground]#NEW# a| **Spotter experience** The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. Chat history sidebar customization:: @@ -378,11 +507,11 @@ Is emitted when a saved chat is deleted. * `EmbedEvent.SpotterConversationSelected` + Is emitted when a saved chat is selected in the chat history sidebar. -|[tag greenBackground]#NEW FEATURE# | `enableLinkOverridesV2` + +|[tag greenBackground]#NEW# | `enableLinkOverridesV2` + Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** +|[tag greenBackground]#NEW# a| **Liveboard experience enhancements** * The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. * The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. @@ -392,7 +521,7 @@ Use this configuration setting to override ThoughtSpot URLs on hover or when ope [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter enhancements** +|[tag greenBackground]#NEW# a| **Spotter enhancements** You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface. @@ -413,7 +542,7 @@ Events:: On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. ==== -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + +|[tag greenBackground]#NEW# a| **Liveboard experience enhancements** + Styling and grouping:: @@ -431,7 +560,7 @@ For more information, see link:https://docs.thoughtspot.com/cloud/latest/securit + The `showMaskedFilterChip` setting is also available in full application embedding. -|[tag greenBackground]#NEW FEATURE# a| **Publishing objects** +|[tag greenBackground]#NEW# a| **Publishing objects** The following action IDs are available for the data publishing menu actions in the *Data workspace* page: @@ -439,7 +568,7 @@ The following action IDs are available for the data publishing menu actions in t * `Action.ManagePublishing` for *Manage publishing* * `Action.Unpublish` for *Unpublish* * `Action.Parameterize` for *Parameterize* -|[tag greenBackground]#NEW FEATURE# a| **Error handling improvements** +|[tag greenBackground]#NEW# a| **Error handling improvements** To handle errors in the embedding workflows, the SDK includes the following features: @@ -460,7 +589,7 @@ For more information, see link:https://developers.thoughtspot.com/docs/Enumerati The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. -|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + +|[tag greenBackground]#NEW# a| *Intercepting API calls* + The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: //* `enableApiIntercept` + @@ -481,7 +610,7 @@ For more information, see xref:api-intercept.adoc[Intercept API calls and search == Version 1.43.0, November 2025 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* +|[tag greenBackground]#NEW# a| *Code-based custom actions* The following enumerations are available for code-based custom actions: @@ -489,7 +618,7 @@ The following enumerations are available for code-based custom actions: To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. * `CustomActionsPosition` + To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. -|[tag greenBackground]#NEW FEATURE# | *Attribute to set Parameter chip visibility during overrides* + +|[tag greenBackground]#NEW# | *Attribute to set Parameter chip visibility during overrides* + The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. |==== @@ -497,14 +626,14 @@ The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleTo [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|*Runtime overrides in Spotter embed* +|[tag greenBackground]#NEW# a|*Runtime overrides in Spotter embed* The Visual Embed SDK now supports runtime overrides in Spotter embed. * To apply runtime filters, use the `runtimeFilters` object * To apply runtime Parameters, use the `runtimeParameters` object. -|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + +|[tag greenBackground]#NEW# a|*PNG images in Liveboard schedule notifications* + To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. The SDK also provides the following action IDs: @@ -513,7 +642,7 @@ The SDK also provides the following action IDs: Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. * `Action.RemoveAttachment` + Allows the user to remove an attachment from the email configuration in the schedule email dialog. -|[tag greenBackground]#NEW FEATURE# a|*Spotter embed* +|[tag greenBackground]#NEW# a|*Spotter embed* Action IDs:: The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: @@ -530,13 +659,13 @@ Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/lates [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|*React component for Spotter Agent embed* +|[tag greenBackground]#NEW# a|*React component for Spotter Agent embed* The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter embed* +|[tag greenBackground]#NEW# a|*Event handlers for Spotter embed* The following event handlers are now available for Spotter embed: @@ -555,7 +684,7 @@ Triggers the action to get TML representation of a Spotter-generated Answer. For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter Agent embed* +|[tag greenBackground]#NEW# a|*Event handlers for Spotter Agent embed* You can now use the following host events in Spotter Agent embedding: @@ -574,7 +703,7 @@ Triggers the *Save* action for a Spotter-generated Answer. For more information, see xref:HostEvent.adoc[HostEvent]. -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading of visualizations on an embedded Liveboard* +|[tag greenBackground]#NEW# a| *Lazy loading of visualizations on an embedded Liveboard* You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. @@ -582,7 +711,7 @@ You can also set the margin property for lazy loading to define when the visuali For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. -|[tag greenBackground]#NEW FEATURE# a| *Full application embed* + +|[tag greenBackground]#NEW# a| *Full application embed* + You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. @@ -593,22 +722,22 @@ When enabled, the left navigation panel organizes the application menu into pers [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + +|[tag greenBackground]#NEW# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. -|[tag greenBackground]#NEW FEATURE# a| *PDF download settings* + +|[tag greenBackground]#NEW# a| *PDF download settings* + Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. -|[tag greenBackground]#NEW FEATURE# a| *Parameter for overriding a default primary action* + +|[tag greenBackground]#NEW# a| *Parameter for overriding a default primary action* + If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. -|[tag greenBackground]#NEW FEATURE# a| *Full application embed experience enhancements* + +|[tag greenBackground]#NEW# a| *Full application embed experience enhancements* + The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. -|[tag greenBackground]#NEW FEATURE# a| *Host events* + +|[tag greenBackground]#NEW# a| *Host events* + In this version, the SDK introduces the following host event handlers: @@ -627,7 +756,7 @@ Triggers the delete prompt action. For more information, see xref:HostEvent.adoc[HostEvent]. -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* +|[tag greenBackground]#NEW# a|*Events support for Spotter embed* You can now use the following host events in Spotter embed: @@ -643,7 +772,7 @@ You can now use the following host events in Spotter embed: For more information, see xref:HostEvent.adoc[HostEvent]. -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading with full height* +|[tag greenBackground]#NEW# a| *Lazy loading with full height* The SDK introduces `lazyLoadingForFullHeight` parameter, which enables progressive loading of visualizations on an embedded Liveboard. This parameter works in conjunction with the `fullHeight` attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. @@ -659,7 +788,7 @@ To use these attributes effectively in embedded applications, your ThoughtSpot i [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + +|[tag greenBackground]#NEW# a| *Spotter embed components with new names* + The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: * `ConversationEmbed` + @@ -673,13 +802,13 @@ Replaced with `SpotterAgentEmbedViewConfig` The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. -|[tag greenBackground]#NEW FEATURE# a| *Action ID for Spotter in-conversation training* + +|[tag greenBackground]#NEW# a| *Action ID for Spotter in-conversation training* + For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. [NOTE] The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* +|[tag greenBackground]#NEW# a|*Events support for Spotter embed* New embed events:: @@ -733,7 +862,7 @@ For more information, see xref:EmbedEvent.adoc[EmbedEvent]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| *String IDs for text customization* + +|[tag greenBackground]#NEW# a| *String IDs for text customization* + Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. To locate the string IDs, SDK provides the `exposeTranslationIds` attribute. By setting `exposeTranslationIds` to `true` in the Playground, you can find the string ID of the UI text and use it in your customization code. @@ -742,7 +871,7 @@ Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSO For more information, see xref:customize-text-strings.adoc[Customize text strings]. -|[tag greenBackground]#NEW FEATURE# a| *Hide columns on list pages* + +|[tag greenBackground]#NEW# a| *Hide columns on list pages* + In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: @@ -764,16 +893,16 @@ For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pag [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. -|[tag greenBackground]#NEW FEATURE# a| This version of the SDK supports the following embed and host events: +|[tag greenBackground]#NEW# a| This version of the SDK supports the following embed and host events: Embed Events:: @@ -796,7 +925,7 @@ Triggers the *Delete* action on a Liveboard. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| The following HostEvents now allow custom parameters to set object properties programmatically: * `HostEvent.SaveAnswer` + @@ -806,7 +935,7 @@ Allows adding custom properties for visualization ID, name, and description, Liv For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| New configuration attributes:: @@ -848,7 +977,7 @@ The following new CSS variables are available for Spotter interface customizatio * `--ts-var-spotter-prompt-background` For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| Configuration attributes:: @@ -872,7 +1001,7 @@ ID for the action that disables filter chip reordering. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: * When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface @@ -880,14 +1009,14 @@ The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. -|[tag greenBackground]#NEW FEATURE# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. +|[tag greenBackground]#NEW# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. |==== == Version 1.34.0, November 2024 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| You can now embed the following ThoughtSpot Spotter components in your app: +|[tag greenBackground]#NEW# a| You can now embed the following ThoughtSpot Spotter components in your app: * `SpotterEmbed` + Embeds Spotter conversation interface in your app @@ -896,7 +1025,7 @@ Creates a conversation component without the body, which can be integrated into For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. -|[tag greenBackground]#NEW FEATURE# a|The following parameters and enumerations are available for customizing Liveboard experience: +|[tag greenBackground]#NEW# a|The following parameters and enumerations are available for customizing Liveboard experience: * `showLiveboardVerifiedBadge` + Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. @@ -905,16 +1034,16 @@ Shows or hides the re-verify banner. Available if the Liveboard compact header f * `Action.KPIAnalysisCTA` + Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. -|[tag greenBackground]#NEW FEATURE# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. +|[tag greenBackground]#NEW# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. -|[tag greenBackground]#NEW FEATURE# a|The following parameters are available for customizing Search experience: +|[tag greenBackground]#NEW# a|The following parameters are available for customizing Search experience: * `collapseDataPanel` Minimizes the data panel view. Users can click the data panel header any time to expand the panel. * `collapseSearchBar` Sets the initial state of the search bar when embedding a saved Answer. -|[tag greenBackground]#NEW FEATURE# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: +|[tag greenBackground]#NEW# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: * `HomeLeftNavItem.LiveboardSchedules` + The Liveboard schedules menu on the left navigation panel. @@ -937,7 +1066,7 @@ To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. +|[tag greenBackground]#NEW# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. You can set the `homePageSearchBarMode` property to one of the following options: @@ -947,8 +1076,8 @@ Displays the search bar for Natural Language Search. Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. ** `objectSearch` (default) + Displays Object Search bar on the **Home** page. -|[tag greenBackground]#NEW FEATURE# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following Event and Action enumeration members: +|[tag greenBackground]#NEW# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. +|[tag greenBackground]#NEW# a| The SDK includes the following Event and Action enumeration members: Events:: @@ -968,7 +1097,7 @@ Use this action enumeration to disable, show, or hide the **Manage tags** button [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The following new action enumerations are available in this version: + +|[tag greenBackground]#NEW# a| The following new action enumerations are available in this version: + * `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + * `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. @@ -978,26 +1107,26 @@ Use this action enumeration to disable, show, or hide the **Manage tags** button * `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. * `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) For more information, see xref:Action.adoc[Actions]. -|[tag greenBackground]#NEW FEATURE#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. -|[tag greenBackground]#NEW FEATURE# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. +|[tag greenBackground]#NEW#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. +|[tag greenBackground]#NEW# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. || |==== == Version 1.31.x, July 2024 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| Runtime filters + +|[tag greenBackground]#NEW# a| Runtime filters + * `NOT_IN` operator for Runtime filters. For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. * `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. -|[tag greenBackground]#NEW FEATURE# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. +|[tag greenBackground]#NEW# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. |==== == Version 1.30.0, June 2024 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| **CSS variables for new homepage experience** +|[tag greenBackground]#NEW# a| **CSS variables for new homepage experience** * `--ts-var-home-watchlist-selected-text-color` + * `--ts-var-home-card-color` + @@ -1012,7 +1141,7 @@ For more information, see xref:css-customization.adoc#_homepage_modules_new_expe [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| **Ask Sage** +|[tag greenBackground]#NEW# a| **Ask Sage** With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. @@ -1043,11 +1172,11 @@ Updates cross filters applied on a Liveboard. [width="100%" cols="1,4"] |===== -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following new enumeration members in v1.28.0: +|[tag greenBackground]#NEW# a| The SDK includes the following new enumeration members in v1.28.0: ** `Action.VerifiedLiveboard` + Can be used to show or hide the *Verified Liveboard* banner. -|[tag greenBackground]#NEW FEATURE# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: +|[tag greenBackground]#NEW# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: * `hiddenhomeleftnavitems` * `hiddenhomepagemodules` @@ -1058,11 +1187,11 @@ Can be used to show or hide the *Verified Liveboard* banner. * `HomeLeftNavItem` For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. -|[tag greenBackground]#NEW FEATURE# a| The following embed event is available from the v1.28.0 onwards: +|[tag greenBackground]#NEW# a| The following embed event is available from the v1.28.0 onwards: `EmbedEvent.Rename` + Emits when an embedded Liveboard or visualization is renamed. -|[tag greenBackground]#NEW FEATURE# a| TML actions +|[tag greenBackground]#NEW# a| TML actions The following TML menu actions are now grouped under the **TML** sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page. @@ -1089,10 +1218,10 @@ hiddenActions: [Action.TML] // to disable all TML actions disabledActions: [Action.TML] ---- -|[tag greenBackground]#NEW FEATURE# | You can now reset authentication token and fetch a new token for new authentication requests. +|[tag greenBackground]#NEW# | You can now reset authentication token and fetch a new token for new authentication requests. For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. -|[tag greenBackground]#NEW FEATURE#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: +|[tag greenBackground]#NEW#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: * `numberFormatLocale` + * `dateFormatLocale` + @@ -1100,7 +1229,7 @@ For more information, see link:https://developers.thoughtspot.com/docs/Function_ For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. -|[tag greenBackground]#NEW FEATURE# |Tokenized fetch + +|[tag greenBackground]#NEW# |Tokenized fetch + The SDK now provides a fetch wrapper that adds the authentication token to the API requests. For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. |===== @@ -1109,7 +1238,7 @@ For more information, see link:https://developers.thoughtspot.com/docs/Function_ [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The following action enumeration members are available from v1.27.9 and v1.27.10: +|[tag greenBackground]#NEW# a| The following action enumeration members are available from v1.27.9 and v1.27.10: * `Action.AIHighlights` * `Action.AddToWatchlist` @@ -1117,14 +1246,14 @@ For more information, see link:https://developers.thoughtspot.com/docs/Function_ * `Action.CopyKpiLink` For more information, see xref:Action.adoc[Action]. -| [tag greenBackground]#NEW FEATURE# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. +| [tag greenBackground]#NEW# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. |==== == Version 1.27.0, January 2024 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. +|[tag greenBackground]#NEW# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. For a complete list of methods, functions, interface objects, and properties, see the following pages: + @@ -1133,7 +1262,7 @@ For a complete list of methods, functions, interface objects, and properties, se |[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: +|[tag greenBackground]#NEW# a| The new version of the SDK introduces the following new enumeration members: * Host Events ** `HostEvent.UpdateSageQuery` + @@ -1149,10 +1278,10 @@ Emitted when a user creates a new Worksheet. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. +|[tag greenBackground]#NEW# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. -|[tag greenBackground]#NEW FEATURE# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: +|[tag greenBackground]#NEW# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: * `showLiveboardDescription` + Shows the Liveboard description text when set to `true` @@ -1167,9 +1296,9 @@ Hides the specified tabs from the Liveboard page * `visibleTabs` + Displays the specified tabs on the Liveboard page -|[tag greenBackground]#NEW FEATURE# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. +|[tag greenBackground]#NEW# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports the following events: +|[tag greenBackground]#NEW# a|The new version of the SDK supports the following events: Embed events:: * `EmbedEvent.hiddenTabs` @@ -1193,7 +1322,7 @@ Host events:: + For more information, see xref:HostEvent.adoc[HostEvent]. -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: +|[tag greenBackground]#NEW# a| The SDK introduces the following action enumeration members: * `Action.AddTab` + Show, disable, or hide the **Add Tab** action on a Liveboard. @@ -1213,10 +1342,10 @@ For more information, see xref:Action.adoc[Actions]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. +|[tag greenBackground]#NEW# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: +|[tag greenBackground]#NEW# a| The SDK introduces the following action enumeration members: * `Action.RenameModalTitleDescription` * `Action.EnableContextualChangeAnalysis` @@ -1230,22 +1359,22 @@ For more information, see xref:Action.adoc[Actions]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. -|[tag greenBackground]#NEW FEATURE# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. +|[tag greenBackground]#NEW# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. +|[tag greenBackground]#NEW# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. |==== == Version 1.23.0, August 2023 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + +|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: + * Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. * Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. |==== //// -|[tag greenBackground]#NEW FEATURE# a| New events for Liveboard filters + +|[tag greenBackground]#NEW# a| New events for Liveboard filters + * `EmbedEvent.FilterChanged` + * `HostEvent.GetFilters` + @@ -1256,18 +1385,18 @@ For more information, see xref:Action.adoc[Actions]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. +|[tag greenBackground]#NEW# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. +|[tag greenBackground]#NEW# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. |==== //// -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + +|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: + * Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. * Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. @@ -1276,7 +1405,7 @@ For more information, see xref:security-settings.adoc#_block_access_to_non_embed == Version 1.21.0, May 2023 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following action enumeration members: +|[tag greenBackground]#NEW# a|The new version of the SDK introduces the following action enumeration members: * `Action.AxisMenuAggregate` * `Action.AxisMenuConditionalFormat` @@ -1295,7 +1424,7 @@ For more information, see xref:security-settings.adoc#_block_access_to_non_embed For more information, see xref:embed-action-ref.adoc[Action reference]. -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following events: +|[tag greenBackground]#NEW# a| The SDK introduces the following events: * `HostEvent.AddColumns` * `HostEvent.OpenFilter` @@ -1336,7 +1465,7 @@ To disable or hide download actions, you can use `Action.Download` in the `disab ** `Action.DownloadAsXlsx` + ** `Action.DownloadAsPng` -|[tag greenBackground]#NEW FEATURE# a| The SDK includes new attributes to customize the experience for embedded app users: +|[tag greenBackground]#NEW# a| The SDK includes new attributes to customize the experience for embedded app users: * `linkOverride` + @@ -1349,7 +1478,7 @@ Allows triggering contextual menu on the Liveboard visualizations and Answers fr * `hideSearchBar` + Allows hiding the Search bar on the embedded Search page. -|[tag greenBackground]#NEW FEATURE# | The SDK now allows setting the loading preference for embedded iFrames. +|[tag greenBackground]#NEW# | The SDK now allows setting the loading preference for embedded iFrames. For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. |==== @@ -1358,14 +1487,14 @@ For performance optimization, you can set the `loading` attribute to `lazy` in t [width="100%" cols="1,4"] |==== |[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. -|[tag greenBackground]#NEW FEATURE# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. +|[tag greenBackground]#NEW# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. |==== == Version 1.19.0, February 2023 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. +|[tag greenBackground]#NEW# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. For more information, see xref:css-customization.adoc[Customize CSS]. |[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: @@ -1380,7 +1509,7 @@ liveboardEmbed.on(EmbedEvent.CustomAction, payload => { You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following Host events: +|[tag greenBackground]#NEW# a|The new version of the SDK introduces the following Host events: * `HostEvent.Delete` * `HostEvent.Download` @@ -1405,17 +1534,17 @@ For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + +|[tag greenBackground]#NEW# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + +|[tag greenBackground]#NEW# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag greenBackground]#NEW FEATURE# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + +|[tag greenBackground]#NEW# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + For more information, see xref:HostEvent.adoc#_gettml[GetTML]. -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following enums in the `Action` object: +|[tag greenBackground]#NEW# a| The new version of the SDK introduces the following enums in the `Action` object: * `Action.SyncToOtherApps` + * `Action.SyncToSheets` + @@ -1441,9 +1570,9 @@ The new version of the SDK introduces several new features and enhancements. * `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + * `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + This enhancement does not introduce any breaking changes to your current implementation. -|[tag greenBackground]#NEW FEATURE# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + +|[tag greenBackground]#NEW# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + For more information, see xref:embed-authentication.adoc[Authentication]. -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + For more information, see xref:css-customization.adoc[Customize CSS]. |==== @@ -1455,7 +1584,7 @@ The new version of the SDK includes bug fixes and improvements to the new Livebo == Version 1.15.1, September 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. |==== @@ -1463,12 +1592,12 @@ For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources == Version 1.15.0, September 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: +|[tag greenBackground]#NEW# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: * CopyLink * CreateMonitor @@ -1493,7 +1622,7 @@ For more information, see xref:events-hostEvents.adoc[Events reference]. == Version 1.14.0, August 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. |[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. @@ -1503,13 +1632,13 @@ The earlier versions of the SDK supported only `GET` API requests. For more info == Version 1.13.0, July 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. -|[tag greenBackground]#NEW FEATURE#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + +|[tag greenBackground]#NEW#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. |[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + This change does not impact your current embed implementation with `AuthType.SSO`. -|[tag greenBackground]#NEW FEATURE#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + +|[tag greenBackground]#NEW#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + For more information, see xref:events-hostEvents.adoc[Events reference]. |==== @@ -1517,11 +1646,11 @@ For more information, see xref:events-hostEvents.adoc[Events reference]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. For more information, see xref:events-hostEvents.adoc[Events reference]. -|[tag greenBackground]#NEW FEATURE# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. +|[tag greenBackground]#NEW# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. |==== == Version 1.11.2, June 2022 @@ -1532,14 +1661,14 @@ Bug fix for Typescript builds that affect Angular project configurations. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. +|[tag greenBackground]#NEW#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. |==== == Version 1.11.0, May 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK includes the following new events: +|[tag greenBackground]#NEW# a| The new version of SDK includes the following new events: * `ALL` * `AnswerChartSwitcher` @@ -1565,16 +1694,16 @@ Bug fix for Typescript builds that affect Angular project configurations. * `VizPointClick` For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. +|[tag greenBackground]#NEW# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. -|[tag greenBackground]#NEW FEATURE# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. +|[tag greenBackground]#NEW# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. For more information, see xref:embed-actions.adoc[Show or hide UI actions]. |==== == Version 1.10.4, May 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. +|[tag greenBackground]#NEW#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. |==== == Version 1.10.3, May 2022 @@ -1583,14 +1712,14 @@ Bug fix and improvements to the `logout` method. == Version 1.10.2, May 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. +|[tag greenBackground]#NEW#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. |==== == Version 1.10.1, May 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#|You can now use the `logout` method to log out embed users. +|[tag greenBackground]#NEW#|You can now use the `logout` method to log out embed users. |[tag orangeBackground]#MODIFIED# a| Note the following changes: + * You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. @@ -1601,14 +1730,14 @@ Bug fix and improvements to the `logout` method. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. +|[tag greenBackground]#NEW# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. |==== == Version 1.9.8, April 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. +|[tag greenBackground]#NEW#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. For more information, see xref:full-embed.adoc[Embed full application]. |==== @@ -1620,7 +1749,7 @@ Bug fixes and improvements == Version 1.9.5, April 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. +|[tag greenBackground]#NEW#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. For more information, see xref:locale-setting.adoc[Set locale and display language]. |==== @@ -1632,7 +1761,7 @@ Bug fixes and improvements to React components. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + +|[tag greenBackground]#NEW#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. @@ -1642,7 +1771,7 @@ For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Auth == Version 1.9.2, March 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| You can now trigger events on React components using the `useEmbedRef` hook. +|[tag greenBackground]#NEW#| You can now trigger events on React components using the `useEmbedRef` hook. For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. |==== @@ -1650,11 +1779,11 @@ For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a Re == Version 1.9.1, March 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. +|[tag greenBackground]#NEW#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. -|[tag greenBackground]#NEW FEATURE# a| The following events are now available in the SDK: + +|[tag greenBackground]#NEW# a| The following events are now available in the SDK: + * `LiveboardRendered` (EmbedEvent) @@ -1664,7 +1793,7 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. == Version 1.9.0, March 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The SDK now includes the following new enumerations for UI actions: +|[tag greenBackground]#NEW# a| The SDK now includes the following new enumerations for UI actions: * `Action.AnswerDelete` + * `Action.AnswerChartSwitcher` + @@ -1673,7 +1802,7 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. -|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. +|[tag greenBackground]#NEW# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. |==== == Version 1.8.x, February 2022 @@ -1681,7 +1810,7 @@ For more information, see xref:embed-actions.adoc#standard-actions[Show or hide [width="100%" cols="1,4"] |==== |[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. -|[tag greenBackground]#NEW FEATURE# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. +|[tag greenBackground]#NEW# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. |==== @@ -1690,12 +1819,12 @@ For more information, see xref:embed-actions.adoc#standard-actions[Show or hide [width="100%" cols="1,4"] |==== | -[tag greenBackground]#NEW FEATURE# |+++
OIDC AuthType
+++ +[tag greenBackground]#NEW# |+++
OIDC AuthType
+++ The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ +|[tag greenBackground]#NEW# a|+++
Embed events
+++ The SDK includes the following new event: @@ -1709,7 +1838,7 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|+++
Visible actions
+++ +|[tag greenBackground]#NEW# a|+++
Visible actions
+++ You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. @@ -1719,7 +1848,7 @@ For more information, see xref:embed-actions.adoc[Show or hide UI actions]. The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ +|[tag greenBackground]#NEW# a|+++
Embed events
+++ The SDK supports the following new events: @@ -1734,17 +1863,17 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. [width="100%" cols="1,4"] |==== || -|[tag greenBackground]#NEW FEATURE# | +++
Render embedded objects in queue
+++ +|[tag greenBackground]#NEW# | +++
Render embedded objects in queue
+++ The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. -|[tag greenBackground]#NEW FEATURE# a|+++
Liveboard embed
+++ +|[tag greenBackground]#NEW# a|+++
Liveboard embed
+++ The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. For more information, see xref:embed-search.adoc[Embed a pinboard]. -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ +|[tag greenBackground]#NEW# a|+++
Embed events
+++ The SDK EmbedEvent library includes the following new events: @@ -1761,19 +1890,19 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. [width="100%" cols="1,4"] |==== || -|[tag greenBackground]#NEW FEATURE# a|+++
+++Prefetch API+++
+++ +|[tag greenBackground]#NEW# a|+++
+++Prefetch API+++
+++ The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. -|[tag greenBackground]#NEW FEATURE# a|+++
+++In-app page navigation+++
+++ +|[tag greenBackground]#NEW# a|+++
+++In-app page navigation+++
+++ The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. -|[tag greenBackground]#NEW FEATURE# a|+++
+++Full application embedding+++
+++ +|[tag greenBackground]#NEW# a|+++
+++Full application embedding+++
+++ The `appEmbed` SDK package includes the following new attributes: @@ -1783,7 +1912,7 @@ The `appEmbed` SDK package includes the following new attributes: For more information, see xref:full-embed.adoc[Embed full application]. -|[tag greenBackground]#NEW FEATURE# |+++
+++Search embed +++
+++ +|[tag greenBackground]#NEW# |+++
+++Search embed +++
+++ The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. @@ -1792,7 +1921,7 @@ For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. |[tag redBackground]#REMOVED# | The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. -|[tag greenBackground]#NEW FEATURE# a|+++
+++Embed events +++
+++ +|[tag greenBackground]#NEW# a|+++
+++Embed events +++
+++ The SDK EmbedEvent library includes the following events: * `QueryChanged` @@ -1806,7 +1935,7 @@ For more information, see xref:embed-events.adoc[Events and app integration]. [width="100%" cols="1,4"] |==== || -|[tag greenBackground]#NEW FEATURE# a| +++
searchOptions
+++ +|[tag greenBackground]#NEW# a| +++
searchOptions
+++ The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: @@ -1826,13 +1955,13 @@ The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in th For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. -|[tag greenBackground]#NEW FEATURE# a| +++
autoLogin
+++ +|[tag greenBackground]#NEW# a| +++
autoLogin
+++ The SDK now supports logging in users automatically after a user session has expired. For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. -|[tag greenBackground]#NEW FEATURE# a| +++
shouldEncodeUrlQueryParams
+++ +|[tag greenBackground]#NEW# a| +++
shouldEncodeUrlQueryParams
+++ You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. |[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ @@ -1851,16 +1980,16 @@ Includes user information such as username, GUID of the user, and email address. To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. -|[tag greenBackground]#NEW FEATURE# a| +++
preventPinboardFilterRemoval
+++ +|[tag greenBackground]#NEW# a| +++
preventPinboardFilterRemoval
+++ The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. -|[tag greenBackground]#NEW FEATURE# a| +++
suppressNoCookieAccessAlert
+++ +|[tag greenBackground]#NEW# a| +++
suppressNoCookieAccessAlert
+++ You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. -|[tag greenBackground]#NEW FEATURE# a| +++
Support for fetching callback custom action payload in batches
+++ +|[tag greenBackground]#NEW# a| +++
Support for fetching callback custom action payload in batches
+++ The Visual Embed SDK now supports processing data in batches for callback custom action responses. The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. @@ -1872,13 +2001,13 @@ For more information, see xref:push-data-to-external-app.adoc#large-dataset[Call [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|+++
SAML authentication
+++ +|[tag greenBackground]#NEW# a|+++
SAML authentication
+++ The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. -|[tag greenBackground]#NEW FEATURE# a|+++
Pinboard actions
+++ +|[tag greenBackground]#NEW# a|+++
Pinboard actions
+++ The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. Pinboard:: @@ -1894,7 +2023,7 @@ Pinboard:: [NOTE] Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. -|[tag greenBackground]#NEW FEATURE# a|+++
Visualization actions
+++ +|[tag greenBackground]#NEW# a|+++
Visualization actions
+++ Visualizations on a pinboard: @@ -1915,7 +2044,7 @@ Users with edit permissions can view and access the *Edit* action. The *Download [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|+++
NoCookieAccess event
+++ +|[tag greenBackground]#NEW# a|+++
NoCookieAccess event
+++ When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index c65bdd872..be62fc249 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -7,26 +7,31 @@ [.sidebar-title] Embed ThoughtSpot in a web app -* link:{{navprefix}}/getting-started[Embed with Visual Embed SDK] -* link:{{navprefix}}/tsembed[Quickstart guide] -* link:{{navprefix}}/embed-ai-search-analytics[Embed AI Search and Analytics] -** link:{{navprefix}}/embed-spotter[Embed Spotter experience] -*** link:{{navprefix}}/customize-spotter-embed[Customize Spotter interface] -** link:{{navprefix}}/embed-spotter-agent[Embed Spotter Agent] -* link:{{navprefix}}/embed-liveboard[Embed Analytics] +* link:{{navprefix}}/tsembed[Embed with Visual Embed SDK] +* link:{{navprefix}}/getting-started[Get started] +* link:{{navprefix}}/embed-ai-search-analytics[Embed Spotter AI Analytics] +** link:{{navprefix}}/embed-spotter[Embed full Spotter experience] +** link:{{navprefix}}/customize-spotter-embed[Customize Spotter interface] +** link:{{navprefix}}/customize-spotter-chat-experience[Customize chat experience] +** link:{{navprefix}}/customize-spotter-sidebar[Customize sidebar panel] +** link:{{navprefix}}/customize-spotter-sharing[Customize conversation sharing experience] +** link:{{navprefix}}/customize-spotter-analysts[Configure Spotter Analysts] +** link:{{navprefix}}/embed-spotter-agent[Embed Spotter AI without ThoughtSpot UI] +* Embed charts and Liveboards ** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] ** link:{{navprefix}}/spotterViz-agent[SpotterViz AI agent in Liveboards] ** link:{{navprefix}}/embed-a-viz[Embed a visualization] * link:{{navprefix}}/full-embed[Embed full application] ** link:{{navprefix}}/full-app-customize[Customize your embed] ** link:{{navprefix}}/customize-nav-controls[Customize navigation panels] -** link:{{navprefix}}/set-default-page[Customize default page and navigation path] +** link:{{navprefix}}/set-default-page[Set default landing page and navigation] ** link:{{navprefix}}/customize-homepage-experience[Customize home page experience] * Embed token-based Search ** link:{{navprefix}}/search-embed[Embed Search] ** link:{{navprefix}}/embed-searchbar[Embed search bar] ** link:{{navprefix}}/visualization-overrides[Visualization overrides] * link:{{navprefix}}/react-app-embed[Embed with React components] +* +++Visual Embed Playground+++ [.sidebar-title] Embed ThoughtSpot in a mobile app @@ -110,7 +115,6 @@ Customize and integrate * link:{{navprefix}}/set-locale[Customize locale] * link:{{navprefix}}/custom-domain-config[Custom domain configuration] * link:{{navprefix}}/customize-emails[Customize onboarding settings] -* link:{{navprefix}}/customize-email-apis[Customize email template] * link:{{navprefix}}/in-app-navigation[Create dynamic menus and navigation] * link:{{navprefix}}/best-practices[Performance optimization] ** link:{{navprefix}}/best-practices[Best practices] @@ -120,10 +124,7 @@ Customize and integrate * link:{{navprefix}}/troubleshoot-errors[Troubleshoot errors] -[.sidebar-title] -Embedding tutorials -* link:{{navprefix}}/tutorials/tutorials-overview[Embedding tutorials] //// * link:{{navprefix}}/tutorials/tse-fundamentals/intro[Embedding Fundamentals] @@ -158,7 +159,6 @@ Embedding tutorials [.sidebar-title] Reference guides and changelog -* +++Visual Embed Playground+++ * link:{{navprefix}}/VisualEmbedSdk[Visual Embed SDK Reference] include::generated/typedoc/CustomSideNav.adoc[] ** Custom styles @@ -181,6 +181,11 @@ include::generated/typedoc/CustomSideNav.adoc[] ** link:{{navprefix}}/embed-sdk-changelog[Visual Embed SDK] ** link:{{navprefix}}/mobile-sdk-changelog[Mobile Embed SDK] +[.sidebar-title] +Embedding tutorials + +* link:{{navprefix}}/tutorials/tutorials-overview[Embedding tutorials] + [.sidebar-title] Additional resources diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index fa6735fc8..3e46d801a 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -29,17 +29,22 @@ Embed ThoughtSpot in a web app * link:{{navprefix}}/getting-started[Embed with Visual Embed SDK] * link:{{navprefix}}/tsembed[Quickstart guide] -* link:{{navprefix}}/embed-ai-search-analytics[Embed AI Search and Analytics] -** link:{{navprefix}}/embed-spotter[Embed Spotter experience] -** link:{{navprefix}}/embed-spotter-agent[Embed Spotter Agent] -* link:{{navprefix}}/embed-liveboard[Embed Analytics] +* link:{{navprefix}}/embed-ai-search-analytics[Embed Spotter AI Analytics] +** link:{{navprefix}}/embed-spotter[Embed full Spotter experience] +** link:{{navprefix}}/customize-spotter-embed[Customize Spotter interface] +** link:{{navprefix}}/customize-spotter-chat-experience[Customize chat experience] +** link:{{navprefix}}/customize-spotter-sidebar[Customize sidebar panel] +** link:{{navprefix}}/customize-spotter-sharing[Customize conversation sharing experience] +** link:{{navprefix}}/customize-spotter-analysts[Configure Spotter Analysts] +** link:{{navprefix}}/embed-spotter-agent[Embed Spotter AI without ThoughtSpot UI] +* link:{{navprefix}}/embed-liveboard[Embed live analytics] ** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] ** link:{{navprefix}}/spotterViz-agent[SpotterViz AI agent in Liveboards] ** link:{{navprefix}}/embed-a-viz[Embed a visualization] * link:{{navprefix}}/full-embed[Embed full application] ** link:{{navprefix}}/full-app-customize[Customize your embed] ** link:{{navprefix}}/customize-nav-controls[Customize navigation panels] -** link:{{navprefix}}/set-default-page[Customize default page and navigation path] +** link:{{navprefix}}/set-default-page[Set default landing page and navigation] ** link:{{navprefix}}/customize-homepage-experience[Customize home page experience] * Embed token-based Search ** link:{{navprefix}}/search-embed[Embed Search] @@ -225,6 +230,11 @@ REST APIs ** link:{{navprefix}}/report-apis[Report APIs] ** link:{{navprefix}}/spotter-api[Spotter APIs] *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] +*** link:{{navprefix}}/spotter-agent-conversation-apis[Spotter agent conversation APIs] +*** link:{{navprefix}}/spotter-agent-streaming-apis[Spotter agent streaming APIs] +*** link:{{navprefix}}/spotter-agent-process-results-apis[Process Spotter agent conversation results] +*** link:{{navprefix}}/spotter-agent-data-literacy-apis[Spotter agent data literacy APIs] +*** link:{{navprefix}}/spotter-agent-sharing-apis[Spotter agent conversation sharing APIs] *** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] *** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] *** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] diff --git a/modules/ROOT/pages/common/nav-release-notes.adoc b/modules/ROOT/pages/common/nav-release-notes.adoc index 061b9ec4d..75c6a169b 100644 --- a/modules/ROOT/pages/common/nav-release-notes.adoc +++ b/modules/ROOT/pages/common/nav-release-notes.adoc @@ -5,13 +5,12 @@ [navSection] [.sidebar-title] -Release notes and changelogs +Release notes * link:{{navprefix}}/whats-new[What's new] -* Changelog -** link:{{navprefix}}/embed-sdk-changelog[Visual Embed SDK changelog] -** link:{{navprefix}}/mobile-sdk-changelog[Mobile Embed SDK changelog] -** link:{{navprefix}}/rest-v2-changelog[REST API v2 changelog] -** link:{{navprefix}}/mcp-server-changelog[Spotter MCP Server changelog] +* link:{{navprefix}}/embed-sdk-changelog[Visual Embed SDK changelog] +* link:{{navprefix}}/mobile-sdk-changelog[Mobile Embed SDK changelog] +* link:{{navprefix}}/rest-v2-changelog[REST API v2 changelog] +* link:{{navprefix}}/mcp-server-changelog[Spotter MCP Server changelog] * link:{{navprefix}}/deprecated-features[Deprecation announcements] diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index 8eaa925be..4672e98ce 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -9,42 +9,59 @@ REST APIs * link:{{navprefix}}/rest-apis[Overview] * link:{{navprefix}}/rest-apiv2-getstarted[Get started] -* link:{{navprefix}}/api-authv2[REST API v2.0 authentication] * link:{{navprefix}}/rest-v2-changelog[REST API v2 changelog] * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fgetting-started%2Fintroduction[REST API v2 Playground] * link:{{navprefix}}/rest-apiv2-reference[REST API v2.0 Reference] +* Authentication and administration +** link:{{navprefix}}/api-authv2[REST API v2.0 authentication] ** link:{{navprefix}}/api-user-management[Users and group privileges] ** link:{{navprefix}}/rbac[Role-based access control] +** link:{{navprefix}}/audit-logs[Audit logs] + +* Search APIs ** link:{{navprefix}}/rest-apiv2-search[Search API endpoints] -*** link:{{navprefix}}/rest-apiv2-users-search[Search users] -*** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] -*** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] +** link:{{navprefix}}/rest-apiv2-users-search[Search users] +** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] +** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] + +* Data and report APIs ** link:{{navprefix}}/fetch-data-and-report-apis[Data APIs] ** link:{{navprefix}}/report-apis[Report APIs] ** link:{{navprefix}}/runtime-sort[Runtime sorting] -** link:{{navprefix}}/spotter-api[Spotter APIs] -*** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] -*** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] -*** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] -*** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] -*** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic) ^BETA^] -*** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^] -** link:{{navprefix}}/audit-logs[Audit logs] -** link:{{navprefix}}/tml[TML] -*** link:{{navprefix}}/tml-import[Import TML] -*** link:{{navprefix}}/tml-export[Export TML] ** link:{{navprefix}}/collections[Collections] + + +* link:{{navprefix}}/webhooks-rest-api[Webhook APIs] + +* link:{{navprefix}}/spotter-api[Spotter APIs] +** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] +** link:{{navprefix}}/spotter-agent-conversation-apis[Spotter agent conversation APIs] +** link:{{navprefix}}/spotter-agent-streaming-apis[Spotter agent streaming APIs] +** link:{{navprefix}}/spotter-agent-process-results-apis[Process Spotter agent conversation results] +** link:{{navprefix}}/spotter-agent-data-literacy-apis[Spotter agent data literacy APIs] +** link:{{navprefix}}/spotter-agent-sharing-apis[Spotter agent conversation sharing APIs] +** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] +** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] +** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] +** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic) ^BETA^] +** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^] + +* Data connection and modelling APIs ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] +** link:{{navprefix}}/tml[TML] +** link:{{navprefix}}/tml-import[Import TML] +** link:{{navprefix}}/tml-export[Export TML] ** link:{{navprefix}}/manual-translation-api[Manual translations] -** link:{{navprefix}}/style-customization-apis[Style customization APIs] -** link:{{navprefix}}/webhooks-rest-api[Webhook APIs] +* Customization +** link:{{navprefix}}/style-customization-apis[Style customization APIs] +** link:{{navprefix}}/customize-email-apis[Customize email template] [.sidebar-title] REST API SDK -* link:{{navprefix}}/rest-api-sdk[Overview] +* link:{{navprefix}}/rest-api-sdk-libraries[Overview] * link:{{navprefix}}/rest-api-sdk-typescript[TypeScript SDK] * link:{{navprefix}}/rest-api-sdk-java[Java SDK] * link:{{navprefix}}/python-sdk[Python SDK] @@ -69,9 +86,9 @@ REST API tutorial REST API v1 (DEPRECATED) * link:{{navprefix}}/rest-api-getstarted[Get started] -* link:{{navprefix}}/api-auth-session[REST API v1 authentication] -* link:{{navprefix}}/catalog-and-audit[Catalog and audit content] -* link:{{navprefix}}/rest-api-pagination[Paginate API response] +//* link:{{navprefix}}/api-auth-session[REST API v1 authentication] +//* link:{{navprefix}}/catalog-and-audit[Catalog and audit content] +//* link:{{navprefix}}/rest-api-pagination[Paginate API response] * link:{{navprefix}}/rest-api-reference[REST API v1 Reference] * link:{{navprefix}}/rest-v1-changelog[REST API v1 changelog] * link:{{navprefix}}/v1v2-comparison[REST v1 and v2.0 comparison] diff --git a/modules/ROOT/pages/connection-config.adoc b/modules/ROOT/pages/connection-config.adoc index 3dfcc186b..c39852647 100644 --- a/modules/ROOT/pages/connection-config.adoc +++ b/modules/ROOT/pages/connection-config.adoc @@ -51,6 +51,7 @@ In your `POST` request body, include the following parameters: * `SAGE_INDEXING` * `ROW_COUNT_STATS` +* `SCHEDULED_LIVEBOARDS` |===== diff --git a/modules/ROOT/pages/customize-links.adoc b/modules/ROOT/pages/customize-links.adoc index 310b00311..7c92d9edb 100644 --- a/modules/ROOT/pages/customize-links.adoc +++ b/modules/ROOT/pages/customize-links.adoc @@ -23,16 +23,16 @@ An Answer link is generated when a user shares an Answer with another user and i SpotIQ analyses links:: ThoughtSpot generates this link when a user runs the SpotIQ analysis on the data generated from a search query, saved Answer, or a visualization pinned to a Liveboard. This link points users to the *SpotIQ Analyses* page and is also sent in email notifications. - Links to unsubscribe from notifications:: -+ The *Unsubscribe* link is included in system-generated emails to allow users to turn off email notifications. * The *Unsubscribe* link is included in object share and Liveboard notifications. By default, the *Unsubscribe* link in these notifications points users to the *Profile* settings page in ThoughtSpot, using which they can turn off or enable email notifications. * If a user has subscribed to receive alerts for KPI charts, the email notifications include the *Unsubscribe* link. A user can click this link to unsubscribe from monitor alerts at any time. +Spotter conversation sharing link:: +The conversation sharing link is generated when a user shares a Spotter conversation from an embedded interface. Recipients use this link to open the shared conversation in the host application. + Generic link:: -+ The *Generic* link allows you to customize navigation links in your application that are not parameterized. For example, the top navigation menu links in your embedded application can be customized as *Generic link*. == Create dynamic routes for ThoughtSpot pages in embedding app @@ -65,7 +65,7 @@ xref:embed-search.adoc[SearchEmbed] component to an existing Answer: `{web-app-name}.{your-domain}.com/analytics/report/*{answerId}*` -== Link format for an embedded instance +== Link format for embedded views By default, ThoughtSpot generates these links with URL paths from the ThoughtSpot application context. If you have embedded ThoughtSpot in your application, you might want to generate links with the URL and resource paths from your host application context. For example, if your host app URL is `\https://www.mysite.com`, you may want to generate a Liveboard link with your host application URL instead of the standard ThoughtSpot portal URL. You can customize the format of system-generated links in the *Link settings* page of the *Develop* tab. @@ -198,6 +198,22 @@ https://www.mysite.com/?unsubscribe ---- + +[#conversation-share-link] +Spotter conversation sharing URL:: +If your deployment embeds Spotter, you can customize the conversation share link so that recipients open the shared conversation in your application instead of the ThoughtSpot standalone application. ++ +The conversation share link format string must include both of the following placeholders: + +* `{conversation-id}`: Replaced with the ID of the shared conversation when the link is generated. +* `{ts-query-params}`: Replaced with the query parameters that ThoughtSpot appends to the link. + ++ +The placeholders must be specified in the `\https://{your-app-domain}/{path}/{conversation-id}?{ts-query-params}` format. For example, `\https://myapp.example.com/analytics/shared/{conversation-id}?{ts-query-params}`. + ++ +When a user shares a conversation from an embedded Spotter interface, ThoughtSpot generates the recipient's link from the configured format string. On that page, your application reads the conversation ID from the URL and passes it to the embed in the `sharedConversationId` property of the `SpotterEmbed` configuration. The embed then opens the shared conversation directly in the read-only view and the recipient lands in the host application page defined in the template, with the shared conversation's ID in the URL path. For more information about the conversation sharing configuration, see xref:customize-spotter-sharing.adoc#_customizing_conversation_sharing_link[Customizing Spotter conversation sharing link]. + + [#genericLink] Generic link:: diff --git a/modules/ROOT/pages/customize-spotter-analysts.adoc b/modules/ROOT/pages/customize-spotter-analysts.adoc new file mode 100644 index 000000000..2c2a8ad59 --- /dev/null +++ b/modules/ROOT/pages/customize-spotter-analysts.adoc @@ -0,0 +1,94 @@ += Configure Spotter Analysts +:toc: true +:toclevels: 2 + +:page-title: Customizing Spotter Analysts in the embedded view +:page-pageid: customize-spotter-analysts +:page-description: You can customize the Spotter Analysts panel and dashboard using the customization options available in the Visual Embed SDK. + +Spotter Analysts are use-case-scoped AI analysts that bring governed, pre-configured natural language analytics to your embedded applications. + +== Overview +Instead of showing a blank Spotter prompt and expecting users to pick the right data source and ask the correct questions to get the right answers, you can provide them with a pre-configured, governed Analyst that is scoped with the right data context. With the data pre-scoped to what the team is allowed to access and the tools governed accordingly, every team member gets the same context without having to configure anything themselves. + +ThoughtSpot allows users to create and manage link:https://docs.thoughtspot.com/cloud/latest/spotter-analysts[Analysts, window=_blank] directly within the Spotter interface. Each Analyst is scoped to a data model and can be configured with custom instructions, tool restrictions, and conversation starter options. You can also set share permissions and administrative controls to determine who can access or modify the Analyst in the embedded view. + +[#_spotter_analysts] +== Spotter Analysts in the embedded view +When Spotter Analysts are enabled on your ThoughtSpot instance and xref:customize-spotter-sidebar.adoc[sidebar] is visible in the embedded view, the Analysts panel and dashboard are visible by default. The sidebar also includes the option to view a specific Analyst or open the dashboard to view all the available Analysts. + +=== Customizing the Analyst panel visibility +To control the visibility of the Spotter Analysts panel in the embedded sidebar, use the `SpotterAnalystSidebar` action ID in the `disabledActions` or `hiddenActions` array. + +The following example shows how to hide the Spotter Analysts panel from the embedded view: + +[source,JavaScript] +---- +const embed = new SpotterEmbed("#embed", { + // ...other Spotter embed configuration options + disabledActions: [ + Action.SpotterAnalystSidebar, + ], +}); +---- + +=== Control individual Analyst actions +When Analysts are enabled in the embedded view, you can show or hide specific menu actions using the following action IDs: + +[cols="1,3", options="header"] +|=== +| Action ID | Description + +| `Action.CreateAnalyst` +| Action ID for the *Create new* action for creating a new Spotter Analyst. + +| `Action.EditAnalyst` +| Action ID for the edit option for an existing Analyst. + +| `Action.CopyAnalyst` +| Action ID for the *Make a copy* action for duplicating an Analyst. + +| `Action.ShareAnalyst` +| Action ID for the share action for sharing an Analyst with other users. + +| `Action.DeleteAnalyst` +| Action ID for the delete option for removing an Analyst. +|=== + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + hiddenActions: [ + Action.DeleteAnalyst, + ], +}); +---- + +=== Customizing label strings +If you want to replace the default "Analyst" or "Analysts" text with terminology that matches your application, use the `spotterAnalystLabel` and `spotterAnalystsLabel` locale customization strings. + +For example, you might want to use "AI Assistant" instead of "Analyst" in your embedded application: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + spotterSidebarConfig: { + // show sidebar panel + enablePastConversationsSidebar: true, + // Custom label for a single Analyst (default: "Analyst") + spotterAnalystLabel: 'AI Assistant', + // Custom label for the Analysts section heading (default: "Analysts") + spotterAnalystsLabel: "AI assistants", + }, +}); +---- + +== Additional resources +* link:https://docs.thoughtspot.com/cloud/latest/spotter-analysts[Spotter Analysts in product documentation, window=_blank] +* xref:customize-spotter-embed.adoc[Customizing the Spotter embed view] +* xref:api-changelog.adoc[Visual Embed SDK changelog] +* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] + + diff --git a/modules/ROOT/pages/customize-spotter-chat-experience.adoc b/modules/ROOT/pages/customize-spotter-chat-experience.adoc new file mode 100644 index 000000000..65c4fc7e2 --- /dev/null +++ b/modules/ROOT/pages/customize-spotter-chat-experience.adoc @@ -0,0 +1,293 @@ += Customize the Spotter chat experience +:toc: true +:toclevels: 2 + +:page-title: Customizing the Spotter chat experience +:page-pageid: customize-spotter-chat-experience +:page-description: You can customize the Spotter chat panel and conversational experience using the customization options available in the Visual Embed SDK. + +You can customize the chat panel and conversational experience using the customization controls available in the xref:SpotterEmbedViewConfig.adoc[SpotterEmbedViewConfig] and xref:SpotterChatViewConfig.adoc[SpotterChatViewConfig] interfaces. + +== Spotter chat interface +The chat experience in the embedded view varies according to the Spotter experience enabled in your Spotter embed. + +[width="100%" cols="5,7,7"] +[options="header"] +|==== +|Feature |Description |Availability + +|Data model selector +|Allows users to select a data model to set the context for their Spotter query. +Supports setting *All data models* to let Spotter automatically determine and select the data source. + +| +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag redBackground tick]#x# Spotter classic + +|Toggle to switch between Quick search and Deep analysis mode + +|Allows users to switch between the Quick search and Deep analysis mode in the Spotter interface. + +|[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +|Add files + +|Allows users to add files from their local directory to provide context for a Spotter query. Available under the *+* icon in the chat input area. + +| +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +|Connectors context + +|Allows users to add external connectors and set context for user queries based on the resources from these connectors. + + +In the new Spotter experience, this option is available under the *+* icon in the chat panel. + +| +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic +|Spotter starter prompts + +a|Preconfigured search questions that guide users by displaying clickable suggestion pills in the Spotter chat interface. Includes the following prompt pills: + +* Quick search +* Deep Analysis +* Know your data + +a| +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +|==== + +== Data model selection +To load the Spotter interface with a pre-selected data source, you must specify the data context in the `worksheetId` attribute. You can specify the GUID of the data model or `auto_mode` in the `worksheetId` attribute to enable *All data models* option so that Spotter can automatically discover and select a relevant data model for user queries. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + worksheetId: "auto_mode", + // ...other embed configuration attributes +}); +---- + +== Quick search and deep analysis mode +With Spotter 2 and Spotter 3 experience enabled in the embedded view, the Spotter page displays a toggle switch to allow users to switch between the link:https://docs.thoughtspot.com/cloud/latest/spotter-research-mode[quick search and deep analysis modes]. + +To show, hide, or disable this feature, use the action ID, `Action.SpotterChatModeSwitcher`. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + hiddenActions: [ + Action.SpotterChatModeSwitcher, + ], +}); +---- + +== Spotter starter prompts +Spotter starter prompts are preconfigured search questions that guide users when they first interact with Spotter. They provide curated starting points for data exploration by displaying clickable suggestion pills that help users understand what types of questions they can ask about their data. The starter prompts can be found below the prompt panel in the embedded Spotter page. + +Starter prompts can be automatically created by ThoughtSpot based on your data model or manually configured by developers to address specific business needs. The prompts are data-model-specific and their content dynamically changes according to the data source content being used by the user for their interaction with Spotter. + +=== Types of starter prompts +When included in the embedded interface, the Spotter page displays the following starter prompts pills: + +* *Quick search* + +Includes common queries that users frequently ask. These prompts help users get quick answers to standard business questions, such as top products, sales summaries, or regional breakdowns. + +* *Deep analysis* + +Includes complex analytical questions that require deeper investigation. These prompts guide users toward more sophisticated analysis, such as trend analysis, correlation studies, or root-cause analysis. + +* *Know your data* + +Users can use this feature to understand the data available to them. This category is useful for onboarding new users or introducing new datasets. + +=== Enabling Starter prompts in the embedded view +To enable starter prompts in the embedded page, set the `enableStarterPrompts` property in the `spotterChatConfig` object to `true`. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + spotterChatConfig: { + enableStarterPrompts: true, + }, +}); +---- + +//// +=== Customizing prompt pills and their contents +To customize the prompt pills and their contents, use the following properties in the `starterPrompts` object: + +* `quick` for the Quick search pill +* `research` for the Deep analysis pill +* `previewData` for the Know your data pill. + +The SDK allows you to customize the following properties of the starter prompt pills: + +* `label` + +__String__. Overrides the default pill label. +* `questions` + +__Array of strings__. For each question entry, you can customize the question label and add your own prompt text. Any entry without the `prompt` value is dropped. + +[IMPORTANT] +==== +For the `previewData` category, you can customize only the prompt pill `label` string. +==== + +==== Example + +[source,JavaScript] +---- +const embed = new SpotterEmbed('#tsEmbed', { + // ...other embed view configuration options + spotterChatConfig: { + enableStarterPrompts: true, + starterPrompts: { + quick: { + label: 'Sample questions', + questions: [ + { + label: 'Top products', + prompt: 'What are the top products by revenue?', + }, + ], + }, + research: { + label: 'Deep analysis', + questions: [ + { + label: 'Revenue drivers', + prompt: 'Analyze the main drivers of revenue changes', + }, + ], + }, + previewData: { + label: 'Explore your data', + }, + }, + }, +}); +---- + +=== Customizing the visibility of prompt pills +If you want to include or exclude any specific prompt pill, use the following action IDs with the `hiddenActions` or `visibleActions` array to control the visibility. + +* `Action.QuickSearchPill` for *Quick search* +* `Action.DeepAnalysisPill` for *Deep analysis* +* `Action.DataLiteracyPill` for *Know your data* + +[source,javascript] +---- +const embed = new SpotterEmbed('#tsEmbed', { + // ...other embed view configuration options + spotterChatConfig: { + enableStarterPrompts: true, + }, + hiddenActions: [Action.DeepAnalysisPill] +}); +---- +//// + + +[#fileUpload] +== File uploads in Spotter chats +The **Add files** option is available in the embedded view by default if your embed has Spotter 2 or Spotter 3 experience enabled. + +To customize the visibility of the **Add files** option, use `spotterFileUploadEnabled` in the `spotterChatConfig` object. + +You can also restrict the types of files users can upload by specifying file format in the `spotterFileUploadFileTypes` array. If no file format is specified, all supported file types are allowed for uploads. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed configuration attributes + updatedSpotterChatPrompt: true, + spotterChatConfig: { + spotterFileUploadEnabled: true, + spotterFileUploadFileTypes: ['pdf', 'png', 'xlsx'], + }, +}); +---- + +[#mcp-connectors] +== MCP connectors and resource selection +The ability to select external MCP connectors and resources for Spotter AI analytics is available when Spotter 3 experience is enabled in the embedded view. This integration allows your application users to include both structured and unstructured data in their conversation sessions. + +The **Manage connectors** icon in the chat panel allows users to select external connectors such as Google Drive, Slack, Notion, Confluence, Web search or Jira, as a data sources in their Spotter sessions. This list displays only the connectors that are preconfigured by the ThoughtSpot administrator. + +To show, hide, or disable the **Manage connectors** option, use the `Action.SpotterChatConnectors` action ID in the `hiddenActions` or `disabledActions` array. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + updatedSpotterChatPrompt: true, + hiddenActions: [ + Action.SpotterChatConnectors + ], +}); +spotterEmbed.render(); +---- + +== Spotter icon customization +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 link:https://github.com/thoughtspot/custom-css-demo/blob/main/alternate-spotter-icon.svg[alternate-spotter-icon.svg, window=_blank] file hosted on `\https://cdn.jsdelivr.net/` to override the Spotter icon. + +[source,JavaScript] +---- + 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: +[.widthAuto] +[.bordered] +image::./images/spotter-icon-customization.png[Spotter icon customization] + +== Spotter logo and ThoughtSpot branding label +To hide the Spotter logo and branding in the chat interface and tool response, use the following `SpotterChatViewConfig` object properties: + +* `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:: ++ +[source,JavaScript] +---- +import { + SpotterEmbed, + SpotterEmbedViewConfig, + SpotterChatViewConfig +} from '@thoughtspot/visual-embed-sdk'; + +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options + 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', + }, +}); +---- + +== Additional resources +* xref:customize-spotter-embed.adoc[Customizing the Spotter embed view] +* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] +* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] +* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] diff --git a/modules/ROOT/pages/customize-spotter-embed.adoc b/modules/ROOT/pages/customize-spotter-embed.adoc index 4dc6ed070..050177586 100644 --- a/modules/ROOT/pages/customize-spotter-embed.adoc +++ b/modules/ROOT/pages/customize-spotter-embed.adoc @@ -1,4 +1,4 @@ -= Customizing the Spotter embed view += Customize the Spotter embed view :toc: true :toclevels: 2 @@ -6,289 +6,85 @@ :page-pageid: customize-spotter-embed :page-description: You can customize the SpotterEmbed experience using the customization options available in the Visual Embed SDK. -When you xref:embed-spotter.adoc[embed Spotter] in your application, 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. +The Visual Embed SDK provides a vast set of configuration settings and object properties to customize the Spotter UI and chat experience for your embedding application users. -== Spotter UI -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 interface in the embedded view +When you xref:embed-spotter.adoc[embed Spotter] in your application, you'll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page varies depending on the Spotter version used for embedding. -== Spotter 3 experience -Spotter 3 experience is available with a new prompt interface that includes additional features and user elements to enrich your Spotter experience. +=== Default experience +The default experience in embedded view is the classic Spotter interface with an initial page that includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session. ++ +If Spotter 2 is enabled on your ThoughtSpot instance, additional controls such as Quick search and Deep analysis toggle switch, and the automatic data model selection option are available. ++ +[.widthAuto] +[.bordered] +image::./images/spotter-default-interface.png[Default Spotter interface] -To enable the new chat interface in your embed, set the `updatedSpotterChatPrompt` attribute: +=== Spotter 3 experience +If your ThoughtSpot instance has Spotter 3 experience enabled, you can enable the same experience in your embed, which includes additional options to add files, connectors, and improved conversational experience. To enable Spotter 3 experience, set `updatedSpotterChatPrompt` to `true` in the SDK. [source,JavaScript] ---- const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - // ...other embed configuration attributes + worksheetId: '', // Replace with GUID of the data source // Enable the updated Spotter chat prompt experience. updatedSpotterChatPrompt: true, + // Show chat history panel + spotterSidebarConfig: { + enablePastConversationsSidebar: true, + }, + // ...other embed configuration attributes }); ---- [.widthAuto] [.bordered] -image::./images/spotter3-new-interface.png[Spotter 3 new interface] +image::./images/spotter3-interface.png[Spotter 3 experience] -=== Spotter classic and Spotter 2 - -[.widthAuto] -[.bordered] -image::./images/spotter-embed-legacy.png[Spotter embed] - -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**: - -[.widthAuto] -[.bordered] -image::./images/spotter3-legacy-interface.png[Spotter 3 interface] - -**With Auto mode enabled**: - -[.widthAuto] -[.bordered] -image::./images/spotter3-leagcy-interface-automode.png[Spotter 3 interface] - -[NOTE] -==== -When Auto mode is enabled, **Preview data** and **Data Model instructions** options will not be available. -==== - -=== 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 and customize the chat history sidebar, configure the chat history properties in the `spotterSidebarConfig` object: +=== New Spotter3 visual experience +On instances with ThoughtSpot Cloud 26.9.0.cl, the new redesigned Spotter experience is enabled by default. The new Spotter experience includes the updated conversation layout and starter-prompt pills. To enable the new visual experience, set `updatedSpotterExperience` to `true` in the `SpotterEmbed` configuration. [source,JavaScript] ---- -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 +const spotterEmbed = new SpotterEmbed('#ts-embed', { + worksheetId: '', // Replace with GUID of the data source + // Enable Spotter 3 chat experience. + updatedSpotterChatPrompt: true, + // Enable new Spotter visual experience + updatedSpotterExperience: true, + // Show chat history panel spotterSidebarConfig: { - enablePastConversationsSidebar: true, // Enable the chat history sidebar - spotterSidebarDefaultExpanded: true, // Expand the sidebar by default - spotterSidebarTitle: 'Chat History', // Custom sidebar header text - spotterNewChatButtonTitle: 'New Conversation', // Custom label for the New chat button - spotterChatRenameLabel: 'Rename session', // Custom label for the Rename action - spotterChatDeleteLabel: 'Delete session', // Custom label for the Delete action - spotterConversationsBatchSize: 20, // Conversations fetched per batch (default: 30) - spotterDocumentationUrl: 'https://your-help-center-url', // Custom best practices link - }, -}) ----- - -[NOTE] -==== -The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` is deprecated from Visual Embed SDK v1.47.0. Use the `enablePastConversationsSidebar` property within the `spotterSidebarConfig` object instead. When both properties are defined, the value in `spotterSidebarConfig` takes precedence. -==== - -== Spotter Analysts -ThoughtSpot allows users to create and manage AI agents (Analysts) directly within the Spotter interface. These AI agents or bots are referred to as link:https://docs.thoughtspot.com/cloud/latest/spotter-analysts[Spotter Analysts, window=_blank]. Each Analyst is scoped to a data model and can be configured with custom instructions, personas, and conversation starters. - -If you have Spotter Analysts on your ThoughtSpot instance, you can make these available to your embedding application users. - -=== Spotter Analyst panel -If your ThoughtSpot instance has Spotter Analysts, the Spotter Analysts panel and dashboard are visible by default in the Spotter sidebar in the embed view. To control the visibility of this panel in the embed view, use the `SpotterAnalystSidebar` action ID in the `disabledActions`, `hiddenActions`, or `visibleActions` arrays as needed. - -If Spotter Analysts are enabled in the embed view, you can use the following action IDs to show or hide the menu actions: - -* `Action.CreateAnalyst` + -Action ID for the **Create new** action in the Spotter Analysts page. -* `Action.EditAnalyst` + -Action ID for the Analyst edit option. -* `Action.CopyAnalyst` + -Action ID for the *Make a copy* action that creates a copy of the Analyst. -* `Action.ShareAnalyst` + -Action ID for the share action that allows sharing an Analyst with other users. -* `Action.DeleteAnalyst` + -Action ID for the delete option. - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - // ...other embed view configuration options - hiddenActions: [ - Action.CreateAnalyst, - Action.DeleteAnalyst, - ], -}); ----- - -=== Analysts label strings -Use `spotterAnalystLabel` and `spotterAnalystsLabel` to replace the default "Analyst" and "Analysts" label text in the embedded Spotter interface with custom terminology suited to your application: - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - // ...other embed view configuration options - // Custom label for a single Analyst (default: "Analyst") - spotterAnalystLabel: 'AI Assistant', - // Custom label for the Analysts section heading (default: "Analysts") - spotterAnalystsLabel: 'AI Assistants', -}); ----- - -== Quick search and deep analysis mode -When Spotter 3 experience is enabled on a ThoughtSpot instance, the Spotter interface displays a switcher to toggle between the Quick Search and Deep Analysis modes. - -To show, hide, or disable this feature in the embedded view, use the action ID, -`Action.SpotterChatModeSwitcher`. - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - // ...other embed view configuration options - hiddenActions: [ - Action.SpotterChatModeSwitcher, - ], -}); ----- - -== Spotter starter prompts -ThoughtSpot allows users to preselect prompts and display these prompts in the Spotter interface for quick analysis. This feature is disabled by default in the embedded view. To enable this feature, contact ThoughtSpot Support. - -When this feature is enabled on your instance, you can use the `enableStarterPrompts` property in the `spotterChatConfig` object to display the starter prompts to your embedding application users. These prompts appear below the search bar when the users open the Spotter embedded view. - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - // ...other embed view configuration options - spotterChatConfig: { - enableStarterPrompts: true, - }, -}); ----- - -[#mcp-connectors] -== MCP connectors and resource selection icon -If the Spotter 3 interface is enabled, the Spotter page displays the following options to connect external tools and resources for AI analytics. - -* Connector icon that allows you to connect to external applications such as Google Drive, Slack, Notion, Confluence, or Jira, which can be used as a data source in Spotter sessions. These connectors must be preconfigured by your ThoughtSpot administrator for your embedding deployments. -* Add files (+) icon for uploading files and resources for setting the conversation context. -* **Connectors** menu with a `+` icon in the prompt panel that lets your application users connect to external tools and resources. - -These integrations allow users to include both structured and unstructured data in their conversation sessions. - -To show, hide, or disable these options, use the following action IDs in the `disabledActions`, `hiddenActions`, or `visibleActions` arrays as needed: - -* `Action.SpotterChatConnectors` for the Connectors list. -* `Action.SpotterChatConnectorResources` for the connector resources section. - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - // ...other embed view configuration options - hiddenActions: [ - Action.SpotterChatConnectors, - Action.SpotterChatConnectorResources, - ], -}); -spotterEmbed.render(); ----- - -[#fileUpload] -== File uploads in Spotter chats -To enable file uploads in the Spotter chat panel: - -. Ensure that `spotterFileUploadEnabled` is set to `true` in the `spotterChatConfig` object. This setting enables the **+ Add files** option in the Spotter chat panel. -. Optionally, you can restrict the types of files users can upload by specifying the file types in the `spotterFileUploadFileTypes` array. If no file format is specified, all supported file types are allowed for uploads. - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - //... - spotterChatConfig: { - spotterFileUploadEnabled: true, - spotterFileUploadFileTypes: ['pdf', 'png', 'xlsx'], - }, -}); ----- - -//// -For earlier SDK versions, you can use CSS selectors as a workaround: - -[source,JavaScript] ----- -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 + enablePastConversationsSidebar: true, + }, + // ...other embed configuration attributes }); ---- -//// - -== Spotter icon customization -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 link:https://github.com/thoughtspot/custom-css-demo/blob/main/alternate-spotter-icon.svg[alternate-spotter-icon.svg, window=_blank] file hosted on `\https://cdn.jsdelivr.net/` to override the Spotter icon. - -[source,JavaScript] ----- - 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: [.widthAuto] [.bordered] -image::./images/spotter-icon-customization.png[Spotter icon customization] +image::./images/spotter-new-experience.png[New Spotter experience] -== Spotter logo and ThoughtSpot branding label -To hide the Spotter logo and branding in the chat interface and tool response, use the following `SpotterChatViewConfig` object properties: +In the new experience, the + icon displays a menu with the following options: -* `hideToolResponseCardBranding` + -When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. +* **Add files** to files from local directory +* **Connectors** to select available connectors +* **Deep analysis** toggle to switch between the quick search and research mode. -* `toolResponseCardBrandingLabel` + -Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. +You can customize the chat panel and conversational experience further. For more information, see xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience]. -Example:: -+ -[source,JavaScript] ----- -import { - SpotterEmbed, - SpotterEmbedViewConfig, - SpotterChatViewConfig -} from '@thoughtspot/visual-embed-sdk'; +== Customizing Spotter experience +If you want to customize specific features or UI elements, refer to the following documentation: -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - // ...other embed view configuration options - 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', - }, -}); ----- +* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] + +For information on customizing the chat panel, data model selection, starter prompts, file uploads, MCP connectors, and Spotter branding. +* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] + +For information on customizing the sidebar panel and the chat history panel, including menu actions and app interactions. +* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] + +For information on customizing the conversation sharing experience, sharing links, and app interactions. +* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] + +For information on customizing the Spotter Analysts panel and dashboard. -== Styles and interface elements +== Customizing styles and interface elements using CSS variables 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 xref:css-customization.adoc[CSS customization framework], xref:customize-text-strings.adoc[Customize text strings], and xref:customize-icons.adoc[Customize icons] sections. @@ -320,7 +116,7 @@ init({ }); ---- -=== Text string customization +=== Customizing text strings To replace text strings, you can use the `stringIDs` and `strings` properties in the content customization object. The following example shows how to replace "Spotter" and other text strings on the Spotter interface. @@ -334,8 +130,6 @@ init({ 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", } @@ -344,26 +138,20 @@ init({ }); ---- +//// [#spotterMenuActions] === Menu elements and action visibility 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 xref:embed-actions.adoc[`disabledActions`] array: +For a comprehensive list of supported actions, see the xref:Action.adoc[Action reference documentation]. +//// -[source,JavaScript] ----- - // 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 xref:Action.adoc[Spotter menu actions]. == Additional resources -* xref:embed-ai-analytics.adoc[Spotter features and embedding options] +* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] +* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] +* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] +* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] * link:https://developers.thoughtspot.com/docs/Class_SpotterEmbed[SpotterEmbed classes and methods] * link:https://developers.thoughtspot.com/docs/Interface_SpotterEmbedViewConfig[Configuration options for Spotter interface customization] * link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/spotter/spotter-embed[Developer examples, window=_blank] diff --git a/modules/ROOT/pages/customize-spotter-sharing.adoc b/modules/ROOT/pages/customize-spotter-sharing.adoc new file mode 100644 index 000000000..ec48c0412 --- /dev/null +++ b/modules/ROOT/pages/customize-spotter-sharing.adoc @@ -0,0 +1,192 @@ += Customize conversation sharing experience +:toc: true +:toclevels: 2 + +:page-title: Customizing Spotter conversation sharing +:page-pageid: customize-spotter-sharing +:page-description: You can customize the Spotter conversation sharing experience using the customization options available in the Visual Embed SDK. + +Users can share their Spotter conversations with other users and groups from the embedded Spotter interface. + +[#_spotter_conversation_sharing] +== Spotter conversation sharing experience +Conversation sharing is turned off by default in embedded Spotter interface. To enable it, set `enableShareConversation` to `true` in the `spotterShareConversationConfig` object. This setting enables the *Share* action in the Spotter response page and the chat history panel in the sidebar, which allows a user to share a conversation with other users and groups in their application. The recipients can access a shared conversation only in a read-only view. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed('#ts-embed', { + // Enable conversation sharing + spotterShareConversationConfig: { + enableShareConversation: true, + }, + // ...other embed view configuration options +}); +---- + +== Customizing share modal and sharing settings +To customize the conversation sharing experience, use the following options in +the `SpotterShareConversationConfig` interface as needed: + +[width="100%", cols="5,7"] +[options='header'] +|===== +|Property |Description +|`enableShareConversation` |Enables conversation sharing in the embedded interface. Default is `false`. +|`spotterShareLabel` |Label of the *Share* button in the conversation header and the *Share* menu item in the sidebar. Default text is `Share`. +|`spotterShareModalTitle` | Title of the share modal. +|`spotterShareConfirmLabel` |Label of the confirm button in the share modal. Default label is `Share`. +|`spotterShareCancelLabel` |Label of the cancel button in the share modal. Default label is `Cancel`. +|`spotterShareAddUsersLabel` |Label of the recipient picker in the share modal. +|`spotterShareEmptyTitle` |Title text shown when the recipient picker is empty. +|`spotterShareEmptySubtitle` |Subtitle text shown when the recipient picker is empty. +|`spotterShareIncludeNewMessagesLabel` |Label of the checkbox that includes messages added since the last shared version. +|`spotterShareUpToCurrentLabel` |Footer note shown in the share modal when the shared snapshot is current. +|`spotterShareStaleInfoLabel` |Banner text shown in the share modal when the shared snapshot is stale. +|`spotterSharedConversationBannerMessage` |Data-access banner text shown in the read-only shared view. +|`spotterSharedConversationExitLabel` |Label of the *Exit* button in the read-only shared view. Default label is `Exit`. +|| +|===== + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed('#ts-embed', { + // Enable conversation sharing + spotterShareConversationConfig: { + enableShareConversation: true, + spotterShareAddUsersLabel: "Add recipients", + spotterShareIncludeNewMessagesLabel: "Include new messages", + }, + // ...other embed view configuration options +}); +---- + +== Customizing conversation sharing link +When a user shares a conversation from an embedded Spotter interface, the share link sent to recipients must open within your embedding application context and not direct recipients to the conversation page in the ThoughtSpot instance. + +To customize the URL for your application context, configure the conversation share link setting and then pass the conversation ID to your embed. + +=== Configure the conversation share link setting +To customize the conversation share link format: + +. Go to **Develop** > **Link settings** page in your ThoughtSpot application. +. Specify the conversation share link URL so that the links are generated in a URL format that is customized for your application's domain URL, with a placeholder for the shared conversation's ID. ++ +`\https://{your-app-domain}/{path}/{conversation-id}?{ts-query-params}` + ++ +For example: +`\https://myapp.example.com/analytics/shared/{conversation-id}?{ts-query-params}` + +If the conversation sharing link format is defined, ThoughtSpot replaces the `{conversation-id}` with the ID of the shared conversation and generates the link in the specified URL format, so the recipient is directed to the shared conversation page within their application context. + +For more information about customizing links in embedded deployments, see xref:customize-links.adoc[Customize links]. + +=== Pass the conversation ID to your embed +When the user shares a conversation, add the necessary code in your application to read the conversation ID from the page URL and pass it to `SpotterEmbed` in the `sharedConversationId` property. + +[source,JavaScript] +---- +const convId = new URLSearchParams(window.location.search).get('conversation-id'); +const embed = new SpotterEmbed('#tsEmbed', { + //... other embed view config + spotterShareConversationConfig: { + enableShareConversation: true, + }, + sharedConversationId: convId, +}) +---- + +When the `sharedConversationId` property is configured, the embed opens the shared conversation directly in the read-only view, for all recipients within your application. + +== Customizing the visibility of sharing UI elements +Use the following `Action` enum members in `hiddenActions` or `disabledActions` to control individual sharing UI elements: + +* `Action.SpotterShareConversationButtonHeader` for **Share** button in the Spotter conversation header. +* `Action.SpotterShareConversationMenuItemSidebar` for **Share** menu action in the chat history panel in the sidebar. +* `Action.SpotterShareIncludeNewMessagesCheckbox` for the `include new messages since last shared version` checkbox in the share modal. +* `SpotterSharedConversationBannerDismissButton` for the dismiss button of the data access banner displayed in the shared conversation view. +* `Action.SpotterShareUpToCurrentInfo` for the share modal footer note, "Chat will be shared up to the current moment…." +* `Action.SpotterSharedConversationBanner` for the data access banner shown when a recipient opens a shared conversation. +* `Action.SpotterShareStaleInfoBannerDismissButton` for the banner that shows the message, "This data may have changed since the last time you had a chat." +* `Action.SpotterSharedConversationExitButton` for *Exit* button in the read-only view of the shared conversation. + ++ +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed('#ts-embed', { + worksheetId: '', + spotterShareConversationConfig: { + enableShareConversation: true, + }, + // Allow sharing from the header only; hide the sidebar entry point + hiddenActions: [Action.SpotterShareConversationMenuItemSidebar,Action.SpotterShareUpToCurrentInfo], +}); +---- + +For a complete list action IDs, see xref:Action.adoc[Action reference]. + +== Customizing app interactions + +Use the following event IDs to enable interaction between the host and the embedded application: + +HostEvents:: +* `HostEvent.ShareSpotterConversation` + +Opens the Spotter share conversation modal for the given conversation ID. +* `HostEvent.ExitSpotterSharedConversation` + +Exits the read-only view of the shared conversation. +* `HostEvent.CloseSpotterShareConversation` + +Closes the Spotter share conversation modal. + ++ +[source,JavaScript] +---- +spotterEmbed.trigger(HostEvent.ShareSpotterConversation, { + conversationId: '', +}); +---- + ++ +For a complete list of event IDs, see xref:HostEvent.adoc[HostEvent reference]. + +EmbedEvents:: + +* `EmbedEvent.SpotterConversationShared` + +Emitted when a Spotter conversation is shared with the intended recipients. +* `EmbedEvent.SpotterConversationShareRevoked` + +Emitted when access to a shared Spotter conversation is revoked. +* `EmbedEvent.SpotterSharedConversationViewed` + +Emitted when a recipient opens a shared Spotter conversation. +* `EmbedEvent.SpotterShareConversationButtonHeaderClicked` + +Emitted when the Share button in the conversation header is clicked. +* `EmbedEvent.SpotterShareConversationMenuItemSidebarClicked` + +Emitted when the Share action in the menu displayed for a chat in the chat history sidebar. +* `SpotterShareIncludeNewMessagesCheckboxToggled` + +Emitted when the user toggles the "include new messages since last shared version" checkbox in the share modal. +* `EmbedEvent.SpotterShareModalCancelButtonClicked` + +Emitted when the Cancel button in the share conversation modal is clicked. +* `EmbedEvent.SpotterShareStaleInfoBannerDismissed`+ +Emitted when the user dismisses the banner that shows the text, "This data may have changed since the last time you had a chat." +* `EmbedEvent.SpotterSharedConversationExitButtonClicked` + +Emitted when a user exits the shared conversation read-only view. + ++ +[source,JavaScript] +---- +spotterEmbed.on(EmbedEvent.SpotterConversationShared, (payload) => { + console.log('Shared:', payload.shareId, payload.recipientsAdded); +}); + +spotterEmbed.on(EmbedEvent.SpotterConversationShareRevoked, (payload) => { + if (payload.fullyRevoked) { + console.log('All recipients removed'); + } +}); +---- + +For a complete list of event IDs, see xref:EmbedEvent.adoc[EmbedEvent reference]. + +== Additional resources +* xref:customize-spotter-embed.adoc[Customizing the Spotter embed view] +* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] +* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] +* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] diff --git a/modules/ROOT/pages/customize-spotter-sidebar.adoc b/modules/ROOT/pages/customize-spotter-sidebar.adoc new file mode 100644 index 000000000..288eee572 --- /dev/null +++ b/modules/ROOT/pages/customize-spotter-sidebar.adoc @@ -0,0 +1,166 @@ += Customize the Spotter sidebar panel +:toc: true +:toclevels: 2 + +:page-title: Customizing the Spotter sidebar panel +:page-pageid: customize-spotter-sidebar +:page-description: You can customize the sidebar panel in the Spotter embed, including the chat history panel, using the customization options available in the Visual Embed SDK. + +You can customize the Spotter sidebar panel and its contents using configuration properties available in the xref:SpotterSidebarViewConfig.adoc[SpotterSidebarViewConfig] interface. + +== Sidebar elements in the embedded view +The sidebar panel in the Spotter interface includes the following elements: + +[width="100%", cols="5,7,7"] +[options='header'] +|==== +|Feature |Description |Availability + +|Chat history sidebar + +|Allows users to access past chats from a sidebar and start a new conversation session. The chat history panel is disabled by default in the embedded view. +| +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag greenBackground tick]#✓# Spotter Classic + +|Spotter Analysts + +|Allows users to view the Spotter Analysts in the sidebar panel and open the Analysts dashboard. This feature is available by default in the embedded view. +For more information, see xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view]. + +| +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag greenBackground tick]#✓# Spotter Classic + +|Spotter best practices + +|Provides users with guidance and best practices for using Spotter effectively. + +| +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag greenBackground tick]#✓# Spotter Classic +|==== + +== Chat history panel +To allow your users to access the chat history from their previous sessions, you can enable the *Chat history* in the sidebar by setting the `enablePastConversationsSidebar` parameter to `true` in the `spotterSidebarConfig` object. You can also customize the default state and the labels as shown in this example: + +[source,JavaScript] +---- +const embed = new SpotterEmbed('#tsEmbed', { + // ...other embed view configuration options + // Configuration for the Spotter sidebar UI + spotterSidebarConfig: { + enablePastConversationsSidebar: true, // Enable the chat history sidebar + spotterSidebarDefaultExpanded: true, // Expand the sidebar by default + spotterSidebarTitle: 'Chat History', // Custom sidebar header text + spotterNewChatButtonTitle: 'New Conversation', // Custom label for the New chat button + spotterChatRenameLabel: 'Rename session', // Custom label for the Rename action + spotterChatDeleteLabel: 'Delete session', // Custom label for the Delete action + spotterConversationsBatchSize: 20, // Conversations fetched per batch (default: 30) + }, +}) +---- + +[NOTE] +==== +The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` is deprecated from Visual Embed SDK v1.47.0. Use the `enablePastConversationsSidebar` property within the `spotterSidebarConfig` object instead. When both properties are defined, the value in `spotterSidebarConfig` takes precedence. +==== + +=== Customizing sidebar menu actions +Use the following `Action` enum members in `hiddenActions` or `disabledActions` to control the visibility of individual chat history panel elements: + +* `Action.SpotterSidebarHeader` for the sidebar header, which includes the title and the expand/collapse toggle. Hide-only. +* `Action.SpotterSidebarToggle` for the expand/collapse toggle button on the sidebar. +* `Action.SpotterNewChat` for the *New Chat* button. +* `Action.SpotterPastChatBanner` for the past-conversation alert banner. Hide-only. +* `Action.SpotterChatMenu` for the three-dot edit menu displayed for each conversation in the list. +* `Action.SpotterChatRename` for the *Rename* option in the conversation edit menu. +* `Action.SpotterChatDelete` for the *Delete* option in the conversation edit menu. + ++ +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed('#ts-embed', { + worksheetId: '', + spotterSidebarConfig: { + enablePastConversationsSidebar: true, + }, + // Hide the Rename option and the past-conversation banner + hiddenActions: [Action.SpotterChatRename, Action.SpotterPastChatBanner], +}); +---- + +For a complete list of action IDs, see xref:Action.adoc[Action reference]. + +=== Customizing app interactions +Use the following event IDs to enable interaction between the host application and the chat history panel: + +HostEvents:: +* `HostEvent.StartNewSpotterConversation` + +Starts a new Spotter conversation programmatically. + ++ +[source,JavaScript] +---- +spotterEmbed.trigger(HostEvent.StartNewSpotterConversation); +---- + ++ +For a complete list of event IDs, see xref:HostEvent.adoc[HostEvent reference]. For the host event that opens the share modal from the chat history panel, see xref:customize-spotter-sharing.adoc#_customizing_app_interactions[Customizing app interactions]. + +EmbedEvents:: + +* `EmbedEvent.SpotterConversationRenamed` + +Emitted when a user renames a conversation from the chat history panel. The event payload includes the `convId`, `oldTitle`, and `newTitle`. +* `EmbedEvent.SpotterConversationDeleted` + +Emitted when a user deletes a conversation from the chat history panel. The event payload includes the `convId` and `title`. +* `EmbedEvent.SpotterConversationSelected` + +Emitted when a user selects a conversation from the chat history panel. The event payload includes the `convId`, `title`, and `worksheetId`. + ++ +[source,JavaScript] +---- +spotterEmbed.on(EmbedEvent.SpotterConversationRenamed, (payload) => { + console.log('Renamed:', payload.convId, payload.oldTitle, '->', payload.newTitle); +}); + +spotterEmbed.on(EmbedEvent.SpotterConversationDeleted, (payload) => { + console.log('Deleted:', payload.convId, payload.title); +}); + +spotterEmbed.on(EmbedEvent.SpotterConversationSelected, (payload) => { + console.log('Selected:', payload.convId, payload.title, payload.worksheetId); +}); +---- + +For a complete list of event IDs, see xref:EmbedEvent.adoc[EmbedEvent reference]. + +== Customizing other settings in the sidebar panel +The other settings in the sidebar panel include a link to Best practices guide and the sidebar footer. + +To customize these options or to control their visibility in the sidebar, use the following options: + +* `spotterDocumentationUrl` + +Allows customizing the documentation link. +* `Action.SpotterSidebarFooter` + +Action ID to show or hide the sidebar footer that contains the documentation link. +* `Action.SpotterDocs` + +Action ID to show or hide the documentation or best practices link in the sidebar footer. + +[source,JavaScript] +---- +const embed = new SpotterEmbed('#tsEmbed', { + // ...other embed view configuration options + // Configuration for the Spotter sidebar UI + spotterSidebarConfig: { + enablePastConversationsSidebar: true, // Enable the chat history sidebar + spotterDocumentationUrl: 'https://your-help-center-url', // Custom best practices link + }, +}) +---- + +== Additional resources +* xref:customize-spotter-embed.adoc[Customizing the Spotter embed view] +* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] +* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] +* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] diff --git a/modules/ROOT/pages/deprecated-features.adoc b/modules/ROOT/pages/deprecated-features.adoc index 39857dbe9..a6f33608b 100644 --- a/modules/ROOT/pages/deprecated-features.adoc +++ b/modules/ROOT/pages/deprecated-features.adoc @@ -14,7 +14,7 @@ As ThoughtSpot applications evolve, some existing features will be deprecated an [options='header'] |===== |Feature|Impacted interface and release versions|Deprecation date |End of Support / removal from the product -a|xref:deprecated-features.adoc#liveboardAnswerDiscoverable[Liveboard and answer discoverability] +a|xref:deprecated-features.adoc#liveboardDiscoverable[Liveboard and answer discoverability] a|ThoughtSpot Cloud 26.2.0.cl and later | February 2026 | August 2026 a|xref:deprecated-features.adoc#everynmins[Minute-level schedule frequency] |ThoughtSpot Cloud 26.8.0.cl and later | August 2026 | - diff --git a/modules/ROOT/pages/embed-ai-analytics.adoc b/modules/ROOT/pages/embed-ai-analytics.adoc index 6d52bf60b..772b8e030 100644 --- a/modules/ROOT/pages/embed-ai-analytics.adoc +++ b/modules/ROOT/pages/embed-ai-analytics.adoc @@ -1,8 +1,8 @@ -= Embed AI Search and Analytics += Embed Spotter AI analytics :toc: true :toclevels: 3 -:page-title: Embed AI Search and Analytics +:page-title: Embed Spotter AI and Analytics :page-pageid: embed-ai-search-analytics :page-description: To embed the ThoughtSpot Spotter and conversational analytics experience in your app, you can use the `SpotterEmbed` or `SpotterAgentEmbed` SDK components. @@ -62,13 +62,15 @@ You can use this version if your ThoughtSpot embedded app needs only metadata-le |==== == SDK libraries for embedding Spotter -ThoughtSpot provides the following Visual Embed SDK libraries for embedding Spotter capabilities in your app: +ThoughtSpot provides the xref:embed-spotter.adoc[`SpotterEmbed`] in the Visual Embed SDK to embed Spotter interface and its capabilities in your app. -* xref:embed-spotter.adoc[`SpotterEmbed`] + -Use this SDK component to xref:embed-spotter.adoc[embed the full Spotter experience] in your app. The features in a Spotter embed vary based on the Spotter version. +If you want to integrate just the Spotter AI analytics without ThoughtSpot's UI in your chatbot, consider using the xref:mcp-integration.adoc[Spotter MCP Server]. + +//// * xref:embed-spotter-agent.adoc[`SpotterAgentEmbed`] + Also known as `bodyless` embedding, `SpotterAgentEmbed` allows you to integrate Spotter capabilities into your own applications or chatbot, route user questions to ThoughtSpot, and receive structured answers and visualizations. Unlike the full Spotter experience, the "bodyless" embed includes only a prompt panel with no additional buttons or selectors. +//// == Feature status and availability in embed mode @@ -292,7 +294,117 @@ Action IDs to show or hide the MCP connector panel, connector resources section, * `Action.SpotterChatConnectorResources` * `Action.SpotterChatConnectors` * `Action.SpotterChatModeSwitcher` +|Stop answer generation + + +Allows users to interrupt an in-progress answer generation in the Spotter interface. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag greenBackground tick]#✓# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: Available from SDK v1.48.0 and ThoughtSpot Cloud 26.5.0.cl. + + +**Required settings**: Spotter 2 or Spotter 3 must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed`. + + +**Default state in embed**: Disabled by default. To enable, set `enableStopAnswerGenerationEmbed` to `true` in the SDK. + +|File upload in Spotter chat + + +Enables users to upload files from their local directory to provide context for a Spotter query. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: Available from SDK v1.49.0 and ThoughtSpot Cloud 26.6.0.cl. + + +**Required settings**: Spotter 3 must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed`. Also supported in `LiveboardEmbed` and `AppEmbed`. + + +**Default state in embed**: Disabled by default. To enable, set `spotterFileUploadEnabled` to `true` in the `spotterChatConfig` object. + +To restrict uploaded file types, use `spotterFileUploadFileTypes` within `spotterChatConfig`. + +|link:https://docs.thoughtspot.com/cloud/latest/spotter-starter-prompts[Spotter starter prompts, window=_blank] + + +Preconfigured search questions displayed as clickable suggestion pills in the Spotter chat interface. Supports three categories: Basic Search (`quick`), Deep Analysis (`research`), and Data Literacy (`previewData`). + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: Basic enablement available from SDK v1.51.0 and ThoughtSpot Cloud 26.8.0.cl. Custom configuration with category keys available from SDK v1.52.0 and ThoughtSpot Cloud 26.9.0.cl. + + +**Required settings**: Spotter 3 must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed`. Also supported in `LiveboardEmbed` and `AppEmbed`. + + +**Default state in embed**: Disabled by default. To enable, set `enableStarterPrompts` to `true` or set `starterPrompts.enable` to `true` in the `spotterChatConfig` object. + + +To customize individual category labels and questions, use the `starterPrompts` object with `quick`, `research`, and `previewData` keys. Only the first 4 questions per category are rendered. + + +Use the following Action IDs to control the visibility of individual starter prompt pills: + +* `Action.QuickSearchPill` +* `Action.DeepAnalysisPill` +* `Action.DataLiteracyPill` + +|Share conversation + + +Allows users to share a Spotter conversation with other users or groups. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: Available from SDK v1.52.0 and ThoughtSpot Cloud 26.9.0.cl. + + +**Required settings**: Spotter 3 must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed`. Also supported in `AppEmbed`. + + +**Default state in embed**: Disabled by default. To enable, set `enableShareConversation` to `true` in the `spotterShareConversationConfig` object. + +To open a shared conversation in read-only mode, set `sharedConversationId` with the conversation ID. + +|Default query mode + + +Sets the default query mode (Fast Search or Research) when Spotter loads. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: Available from SDK v1.52.0 and ThoughtSpot Cloud 26.9.0.cl. + + +**Required settings**: Spotter 3 must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed` and `AppEmbed`. + + +**Default state in embed**: Defaults to `SpotterQueryMode.FAST_SEARCH`. To set the default to Research mode, set `defaultQueryMode` to `SpotterQueryMode.RESEARCH`. The setting applies per session and does not persist as a user preference. + +|Multiple data sources + + +Allows setting multiple data source GUIDs for Spotter to query. + +|**Supported Spotter version**: + +[tag greenBackground tick]#✓# Spotter 3 + +[tag redBackground tick]#x# Spotter 2 + +[tag redBackground tick]#x# Spotter Classic + +**Feature status**: Disabled by default. + +**Required settings** Spotter 3 must be enabled at the instance level. + + +**Embed SDK component**: Use `SpotterEmbed`. + +**Default state in embed**: Not enabled by default. To use, set the `dataSources` array with the list of data source GUIDs. When `dataSources` is provided, it takes precedence over `worksheetId`. || |==== diff --git a/modules/ROOT/pages/embed-event-error-best-practices.adoc b/modules/ROOT/pages/embed-event-error-best-practices.adoc index e9bdc49f0..36c89620e 100644 --- a/modules/ROOT/pages/embed-event-error-best-practices.adoc +++ b/modules/ROOT/pages/embed-event-error-best-practices.adoc @@ -6,6 +6,17 @@ :page-pageid: handling-embed-errors :page-description: This document lists the best practices for handling error events. + +[IMPORTANT] +==== +In the upcoming ThoughtSpot Cloud 26.10.0.cl and Visual Embed SDK 1.53.0 versions, `EmbedEvent.Error` will include a `severity` field that categorizes errors into three severity levels: `SEV1`, `SEV2`, and `SEV3`. + +ThoughtSpot recommends reviewing your error handing logic to prepare your integrations for this change. If your application currently handles all errors uniformly, you may need to update your error handling to distinguish between critical errors (SEV1) that require tearing down the embed and less severe errors (SEV2, SEV3) that can be logged or ignored. + +//For more information, see the xref:embed-event-error-best-practices.adoc#_error_severity_levels[Error severity levels] section. +==== + + The ThoughtSpot Visual Embed SDK provides a layered approach to error handling. `EmbedEvent.Error` is a real-time outbound event emitted from the embedded ThoughtSpot iframe to the host application, signaling that something has gone wrong, either inside the SDK itself, inside the embedded app (the iframe), or as a result of an invalid HostEvent payload sent by the host. @@ -198,6 +209,42 @@ LiveboardEmbed.on(EmbedEvent.Error, (error) => { ---- |=== +//// +[#_error_severity_levels] +== Error severity levels + +Starting from ThoughtSpot Cloud 26.10.0.cl (Visual Embed SDK 1.53.0), the `EmbedEvent.Error` payload includes a `severity` field that categorizes errors into three levels: + +[cols="1,2,3", options="header"] +|=== +| Severity | Description | Recommended handling + +| `SEV1` | The embed is down: the app crashed and a fallback page is showing. | Consider tearing down the embed and re-initializing, or showing a custom error message to the user. +| `SEV2` | An error was shown to the user; the embed still works. | Log the error for monitoring. No immediate action is required unless the error indicates a persistent issue. +| `SEV3` | Everything else, including validation of the embedder's own input. | Log the error for debugging. These errors are typically not user-facing and can often be ignored if the application is functioning correctly. +|=== + +The `severity` field is included in the error payload as an optional integer value: + +[source,json] +---- +{ + "type": "Error", + "data": { + "errorType": "API", + "error": { + "message": "..." + }, + "severity": 2 + } +} +---- + +[NOTE] +==== +The `severity` field is backward compatible. If your application does not use the `severity` field, the error handling behavior remains unchanged. +==== +//// == Payload shapes [source,typescript] diff --git a/modules/ROOT/pages/embed-spotter-agent.adoc b/modules/ROOT/pages/embed-spotter-agent.adoc index aeaeb8ffc..1b57e8ea0 100644 --- a/modules/ROOT/pages/embed-spotter-agent.adoc +++ b/modules/ROOT/pages/embed-spotter-agent.adoc @@ -1,4 +1,4 @@ -= Embed Spotter Agent += Embed Spotter AI without ThoughtSpot UI :toc: true :toclevels: 3 @@ -6,17 +6,21 @@ :page-pageid: embed-spotter-agent :page-description: You can use the SpotterAgentEmbed SDK library to embed Spotter experience in your application. -Spotter Agent is an embeddable AI analyst component from ThoughtSpot that enables you to integrate natural language data search and conversation analytics into your own application. Unlike the standard Spotter embed, which provides a ready-made search bar and interface, Spotter Agent is designed for deeper integration and customization. It allows you to build your own UI or agent experience, route user questions to ThoughtSpot, and receive structured answers and visualizations, allowing full control over the look, feel, and workflow of the embedded analytics experience. +[IMPORTANT] +==== +The `SpotterAgentEmbed` component will be deprecated in an upcoming version. + If you want to use Spotter capabilities with your own UI or agentic experience, ThoughtSpot recommends using the Spotter MCP Server. For more information, see xref:mcp-connect-custom-chatbot.adoc[Integrating Spotter MCP Server in a custom application or chatbot]. +==== -== Before you begin +SpotterAgentEmbed lets you integrate Spotter's AI analytics into your own chat interface without rendering any ThoughtSpot UI. Unlike SpotterEmbed, which embeds the full Spotter experience in your app, SpotterAgentEmbed gives you full control over the chat layout, message flow, and design, so you can build a branded chatbot or conversational application while ThoughtSpot handles the analytical processing behind the scenes. -Before you begin, check the following: +== Using SpotterAgentEmbed component +Before you begin embedding Spotter prompt panel using `SpotterAgentEmbed` component, -* You have a ThoughtSpot instance with Spotter Agent enabled. -* You have access to the latest version of the Visual Embed SDK v1.33.1 or later. -* Your host application domain is added to ThoughtSpot CSP and CORS allowlists. +* Add the URL of the host application, which embeds ThoughtSpot visualizations, to the CSP allowlist. This includes adding the correct CORS and frame-ancestors CSP. +* Configure the authentication scheme that works best for your use case. -== Import the SDK package +=== Import the SDK package Import the `SpotterAgentEmbed` SDK library to your application environment: @@ -45,7 +49,7 @@ from '@thoughtspot/visual-embed-sdk'; from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/index.js'; ---- -== Initialize the SDK +=== Initialize the SDK To initialize the SDK, the following information is required: @@ -77,17 +81,9 @@ const spotterAgentEmbed = new SpotterAgentEmbed(document.getElementById('ts-embe }); ---- - == Customization controls for the embed view (Optional) - -The embed package for Spotter includes the additional configuration flags to customize the Spotter Agent. Spotter Agent includes only the AI search experience with the Search bar by default. The interface design and styling is controlled by your host app. However, the SDK provides a few controls to customize search experience and app interactions. - -For more information, see the following pages: - -* xref:SpotterAgentEmbedViewConfig.adoc[SpotterAgentEmbedConfig] for embed view customization properties -* xref:Action.adoc[Action customization framework] to show or hide actions on the Answers generated from the query + -* Event handlers for xref:HostEvent.adoc[host] and xref:EmbedEvent.adoc[embed] app interaction -* xref:css-customization.adoc[Style customization framework] to customize style, text strings, and icons in the embedded view. +The SDK supports limited customization controls when you embed using the `SpotterAgentComponent`. +For information about the available interface customization settings, see xref:SpotterAgentEmbedViewConfig.adoc[SpotterAgentEmbedConfig]. == Render the embedded object @@ -115,8 +111,7 @@ const spotterAgentEmbed = new SpotterAgentEmbed('#ts-spotter-agent', { width: '100%', }, worksheetId: "your-worksheet-id", // ID of the data source object (Model) to query data - // Optionally, you can set other configuration options here - // Add event listeners + // Other config attributes }); spotterAgentEmbed.render(); @@ -129,7 +124,7 @@ If the embedding is successful, you'll see the Spotter search panel at the botto + [.widthAuto] [.bordered] -image::./images/spotterAgentEmbed.png[Spotter Agent embed] +image::./images/spotterAgentEmbed.png[SpotterAgentEmbed] * Type your query, click the *Send* button to prompt Spotter and generate a response. + @@ -138,7 +133,6 @@ image::./images/spotterAgentEmbed.png[Spotter Agent embed] image::./images/spotterAgentEmbedQuery.png[Spotter Agent embed query] == Additional resources -* link:https://developers.thoughtspot.com/docs/Class_SpotterAgentEmbed[SpotterAgentEmbed classes and methods] +* xref:SpotterAgentEmbed.adoc[SpotterAgentEmbed classes and methods] * xref:spotter-in-custom-chatbot.adoc[Integrate Spotter in your custom chatbot tutorial] * link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/spotter/spotter-agent-embed[Developer examples, window=_blank] -* link:https://codesandbox.io/p/sandbox/youthful-paper-km4zh6?file=%2Fsrc%2FApp.js%3A51%2C47-51%2C62[Code sandbox, window=_blank] diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index 158fce723..2ce50aea1 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -1,8 +1,8 @@ -= Customize the home page and navigation for full application embedding += Customize your full application embed :toc: true :toclevels: 3 -:page-title: Customize the home page and navigation for full application embedding +:page-title: Customize your full application embed :page-pageid: full-app-customize :page-description: Customize the home page and navigation for full application embedding @@ -16,7 +16,6 @@ ThoughtSpot supports the following experience modes in full application embeddin The classic V1 and V2 navigation and homepage experience modes are deprecated as of ThoughtSpot Cloud 26.8.0.cl. Starting from this release, all embedded sessions render in the V3 navigation experience by default. ==== - == UI experience modes ThoughtSpot supports V3 and V4 home page and navigation experiences for full application embedding. diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/getting-started.adoc index 2a9165058..8be78539c 100644 --- a/modules/ROOT/pages/getting-started.adoc +++ b/modules/ROOT/pages/getting-started.adoc @@ -1,4 +1,4 @@ -= Embed ThoughtSpot += Embed with Visual Embed SDK :toc: true :linkattrs: :sectanchors: diff --git a/modules/ROOT/pages/lazy-loading-fullheight.adoc b/modules/ROOT/pages/lazy-loading-fullheight.adoc index 0d09fafb2..ed3d8c8bb 100644 --- a/modules/ROOT/pages/lazy-loading-fullheight.adoc +++ b/modules/ROOT/pages/lazy-loading-fullheight.adoc @@ -9,55 +9,62 @@ The Visual Embed SDK provides configuration options to control how embedded apps handle the height of frame and loading of visualizations on an embedded Liveboard. == Loading visualizations in the Liveboard viewport -To dynamically resize the height of the Liveboard embed container, the Visual Embed SDK provides the `fullHeight` boolean property. The `fullHeight` property dynamically adjusts the height of the embed container to match the height of the Liveboard, thereby eliminating the need for scroll bars. +To dynamically resize the height of the Liveboard embed container, the Visual Embed SDK provides the `fullHeight` property. * If `fullHeight` is set to `true`: + -The height of the Liveboard container dynamically adjusts to match the height of the Liveboard content. This causes all visualizations on the Liveboard to load simultaneously, which can lead to a potentially longer wait for the top-most visualizations to appear in the viewport. However, setting `lazyLoadFullHeight` to `true` along with `fullHeight: true` allows lazy loading for visualizations in the viewport as the user scrolls the page. The `fullHeight: true` works best when an embedded Liveboard has fewer visualizations. +The height of the Liveboard container dynamically adjusts to match the height of the Liveboard content. This causes all visualizations on the Liveboard to load simultaneously, which can lead to a potentially longer wait for the top-most visualizations to appear in the viewport. However, setting `lazyLoadingForFullHeight` to `true` along with `fullHeight: true` allows lazy loading for visualizations in the viewport as the user scrolls the page. The `fullHeight: true` works best when an embedded Liveboard has fewer visualizations. * When `fullHeight` is set to `false` (default): + Only the visualizations currently visible in the viewport are loaded initially. Additional visualizations are fetched incrementally as users scroll the page. This reduces initial load time, minimizes unnecessary data API calls, and provides a smoother, faster experience for large dashboards. By default, the `fullHeight` parameter is set to `false`. +== Lazy loading +When `fullHeight` is enabled, you can use the `lazyLoadingForFullHeight` parameter to enable lazy loading of visualizations. -=== Full height with minimum height setting -In addition to `fullHeight`, the SDK also provides the `minimumHeight` parameter. The value defined for the `minimumHeight` attribute is applied only when `fullHeight` is set to `true`. -If `fullHeight` is `true`, the embedded container resizes according to the Liveboard content . and `minimumHeight` sets the minimum height (in pixels) for this container. -This ensures that even if the Liveboard is empty or has little content, the container maintains at least the specified minimum height. If `fullHeight` is set to `false`, the `minimumHeight` attribute is not applied. +Starting with Visual Embed SDK v1.52.0, the `lazyLoadingForFullHeight` parameter is enabled by default when `fullHeight` is set to `true` and the visualizations in the embedded Liveboard are loaded incrementally as the user scrolls, rather than all at once. This reduces initial load time and resource usage, and improves performance for large Liveboards. + +If the `lazyLoadingForFullHeight` parameter is set to `false`, all visualizations load immediately, and the data is fetched upfront. [source,JavaScript] ---- -const embed = new LiveboardEmbed('#embed', { - // other liveboard view config - fullHeight: true, - minimumHeight: 600, +const embed = new LiveboardEmbed("#your-embed-div", { + liveboardId: "your-liveboard-id", //your Liveboard ID + fullHeight: true, + lazyLoadingForFullHeight: true, // Enable lazy loading for full height }); ---- -== Lazy loading with full height enabled +=== Lazy loading of scrollable container +When `fullHeight` is enabled, the `enableScrollableContainerLazyLoading` parameter is set to `true` by default to enable lazy loading for scrollable container elements in Visual Embed SDK 1.52.0 and later. + +=== Margin settings for lazy loading + +The `lazyLoadingMargin` parameter allows you to set the margin before a visualization loads in the viewport. For example, if set to `'10px'`, the visualizations begin loading when the top edge is within the 10-pixel margin of the viewport. If set to `'0px'`, the visualization loads only when it becomes fully visible in the viewport. This allows precise control over lazy loading behavior and improves both user experience and performance. + +In Visual Embed SDK 1.52.0 and later, the `lazyLoadingMargin` defaults to `'500px 0px'` when `fullHeight` is enabled. This setting is similar to CSS margin, so '500px 0px' extends the prefetch 500px above and below the viewport and not sideways. The default setting allows loading one visualization ahead of the scroll position, so a chart has usually finished loading by the time it scrolls into view. -If `fullHeight` is enabled, you can use the `lazyLoadingForFullHeight` boolean parameter to enable lazy loading of visualizations. When both `fullHeight` and `lazyLoadingForFullHeight` are set to `true`, visualizations in the embedded Liveboard are loaded incrementally as the user scrolls, rather than all at once. This reduces initial load time and resource usage, and improves performance for large Liveboards. +You can edit the margin setting as needed. Use a smaller margin to cut warehouse queries further, or '0px' to load a visualization only when it is visible. Accepted units are `px`, `em`, `rem`, `%`, `vh` and `vw`. The parameter also allows setting `0` and `auto`. Any invalid value is logged and ignored. [source,JavaScript] ---- const embed = new LiveboardEmbed("#your-embed-div", { liveboardId: "your-liveboard-id", //your Liveboard ID fullHeight: true, - lazyLoadFullHeight: true, // Enable lazy loading for full height + lazyLoadingForFullHeight: true, // Enable lazy loading for full height + lazyLoadingMargin: '0px', }); ---- -By default, the `lazyLoadingForFullHeight` attribute is set to `false`. When set to `false`, all visualizations load immediately, and the data is fetched upfront. - -== Margin settings for lazy loading +== Full height with minimum height setting +In addition to `fullHeight`, the SDK also provides the `minimumHeight` parameter to set the minimum height (in pixels) for this container. The value defined for the `minimumHeight` attribute is applied only when `fullHeight` is set to `true`. -The `lazyLoadingMargin` parameter allows you to set the margin before a visualization loads in the viewport. For example, if set to '10px', the visualizations will begin loading when the top edge is within the 10-pixel margin of the viewport. If set to '0px', the visualization will load only when it becomes fully visible in the viewport. This allows for precise control over lazy loading behavior and improves both user experience and performance. +This ensures that even if the Liveboard is empty or has little content, the container maintains at least the specified minimum height. [source,JavaScript] ---- -const embed = new LiveboardEmbed("#your-embed-div", { - liveboardId: "your-liveboard-id", //your Liveboard ID - fullHeight: true, - lazyLoadFullHeight: true, // Enable lazy loading for full height - lazyLoadingMargin: '0px', +const embed = new LiveboardEmbed('#embed', { + // other liveboard view config + fullHeight: true, + minimumHeight: 600, }); ---- diff --git a/modules/ROOT/pages/prerender.adoc b/modules/ROOT/pages/prerender.adoc index bf568f4cb..bb795fbed 100644 --- a/modules/ROOT/pages/prerender.adoc +++ b/modules/ROOT/pages/prerender.adoc @@ -1,21 +1,17 @@ -= Pre-rendering ThoughtSpot Embed components += Prerender components :toc: true :toclevels: 2 -:page-title: Pre-rendering for Fast Embeds +:page-title: Prerender for fast embedding :page-pageid: prerender :page-description: How to use pre-rendering to optimize performance and user experience in ThoughtSpot embedding -Before implementing pre-rendering, let's understand how embedding ThoughtSpot works in a typical web app. - -== How embedding works - ThoughtSpot is a web app, and like any modern web application, it requires two main things to function: * *Assets* - The static files your browser needs to display and run the application, such as JavaScript files, CSS files, fonts, and images. * *API Calls*: These are network requests made from the browser to the ThoughtSpot backend to fetch: + -- Data (the actual analytics, tables, charts, and so on) -- Metadata (information about users, tables, permissions, and so on) +** Data (the actual analytics, tables, charts, and more) +** Metadata (information about users, tables, permissions, and more) image::./images/pre-render/web-app.png[] @@ -27,23 +23,23 @@ ThoughtSpot internally optimizes the loading process by splitting assets and API - For embed components such as Search, Liveboard, and Spotter, only the assets and API calls required for that component are loaded. - There are a few common assets such as fonts, shared JavaScript, CSS, and common API calls to fetch user information, that are always loaded, as they are used across all embed types. -- In addition to these common resources, each component (for example, Liveboard) will load its own specific JavaScript, CSS, and make API calls only needed for that component. +- In addition to these common resources, each component (for example, Liveboard) will load its own specific JavaScript and CSS, and make only the API calls needed for that component. image::./images/pre-render/asset-split.png[] For example, if you are embedding a Liveboard: . The browser first loads the common assets and makes common API calls for resources such as fonts and user information. -. Then, it loads the Liveboard-specific JavaScript and CSS files, and make the necessary API calls to fetch Liveboard data. -. Assets and API calls for other components, such as Search or Spotter, are not loaded unless those components are actually used. +. Then, it loads the Liveboard-specific JavaScript and CSS files, and makes the necessary API calls to fetch Liveboard data. +. Assets and API calls for other components, such as Search or Spotter, are not loaded unless those components are used. This approach ensures that the embed is efficient, loading only what is necessary for the user's current experience, and helps improve performance by reducing unnecessary downloads and network requests. -Before getting started with pre-rendering, let’s understand the essential first step in embedding ThoughtSpot. +Before getting started with pre-rendering, let's understand the essential first step in embedding ThoughtSpot. == `init` call -In ThoughtSpot embedding, `init` is first essential step. Before you can render any ThoughtSpot embed component, you must call the `init` method from the Visual Embed SDK. This function initializes the SDK and sets up the connection to your ThoughtSpot instance. It is the required starting point for any embedding scenario. +In ThoughtSpot embedding, `init` is the first essential step. Before you can render any ThoughtSpot embed component, you must call the `init` method from the Visual Embed SDK. This function initializes the SDK and sets up the connection to your ThoughtSpot instance. It is the required starting point for any embedding scenario. === When should you call `init`? @@ -60,9 +56,9 @@ Always call `init` before rendering any embed component, and do so as soon as yo == Pre-rendering overview -Now that you know how ThoughtSpot loads assets and data, let’s explore how you can make the experience even faster for your users. +Now that you know how ThoughtSpot loads assets and data, let's explore how you can make the experience even faster for your users. -Consider the scenario, where you have an app with a landing screen where users spend some time before navigating to the embedded ThoughtSpot page. In the current setup, ThoughtSpot only starts loading when the user actually visits the analytics page. What if you could start loading some of ThoughtSpot’s essential files and data while users are still on the landing screen, before they reach the analytics page? +Consider the scenario, where you have an app with a landing screen where users spend some time before navigating to the embedded ThoughtSpot page. In the current setup, ThoughtSpot only starts loading when the user visits the analytics page. What if you could start loading some of ThoughtSpot’s essential files and data while users are still on the landing screen, before they reach the analytics page? That’s exactly what pre-rendering does! By starting the load process early, you can make the analytics appear much faster when the user finally navigates to that page. @@ -72,12 +68,12 @@ image::./images/pre-render/pre-rendering-basic.png[] Keeping the above in mind, let's define a few key terms that we'll use later in this guide: -* **Common asset download** – The shared JavaScript and CSS files that every embed needs -* **Common API calls** – The basic API requests made for things like user info, used by all embed types -* **Embed level asset download** – The specific files (like JS and CSS) needed only for the embed type you're using (for example, Liveboard or Search) -* **Embed API calls** – The API requests made to fetch the actual data and content for the specific embed (like loading a Liveboard's data) -* **Host app** – This is your web application (the main app your users interact with) -* **Analytics page** – This is a page in your web app where ThoughtSpot is actually embedded +* **Common asset download**: The shared JavaScript and CSS files that every embed needs +* **Common API calls**: The basic API requests made for things like user info, used by all embed types +* **Embed level asset download**: The specific files (like JS and CSS) needed only for the embed type you're using (for example, Liveboard or Search) +* **Embed API calls**: The API requests made to fetch the actual data and content for the specific embed (like loading a Liveboard's data) +* **Host app**: This is your web application (the main app your users interact with) +* **Analytics page**: This is a page in your web app where ThoughtSpot is embedded == How to use pre-rendering? @@ -85,7 +81,7 @@ Based on your use case, you can choose to pre-render the embed in one of the fol . xref:prerender.adoc#_pre_render_with_liveboard_id[Pre-render with Liveboard ID] . xref:prerender.adoc#_pre_render_without_the_liveboard_id[Pre-render without the Liveboard ID] -. xref:prerender.adoc#_pre_render_on_demand[Prerender on demand] +. xref:prerender.adoc#_pre_render_on_demand[Pre-render on demand] . xref:prerender.adoc#_normal_render[Normal render] . xref:prerender.adoc#_prefetch_assets[Prefetch assets] @@ -100,15 +96,16 @@ In this approach, you load everything all at once. When the user navigates to th image::./images/pre-render/dig3_pre_with_livid.png[] ==== Implementation - -In your application's home page, loading page, or landing page, you need to prerender the embed with the Liveboard ID. +In your application's home page, loading page, or landing page, you need to pre-render the embed with the Liveboard ID. [source,JSX] ---- // React ---- @@ -121,20 +118,24 @@ import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; const embed = new LiveboardEmbed({ liveboardId: 'e40c0727-01e6-49db-bb2f-5aa19661477b', - preRenderId: 'pre-render-with-liveboard-id', + preRenderConfig: { + id: 'pre-render-with-liveboard-id', + }, }); embed.preRender(); ---- -When you actually want to show the Liveboard, call this component: +When you want to show the Liveboard, call this component: [source,JSX] ---- // React ---- @@ -147,17 +148,72 @@ import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; const embed = new LiveboardEmbed({ liveboardId: 'e40c0727-01e6-49db-bb2f-5aa19661477b', - preRenderId: 'pre-render-with-liveboard-id', + preRenderConfig: { + id: 'pre-render-with-liveboard-id', + }, }); embed.render(); ---- +[NOTE] +==== +Starting from Visual Embed SDK 1.52.0, the top-level pre-render properties are deprecated. Use the `preRenderConfig` object instead: + +* `preRenderId` → `preRenderConfig.id` +* `preRenderContainer` → `preRenderConfig.containerSelector` +* `doNotTrackPreRenderSize` → `preRenderConfig.doNotTrackSize` +==== + This approach is the fastest way to load the embed, but it is also the most resource-intensive. -The makes calls to the ThoughtSpot API to fetch the Liveboard data and metadata, which might be unwanted if the end user never views the embed. +The SDK makes calls to the ThoughtSpot API to fetch the Liveboard data and metadata, which might be unwanted if the end user never views the embed. -=== Pre-render without the Liveboard ID +=== Mount the pre-rendered embed in a specific container +By default, the SDK attaches pre-rendered iframes as child components of the document body. The `containerSelector` property in `preRenderConfig` tells the SDK which element on your page to mount the pre-rendered embed inside instead. + +This is useful when the browser window itself does not scroll, but an inner container does. Mounting the pre-rendered embed inside the scrolling container ensures the embed positions and sizes itself correctly within your application's layout. + +For example, if the window does not scroll, `#app-scroll` does, and the embed element sits inside it: + +[source,HTML] +---- +
+
+
+---- + +Set `containerSelector` to the scrolling container: + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + liveboardId: '', + preRenderConfig: { + id: 'my-liveboard', + containerSelector: '#app-scroll', + }, +}); + +// Warm the Liveboard up front, for example on your landing page. +await embed.preRender(); + +// Reveal it when the user navigates to the page that shows it. +embed.showPreRender(); +---- + +In React, set `containerSelector` on the `PreRendered*` component — the component that creates the pre-render: + +[source,JSX] +---- + +---- + + +=== Pre-render without the Liveboard ID In this approach, you load the common assets and common API calls early, but you defer the Liveboard-specific data/API calls until needed. - Loads common assets and bootstrap logic early. @@ -172,7 +228,9 @@ To use this strategy, place the following component on your application's home p [source,JSX] ---- ---- @@ -184,18 +242,21 @@ OR import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; const embed = new LiveboardEmbed({ - preRenderId: 'pre-render-without-liveboard-id', + preRenderConfig: { + id: 'pre-render-without-liveboard-id', + }, }); embed.preRender(); ---- - -When you actually want to show the Liveboard, call this component: +When you want to show the Liveboard, call this component: [source,JSX] ---- ---- @@ -208,33 +269,39 @@ OR import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; const embed = new LiveboardEmbed({ - preRenderId: 'pre-render-without-liveboard-id', + preRenderConfig: { + id: 'pre-render-without-liveboard-id', + }, liveboardId: 'e40c0727-01e6-49db-bb2f-5aa19661477b', }); embed.render(); ---- -This approach is more efficient than the previous one, but it does not load the Liveboard data and metadata until the end user actually navigates to the analytics page. So users might see a loading state for a few seconds before the Liveboard is loaded. +This approach is more efficient than the previous one, but it does not load the Liveboard data and metadata until the end user navigates to the analytics page. So users might see a loading state for a few seconds before the Liveboard is loaded. === Pre-render on demand +If you do not want your host app to fetch any ThoughtSpot resources during its initial load, pre-rendering on demand is ideal. -If you do not want your host app to fetch any ThoughtSpot resources during its initial load, this approach is ideal. - -In this mode, nothing is fetched until you actually render the embed. On the first render, all required assets and data are loaded. The iframe is then kept alive in the browser, so subsequent renders with the same `preRenderId` are instant because the existing iframe is reused. +In this mode, nothing is fetched until you render the embed. On the first render, all required assets and data are loaded. The iframe is then kept alive in the browser, so subsequent renders with the same prerender ID are instant because the existing iframe is reused. - Loads nothing up front; the embed is created only when the end user navigates to it. -- First visit loads normally; subsequent visits with the same `preRenderId` reuse the iframe and appear instantly. +- First visit loads normally; subsequent visits with the same prerender ID reuse the iframe and appear instantly. - Most resource‑efficient; loads only if needed and avoids repeated work by reusing the iframe. - Performance benefit is realized only when the user navigates back to the analytics page; the first visit behaves like a normal render. image::./images/pre-render/dig5_ondemand.png[] -Since we are not 'preloading' any assets or data, this strategy does not require any pre-render component, simply pass a `preRenderId` prop to your normal component render. +Since we are not _preloading_ any assets or data, this strategy does not require any pre-render component. Simply pass a prerender ID in the `preRenderConfig` object of your normal component render. [source,JSX] ---- - + ---- [source,js] @@ -243,16 +310,18 @@ Since we are not 'preloading' any assets or data, this strategy does not require import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; const embed = new LiveboardEmbed({ - preRenderId: 'pre-render-on-demand', + preRenderConfig: { + id: 'pre-render-on-demand', + }, liveboardId: 'e40c0727-01e6-49db-bb2f-5aa19661477b', }); embed.render(); ---- -The value of `preRenderId` can be any string, but it must match the `preRenderId` you use when rendering the actual embed later. +The value of prerender ID can be any string, but it must match the `id` you use when rendering the actual embed later. -=== Normal Render +=== Normal render - Default behavior. Loads the embed only when the component is rendered. - On every visit, the iframe is recreated and the embed loads from scratch. @@ -300,24 +369,50 @@ prefetch("https://:", [ ]); ---- -== Strategy Comparison Table +== Strategy comparison table [cols="1,1,1,1,1,1,2",options="header"] |===== | Strategy | Loads in Parallel | Loads Data If Not Used | Loads Assets If Not Used | Reuses Iframe | Perceived Load Speed | Notes -| Normal Render | ❌ | ✅ No | ✅ No | ❌ | ❌ Slowest | No reuse; re-renders every time +| Normal render | ❌ | ✅ No | ✅ No | ❌ | ❌ Slowest | No reuse; re-renders every time | Prefetch | ✅ (few assets) | ✅ No | ⚠️ Yes (small assets) | ❌ | ⚠️ Slight improvement | Browser cache often makes it redundant -| Prerender + ID | ✅ | ❌ Yes | ❌ Yes | ✅ | ✅✅✅ Fastest | Best UX, worst resource efficiency -| Prerender w/o ID | ✅ | ✅ No | ⚠️ Yes (partial assets) | ✅ | ⚠️ Moderate | Trade-off between prep and efficiency +| Pre-render + ID | ✅ | ❌ Yes | ❌ Yes | ✅ | ✅✅✅ Fastest | Best UX, worst resource efficiency +| Pre-render w/o ID | ✅ | ✅ No | ⚠️ Yes (partial assets) | ✅ | ⚠️ Moderate | Trade-off between prep and efficiency | On Demand | ❌ | ✅ No | ✅ No | ✅ | ✅ (on revisit), ❌ (first visit) | Best balance of performance and efficiency |===== -=== Advanced Troubleshooting +== Keep the pre-render configuration in sync with the actual embed +When you pre-render a Liveboard with `PreRenderedLiveboardEmbed`, pass the same configuration you intend to use on the real `LiveboardEmbed`, including the `liveboardId` and any flags that change the Liveboard's layout or behavior, such as `isLiveboardCompactHeaderEnabled` or `isLiveboardMasterpiecesEnabled`. + +These settings alter the rendered UI and the API calls ThoughtSpot makes to build the Liveboard. If a flag is set on `LiveboardEmbed` but was missing from the pre-rendered instance, the pre-rendered app cannot be reused as-is: it has to reload and re-fetch the Liveboard, which cancels the benefit of pre-rendering and reintroduces exactly the delay you were trying to avoid. + +As a best practice, pre-render with the exact configuration you intend to display, the same liveboardId, settings, and runtime overrides. When the pre-rendered configuration matches, the SDK reuses the existing instance directly, resulting in a near-instant load. + +[source,JSX] +---- +// Pre-render early (hidden), with the full config + + +// Later, show it — identical configuration settings, so the pre-rendered instance is reused + +---- + +=== Advanced troubleshooting * If the pre-rendered component does not appear, check that the container is visible and the coordinates are set. -* The iframes are saved as a child components to the body and not in the given target element. +* The iframes are saved as child components to the body, and not in the given target element. To mount the pre-rendered iframe inside a specific element instead, use `preRenderConfig.containerSelector`. For more information, see xref:prerender.adoc#_mount_the_pre_rendered_embed_in_a_specific_container[Mount the pre-rendered embed in a specific container]. -== Additional Resources +== Additional resources * link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/pre-rendering[Pre-rendering examples on GitHub, window=_blank] * link:https://stackblitz.com/github/thoughtspot/developer-examples/tree/main/visual-embed/pre-rendering[StackBlitz: Pre-rendering, window=_blank] diff --git a/modules/ROOT/pages/report-apis-v2.adoc b/modules/ROOT/pages/report-apis-v2.adoc index 74c50cb30..f5195e5b9 100644 --- a/modules/ROOT/pages/report-apis-v2.adoc +++ b/modules/ROOT/pages/report-apis-v2.adoc @@ -11,7 +11,7 @@ ThoughtSpot provides the following REST API v2 endpoints to download or export d * xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] + Download a Liveboard and its visualizations in PDF, PNG, CSV, or XLSX file format. * xref:#_answer_report_api[`POST /api/rest/2.0/report/answer`] + -Download data from a saved Answer in PDF, PNG, CSV, or XLSX file format. +Download data from a saved Answer, a pinned Answer on a Liveboard, or a Spotter-generated Answer in PDF, PNG, CSV, or XLSX file format. [NOTE] To retrieve data as JSON instead of downloading a file, see xref:data-apis-v2.adoc[Data APIs]. @@ -28,7 +28,7 @@ To download a personalized view of the Liveboard, specify the view name in the ` [IMPORTANT] ==== -* The downloadable file returned in API response file is extensionless. You need to rename the downloaded file by typing in the relevant extension. +* The downloadable file returned in the Liveboard API response is extensionless. You need to rename the downloaded file by adding the relevant extension. Answer exports are named automatically; see xref:#_answer_report_api[Answer Report API]. * If the Liveboard includes Note tiles, ensure that you do not pass the GUID of Note tiles as `visualization_identifiers` in the API request. Attempting to do so will lead to an error, and the API will return 400 error code in response. * Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. * If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Liveboard exports. @@ -254,31 +254,56 @@ See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_ge == Answer Report API -To download Answer data via `/api/rest/2.0/report/answer` API, you need at least view access to the saved Answer. +To download Answer data via `/api/rest/2.0/report/answer` API, you need at least view access to the Answer being exported. -In the request body, specify the GUID or name of the Answer object as `metadata_identifier`. +The API supports exporting: -The API supports exporting saved Answers, pinned Answers from a Liveboard, and Spotter-generated Answers. You can download Answer data in `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`. +* Saved Answers +* Pinned Answers on a Liveboard +* Spotter-generated Answers + +You can download Answer data in `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`. [IMPORTANT] ==== -* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Answer exports. -* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the PDF, XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. +* If Role-Based Access Control (RBAC) is enabled, the `DATADOWNLOADING` (Can download Data) privilege is required for Answer exports. +* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the PDF, XLSX, or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. ==== -=== Example +=== Usage guidelines -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", - "file_format": "PNG" -}' ----- +Use the `type` and `metadata_identifier` parameters together to specify the Answer to export. +The `type` parameter distinguishes between a saved Answer and a pinned Answer on a Liveboard. +If `type` is not specified, the API defaults to `SAVED`. + + +[cols="1,2,1,3"] +|=== +|`type` |`metadata_identifier` |Result |Notes + +|`SAVED` (default) +|GUID or name of the *saved Answer* +|_Success_. Downloads the saved Answer +|Omitting `type` produces the same result as setting `type: SAVED`. + +|`PINNED` +|Container ID +|_Success_. Downloads with Liveboard context + +Liveboard-level filters, Runtime Filters, and Column Security Rules (CSR) are automatically applied to the export. +|Use container ID as `metadata_identifier`. + +|`PINNED` +|GUID of a *saved Answer* (not a Liveboard) +|_Fails_ +|Passing an Answer GUID instead of the containing Liveboard GUID when `type` is `PINNED` results in an error. + +|`SAVED` +|GUID of a *Liveboard* +|_Fails_ +|Liveboard GUIDs are not valid `metadata_identifier` values when `type` is `SAVED` or omitted. +|=== + +To export a specific Personalized View of a Liveboard, include the `personalised_view_identifier` parameter with the GUID of that view. [NOTE] ==== @@ -286,18 +311,28 @@ curl -X POST \ * HTML rendering is not supported for PDF exports of Answers with tables. ==== +=== Find the metadata identifier -Contact ThoughtSpot support to enable these enhanced settings for this API endpoint on your ThoughtSpot instance: +For *saved Answers* (`type: SAVED`): +Send a request to `/api/rest/2.0/metadata/search` with `type: ANSWER` to retrieve the Answer GUID. -* `personalised_view_identifier` [earlyAccess eaBackground]#Early Access# + -Optional parameter to specify the GUID of the personalised view of the `PINNED` Answer object that you want to download. -* `type` [earlyAccess eaBackground]#Early Access# + -Used to distinguish between a saved answer and a pinned answer on a Liveboard. Setting this parameter to `PINNED` allows the API to -accept the guid of a pinned Answer directly as the `metadata_identifier`. When -exporting an Answer, all Liveboard-level filters, Runtime Filters, and Column -Security Rules (CSR) are automatically applied to the export output. +For *pinned Answers* (`type: PINNED`): +Use the GUID of the *Liveboard* that contains the pinned Answer as the `metadata_identifier`. +To find the Liveboard GUID: + +. In the ThoughtSpot application, open the Liveboard. +. Copy the GUID from the address bar. ++ +---- +https:///#/pinboard/ +---- + +Alternatively, send a request to `/api/rest/2.0/metadata/search` with `type: LIVEBOARD`. + +=== PNG export options + +The `png_options` support the following properties: -The `png_options` [earlyAccess eaBackground]#Early Access# support the following properties: [cols="1,1,3"] |=== @@ -306,21 +341,75 @@ The `png_options` [earlyAccess eaBackground]#Early Access# support the following |`x_resolution` |Number |Width of the exported PNG in pixels. + -Valid range: `600px` to `3840px`. +Valid range: `600px` to `3840px`. + +Default: `2254px`. This is honored only when neither `x_resolution` nor `y_resolution` is passed. If either value is passed, retaining the default 1.414:1 aspect ratio is prioritized. |`y_resolution` |Number |Height of the exported PNG in pixels. + -Valid range: `600px` to `3840px`. +Valid range: `600px` to `3840px`. + +Default: `1588px`. This is honored only when neither `x_resolution` nor `y_resolution` is passed. If either value is passed, retaining the default 1.414:1 aspect ratio is prioritized. |`scaling` |Integer -|Display scale percentage for objects rendered in the image. Adjusts the relative -size of visual elements without cropping the image. + +|Display scale percentage for objects rendered in the image. Adjusts the relative size of visual elements without cropping the image. + Valid range: `80%` to `500%`. |=== -You can now export the PNG of any Answer in any aspect ratio and any scaling or zoom level. Just configure, scale, and export exactly what you need. +=== Examples + +==== Export a saved Answer (default) + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", + "file_format": "PNG" +}' +---- + +Omitting `type` is equivalent to setting `"type": "SAVED"`. + +==== Export a pinned Answer from a Liveboard + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", + "type": "PINNED", + "file_format": "CSV" +}' +---- + +In this case, `metadata_identifier` is the GUID of the Liveboard that contains the pinned Answer. +Liveboard-level filters, Runtime Filters, and Column Security Rules are automatically applied to the export. + +==== Export a PNG with custom dimensions and scaling + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", + "file_format": "PNG", + "png_options": { + "x_resolution": 1920, + "y_resolution": 1080, + "scaling": 120 + } +}' +---- [#exportSpotterData] === Export data generated from Spotter APIs diff --git a/modules/ROOT/pages/rest-api-csharp-sdk.adoc b/modules/ROOT/pages/rest-api-csharp-sdk.adoc index 28200e803..ce6832f20 100644 --- a/modules/ROOT/pages/rest-api-csharp-sdk.adoc +++ b/modules/ROOT/pages/rest-api-csharp-sdk.adoc @@ -28,14 +28,14 @@ Using the .NET CLI:: [source,bash] ---- -dotnet add package ThoughtSpot.RestApi.Sdk --version 2.27.0 +dotnet add package ThoughtSpot.RestApi.Sdk --version 2.27.1 ---- Using the NuGet Package Manager console:: [source,bash] ---- -Install-Package ThoughtSpot.RestApi.Sdk -Version 2.27.0 +Install-Package ThoughtSpot.RestApi.Sdk -Version 2.27.1 ---- == API client configuration @@ -323,6 +323,7 @@ await api.ApplyConfigurationAsync(newConfig); [options="header"] |==== |ThoughtSpot release|Recommended SDK version +|ThoughtSpot Cloud: 26.9.0.cl|v2.28.0 or later |ThoughtSpot Cloud 26.8.0.cl|v2.27.1 or later |==== diff --git a/modules/ROOT/pages/rest-api-java-sdk.adoc b/modules/ROOT/pages/rest-api-java-sdk.adoc index 2ce0cee7e..31ef6730b 100644 --- a/modules/ROOT/pages/rest-api-java-sdk.adoc +++ b/modules/ROOT/pages/rest-api-java-sdk.adoc @@ -281,6 +281,7 @@ Note the recommendation of Java SDK: [options='header'] |==== |ThoughtSpot release version|Supported SDK version +|ThoughtSpot Cloud: 26.9.0.cl|v2.28.0 or later |ThoughtSpot Cloud: 26.8.0.cl|v2.27.1 or later |ThoughtSpot Cloud: 26.7.0.cl|v2.26.0 or later |ThoughtSpot Cloud: 26.6.0.cl|v2.25.0 or later diff --git a/modules/ROOT/pages/rest-api-python-sdk.adoc b/modules/ROOT/pages/rest-api-python-sdk.adoc index 183851120..6a1cf354b 100644 --- a/modules/ROOT/pages/rest-api-python-sdk.adoc +++ b/modules/ROOT/pages/rest-api-python-sdk.adoc @@ -373,6 +373,7 @@ on every request. [options='header'] |==== |ThoughtSpot release version|Recommended SDK version +a|ThoughtSpot Cloud: 26.9.0.cl|v2.28.0 or later a|ThoughtSpot Cloud: 26.8.0.cl | v2.27.1 or later a|ThoughtSpot Cloud: 26.7.0.cl | v2.26.0 or later |==== diff --git a/modules/ROOT/pages/rest-api-sdk-libraries.adoc b/modules/ROOT/pages/rest-api-sdk-libraries.adoc index 31eafefd1..59c6b3ce5 100644 --- a/modules/ROOT/pages/rest-api-sdk-libraries.adoc +++ b/modules/ROOT/pages/rest-api-sdk-libraries.adoc @@ -1,8 +1,8 @@ -= SDK libraries += REST API SDK libraries :toc: true :toclevels: 1 -:page-title: SDK libraries +:page-title: REST API SDK libraries :page-pageid: rest-api-sdk-libraries :page-description: ThoughtSpot provides SDK libraries that allow you to integrate ThoughtSpot REST APIs in your application. diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index 3710ff63d..ddcae33f9 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -201,6 +201,7 @@ const test = async () => { [options='header'] |==== |ThoughtSpot release version|Recommended SDK version +|ThoughtSpot Cloud: 26.9.0.cl|v2.28.0 or later |ThoughtSpot Cloud: 26.8.0.cl|v2.27.1 or later |ThoughtSpot Cloud: 26.7.0.cl|v2.26.0 or later |ThoughtSpot Cloud: 26.6.0.cl|v2.25.0 or later diff --git a/modules/ROOT/pages/rest-apiv1-changelog.adoc b/modules/ROOT/pages/rest-apiv1-changelog.adoc index e0bcc2d87..5e3475688 100644 --- a/modules/ROOT/pages/rest-apiv1-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv1-changelog.adoc @@ -6,9 +6,11 @@ :page-pageid: rest-v1-changelog :page-description: Changelog of REST APIs -This changelog lists only the changes introduced in REST API v1. For information about new embedding features and enhancements, see xref:whats-new.adoc[What's New]. - +[IMPORTANT] +==== +The REST API v1 framework is deprecated and replaced with REST API v2 endpoints. Existing integrations that use REST API v1 endpoints will continue to function without disruption. However, ThoughtSpot strongly recommends updating your integrations to use REST API v2 endpoints and API workflows. For more information about REST API v2 endpoints, see xref:rest-api-v2-reference.adoc[REST API v2 Reference]. +==== == Version 10.4.0.cl, November 2024 diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index a52c591f3..7e201fe2f 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,91 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 26.9.0.cl, September 2026 + +=== Answer Export API + +The following enhancements for the `POST /api/rest/2.0/report/answer` endpoint are now GA: + +`type` parameter:: +The request body accepts a new `type` parameter that specifies the kind of Answer to export: ++ +* `SAVED` (default): exports a saved Answer. +* `PINNED`: exports a pinned Answer from a Liveboard. + +Pinned Answer export:: +Set `type` to `PINNED` to export a pinned Answer (a visualization on a Liveboard) directly. The Answer downloads with Liveboard context: Liveboard-level filters, Runtime Filters, and Column Security Rules are applied automatically. + +Personalized View support:: +Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. + +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter-generated Answers, in addition to CSV and PNG. + +Custom PNG dimensions:: +Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. + +Display scaling:: +Use `scaling` to adjust the relative size of chart elements in a PNG export without cropping the image. + +Dynamic file naming:: +Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. + +For more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer Report API]. + +=== Snowflake Semantic View integration APIs +This release introduces the following new REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. + +* `POST /api/rest/2.0/semantic-integrations/create` + +Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +* `POST /api/rest/2.0/semantic-integrations/search` + +Returns a list of semantic integrations matching the specified filter criteria. +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` + +Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + +Deletes a semantic integration and its generated ThoughtSpot data model. + +For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + +=== Conversation sharing APIs +ThoughtSpot introduces the following REST API v2.0 endpoints to share Spotter agent conversations with other users or groups. + +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` + +Share a conversation with users or groups with `READ_ONLY` access. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` + +Retrieve the shared messages and answers in a conversation. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` + +Retrieve the list of principals a conversation is shared with and their access levels. + +For more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. + +=== KPI Sparkline setting in metadata search response +The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` parameter in the `AnswerSpecHeader` object for KPI chart type answers. This boolean parameter indicates whether the sparkline trend line is enabled for the KPI visualization. + +//// +=== Outline Encoding for Muze charts +Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. + +The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. +//// + +=== Personalized Views TML portability +The Personalized Views TML portability feature is now GA and enabled on all ThoughtSpot Embedded instances: + +* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained while delegating ownership to another user during import. +* The `obj_id` field provides a stable cross-environment identifier for inter-Org deployments. +* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. + +For more information, see xref:tml-import.adoc#personalized-views-portability[Personalized Views portability in TML]. + +=== Support for Scheduled Liveboards process type in Connection configuration +The connection configuration API endpoints now support `SCHEDULED_LIVEBOARDS` as a process type: + +* `POST /api/rest/2.0/connection/configuration/create` +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + +Administrators can add `SCHEDULED_LIVEBOARDS` as a valid process type for connection configurations, allowing scheduled Liveboard delivery jobs to use an alternative connection configuration, with separate warehouse, credentials, or non-OAuth authentication instead of the parent connection's defaults. + == Version 26.8.0.cl, August 2026 === Spotter AI APIs @@ -169,7 +254,7 @@ Stop in-progress agent response:: * `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + Stops a Spotter agent response that is currently in progress for a given conversation session. -For more information, see xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. +For more information, see xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. === Authentication The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allow enabling and disabling authentication. These endpoints currently support only trusted authentication. @@ -1005,7 +1090,7 @@ The `CAN_MANAGE_VERSION_CONTROL` Role privilege is required for Git integration == Version 9.12.0.cl, May 2024 -==== New features +=== New features Authentication API:: @@ -1022,7 +1107,7 @@ Allows exporting dependent Tables while exporting a Connection. * `export_connection_as_dependent` + Specifies if a Connection can be exported as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard. This parameter works only when `export_associated` is set to `true` in the API request. -==== Deprecated features +=== Deprecated features Token authentication APIs:: diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index 0eda6d3c1..8d1c79b3f 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -359,7 +359,6 @@ curl -X POST \ }' ---- -//// [#custom-app-schemes] ==== Allow custom app schemes for mobile and hybrid embeds If you are embedding ThoughtSpot in a mobile or hybrid application built with frameworks such as Capacitor or Ionic, your application may use a custom URL scheme (for example, `capacitor://localhost` or `ionic://localhost`) rather than an `https://` origin. @@ -449,7 +448,6 @@ init({ .then(d => d.token), }); ---- -//// [#csp-cors-hosts] ==== Domain name format for CSP and CORS configuration @@ -501,11 +499,11 @@ If your domain URL has a non-standard port, for example `mysite.com:8080`, make |[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported -//|URLs with custom schemes such as: + -//`capacitor://localhost` + -//`ionic://localhost` +|URLs with custom schemes such as: + +`capacitor://localhost` + +`ionic://localhost` -//|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported a|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported +|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported a|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported |Wildcard (`\*`) , (`.*`) for domain URL + |[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported a|[tag orangeBackground tick]#✓# Partial support + diff --git a/modules/ROOT/pages/semantic-integrations-api.adoc b/modules/ROOT/pages/semantic-integrations-api.adoc new file mode 100644 index 000000000..0a9f80a9e --- /dev/null +++ b/modules/ROOT/pages/semantic-integrations-api.adoc @@ -0,0 +1,376 @@ += Snowflake Semantic View integration APIs +:toc: true +:toclevels: 3 + +:page-title: Snowflake Semantic View integration APIs +:page-pageid: semantic-integrations-api +:page-description: Use the ThoughtSpot REST API v2.0 endpoints to create, search, import, and delete Snowflake Semantic View integration configurations programmatically. + +ThoughtSpot provides the Semantic View integrations REST API v2.0 endpoints to create, search, import, and delete semantic integration configurations programmatically. + +== Overview +Snowflake Semantic Views provide a governed semantic layer for data in Snowflake, including named measures, dimensions, and business-logic formulas. When you create a semantic integration in ThoughtSpot, the platform reads the semantic view definition from Snowflake and generates a corresponding ThoughtSpot data model (Worksheet). The model inherits the column names, descriptions, and formula definitions from the Snowflake Semantic View. + +You can use the semantic integration APIs to automate the following tasks: + +* Create a semantic integration that links a Snowflake Semantic View to a ThoughtSpot data model. +* Search and list existing semantic integrations. +* Re-import a semantic integration to refresh the ThoughtSpot model after the source Snowflake Semantic View has changed. +* Delete a semantic integration and its generated ThoughtSpot model. + +[NOTE] +==== +The semantic integration APIs are available on ThoughtSpot Cloud instances from 26.9.0.cl. +Snowflake is the only supported CDW connector type (`RDBMS_SNOWFLAKE`). +==== + +== Prerequisites + +To use these APIs, the authenticated user must have one of the following privileges: + +* `ADMINISTRATION` (*Can administer ThoughtSpot*) +* `DATAMANAGEMENT` (*Can manage data*) + +If Role-Based Access Control (RBAC) is enabled on your instance, the user requires `CAN_CREATE_OR_EDIT_CONNECTIONS` (*Can create/edit Connections*) privilege. + +== API endpoints + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from the CDW source and refreshes the associated ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. +|===== + +[#create-semantic-integration] +== Create a semantic integration +To create a new semantic integration by reading the specified Snowflake Semantic View and generating a corresponding ThoughtSpot data model, use the `/api/rest/2.0/semantic-integrations/create` API endpoint. On success, the response includes the integration GUID, the generated model GUID, and a per-formula import report. + + +=== Request parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `connection_identifier` | String | Yes | GUID or name of the Snowflake connection in ThoughtSpot. +| `name` | String | Yes | Display name for the semantic integration. Must be unique. +| `database_name` | String | Yes | Database name in the Snowflake CDW that contains the semantic view. +| `schema_name` | String | Yes | Schema name in the Snowflake CDW that contains the semantic view. +| `semantic_view_name` | String | Yes | Name of the Snowflake Semantic View to integrate. +| `type` | String | Yes | CDW connector type. Only accepted value: `RDBMS_SNOWFLAKE`. +| `description` | String | No | Optional description for the semantic integration. +| `tags` | Array | No | Tag GUIDs or names to associate with the integration. +|===== + +=== Response fields + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | GUID of the newly created semantic integration. +| `name` | String | Display name of the semantic integration. +| `model_id` | String | GUID of the ThoughtSpot data model generated for this integration. +| `model_name` | String | Display name of the generated ThoughtSpot data model. +| `semantic_report` | Object | Per-formula import report. See <<_semantic_report_fields>>. +|===== + +[#semantic-report-fields] +=== Semantic report fields + +The `semantic_report` object contains a summary and a list of per-formula import results. + +`summary` fields: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `total` | Integer | Total number of formulas in the Snowflake Semantic View. +| `imported` | Integer | Number of formulas successfully imported. +| `failed` | Integer | Number of formulas that failed to import. +| `skipped` | Integer | Number of formulas that were skipped. +|===== + +`formulas` array — each entry contains: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | Formula GUID in the generated ThoughtSpot model. +| `name` | String | Formula name. +| `description` | String | Formula description. +| `source_expression` | String | Original CDW expression. +| `translated_formula` | String | Equivalent ThoughtSpot formula expression. +| `import_status` | String | One of `IMPORTED`, `FAILED`, or `SKIPPED`. +| `change_status` | String | One of `NEW`, `UPDATED`, or `UNCHANGED`. Null on initial create (populated by import). +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/create' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "connection_identifier": "", + "name": "Sales Semantic View", + "database_name": "SALES_DB", + "schema_name": "PUBLIC", + "semantic_view_name": "SALES_SEMANTIC_VIEW", + "type": "RDBMS_SNOWFLAKE", + "description": "Semantic integration for the Sales Snowflake Semantic View" +}' +---- + +=== Example response + +[source,JSON] +---- +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Sales Semantic View", + "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "model_name": "Sales Semantic View", + "semantic_report": { + "summary": { + "total": 5, + "imported": 4, + "failed": 0, + "skipped": 1 + }, + "formulas": [ + { + "id": "formula-guid-001", + "name": "Total Revenue", + "description": "Sum of all revenue", + "source_expression": "SUM(revenue)", + "translated_formula": "sum(revenue)", + "import_status": "IMPORTED", + "change_status": null + } + ] + } +} +---- + +[#search-semantic-integrations] +== Search semantic integrations + +To fetch a paginated list of semantic integrations matching the specified criteria, use the `/api/rest/2.0/semantic-integrations/search` API endpoint. Returns all integrations if no filters are specified. + +=== Request parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `pattern` | String | No | Substring filter to narrow search results by integration name. +| `author_identifiers` | Array | No | Filter by the GUID or username of the user who created the integration. +| `connection_identifiers` | Array | No | Filter by the GUID or name of the Snowflake connection associated with the integration. +| `sort_options` | Object | No | Sort configuration. See <<_sort_options>>. +| `record_offset` | Integer | No | Number of records to skip for pagination. Minimum: 0. Default: 0. +| `record_size` | Integer | No | Maximum number of records to return. Use `0` to return all records. Default: 10. +|===== + +[#sort-options] +==== Sort options + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `field_name` | String | Sort field. One of: `NAME`, `AUTHOR`, `CREATED_TIME`, `MODIFIED_TIME`. +| `order` | String | Sort direction. `ASC` for ascending, `DESC` for descending. +|===== + +=== Response fields + +Returns an array of objects, each with the following fields: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | GUID of the semantic integration. +| `name` | String | Display name of the semantic integration. +| `description` | String | Description of the semantic integration. Null if not set. +| `model_id` | String | GUID of the associated ThoughtSpot data model. +| `model_name` | String | Display name of the associated ThoughtSpot data model. +| `import_type` | String | How the semantic definition was sourced. `CDW` for Snowflake Semantic View; `FILE` for file upload. +| `type` | String | CDW connector type. Currently always `RDBMS_SNOWFLAKE`. +| `connection_id` | String | GUID of the Snowflake connection. +| `connection_name` | String | Display name of the Snowflake connection. +| `author_id` | String | GUID of the user who created the integration. +| `author_name` | String | Username of the user who created the integration. +| `creation_time_in_millis` | Float | Creation time in Unix epoch milliseconds. +| `modification_time_in_millis` | Float | Last modification time in Unix epoch milliseconds. +| `tags` | Array | Tags associated with the integration, each with `id` and `name`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/search' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "connection_identifiers": [""], + "sort_options": { + "field_name": "MODIFIED_TIME", + "order": "DESC" + }, + "record_size": 20, + "record_offset": 0 +}' +---- + +[#import-semantic-integration] +== Import a semantic integration +To re-import semantic updates from the Snowflake CDW source for an existing integration, and rebuild the corresponding ThoughtSpot data model, send a `POST` request to the `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` API endpoint. Send this API request, after the source Snowflake Semantic View has been updated (formulas added, removed, or modified) to bring the ThoughtSpot model back in line with the CDW definition. + +[NOTE] +==== +Importing updates is not supported for integrations created using the file upload option in the ThoughtSpot UI. To refresh a file-upload-based integration, use the ThoughtSpot UI. +==== + +The import operation: + +* Preserves the integration GUID, name, and `model_id`. Only the formula set is refreshed. +* Returns the same `semantic_report` response as create, with an additional `change_status` per formula indicating whether each formula is `NEW`, `UPDATED`, or `UNCHANGED` since the previous import. + + +=== Path parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `semantic_integration_identifier` | String | Yes | GUID or name of the semantic integration to re-import. +|===== + +=== Response fields + +Same as <>, with the addition of the `change_status` field in each formula entry: + +[width="100%"] +[options="header"] +|===== +| `change_status` value | Description +| `NEW` | Formula is new since the previous import. +| `UPDATED` | Formula definition changed since the previous import. +| `UNCHANGED` | Formula is unchanged since the previous import. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/import' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' +---- + +=== Example response + +[source,JSON] +---- +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Sales Semantic View", + "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "model_name": "Sales Semantic View", + "semantic_report": { + "summary": { + "total": 6, + "imported": 5, + "failed": 0, + "skipped": 1 + }, + "formulas": [ + { + "id": "formula-guid-001", + "name": "Total Revenue", + "description": "Sum of all revenue", + "source_expression": "SUM(revenue)", + "translated_formula": "sum(revenue)", + "import_status": "IMPORTED", + "change_status": "UNCHANGED" + }, + { + "id": "formula-guid-002", + "name": "Net Profit", + "description": "Revenue minus costs", + "source_expression": "SUM(revenue) - SUM(costs)", + "translated_formula": "sum(revenue) - sum(costs)", + "import_status": "IMPORTED", + "change_status": "NEW" + } + ] + } +} +---- + +[#delete-semantic-integration] +== Delete a semantic integration +To permanently delete the specified semantic integration and its generated ThoughtSpot data model from the system, use the `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` API endpoint. + +[WARNING] +==== +Deletion is permanent and cannot be undone. If you need to restore the integration, use the `create` endpoint to re-import the Snowflake Semantic View. +==== + +=== Path parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `semantic_integration_identifier` | String | Yes | GUID or name of the semantic integration to delete. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/delete' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' +---- + +A successful delete returns HTTP `200` with an empty response body. + +== Error responses + +[width="100%"] +[options="header"] +|===== +| Code | Description +| 400 | Bad Request — required parameter missing or invalid value (for example, unsupported `type`). +| 401 | Unauthorized — authentication token missing, expired, or invalid. +| 403 | Forbidden — the caller lacks the required privilege. +| 404 | Not Found — no semantic integration exists with the given identifier. +|===== + +== Related resources + +* xref:connections.adoc[Data connections] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] diff --git a/modules/ROOT/pages/set-default-page.adoc b/modules/ROOT/pages/set-default-page.adoc index ee51073cf..2d2d1661e 100644 --- a/modules/ROOT/pages/set-default-page.adoc +++ b/modules/ROOT/pages/set-default-page.adoc @@ -1,4 +1,4 @@ -= Customize default page and navigation path += Set default landing page and navigation :toc: true :toclevels: 2 @@ -16,8 +16,10 @@ The `pageId` parameter in `AppEmbed` sets the default ThoughtSpot page to load u * `Page.Search` for the ThoughtSpot *Search* page + * `Page.Answers` for the *Answers* page + * `Page.Liveboards` for the *Liveboards* page + +* * `Page.Data` for the *Data* page + * `Page.SpotIQ` for the *SpotIQ* analyses page +* `Page.Collections` for the *Collections* list page === Example @@ -66,6 +68,10 @@ The `path` parameter allows setting the default ThoughtSpot application page usi * `path: "monitor"` + * `path: "home/monitor-alerts"` + * `path: "insights/monitor-alerts"` +|Collections|`path: "collections"`| Supported settings include: + +* `path: "collections"` + +* `path: "home/collections"` + |===== === Example diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index caea17b5e..383af675b 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -19,48 +19,60 @@ The key capabilities of the Spotter APIs include the following: * Recommending relevant datasets or data sources * Decomposing complex user queries -== API endpoints - -The AI REST API endpoints listed in the following table provide all the functionality necessary to implement a Spotter 3 conversational experience in your application, from data source discovery through to streaming query responses. +== Supported API endpoints The API endpoints introduced for Spotter 2 also support Spotter 3 capabilities as of version 26.2.0.cl. Some of these API endpoints are deprecated in 26.5.0.cl; ThoughtSpot recommends using the new API endpoints instead. Initialize session:: -Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. +Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. See xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. Execute queries:: -To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. +To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. See xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. Real-time output (streaming):: -To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. +To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. See xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs]. + +Share a conversation:: +Share a saved Spotter conversation with other users or groups as read-only content. See xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs]. -=== Supported API endpoints [width="100%" cols="1"] |===== a|`POST /api/rest/2.0/ai/agent/conversation/create` + -xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[Creates a conversation session with the Spotter agent] to generate Answers for the specified data context. +xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[Creates a conversation session with the Spotter agent] to generate Answers for the specified data context. __Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards. Breaking changes introduced in 26.5.0.cl.__ a| `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[Sends natural language messages] to an existing Spotter agent conversation and returns the complete response synchronously. +xref:spotter-agent-conversation-apis.adoc#_send_queries_to_a_conversation_session[Sends natural language messages] to an existing Spotter agent conversation and returns the complete response synchronously. __Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse__. a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_send_a_query_to_agent_and_get_streaming_responses[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. +xref:spotter-agent-streaming-apis.adoc[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. __Replaces /api/rest/2.0/ai/agent/converse/sse__. a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + +xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + __Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ a| `POST /api/rest/2.0/ai/data-source-suggestions` [beta betaBackground]^Beta^ + -xref:spotter-agent-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + +xref:spotter-agent-data-literacy-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + __Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. a| `POST /api/rest/2.0/ai/relevant-questions/` [beta betaBackground]^Beta^ + -xref:spotter-agent-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + +xref:spotter-agent-data-literacy-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + __Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. +a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. Use `grant` and `revoke` arrays to manage access. Shared conversations are `READ_ONLY`. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with and whether the shared content is outdated. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. __Deprecated in 26.5.0.cl__. @@ -70,1223 +82,19 @@ Legacy API endpoint to send natural language queries to a conversation session w __Deprecated in 26.5.0.cl__. |===== -== Create a conversation session with Spotter Agent - -The `/api/rest/2.0/ai/agent/conversation/create` API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID. - -=== Request parameters -The request body must include the `metadata_context`. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries. - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Form parameter| Description -|`metadata_context` a| Defines the data context for the conversation. - -* `type` + -Metadata context type. The context type is mandatory. Select one of the following values: - -** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. -** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + -To set a specific data source object, use `data_source_identifier`. + -To set multi-data context, use `data_source_identifiers`. -** `data_source` [.version-badge.deprecated]#Deprecated# + -This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the `DATA_SOURCE` with `data_source_context` and data source IDs instead. - -|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: - -* `enable_contextual_change_analysis` + -__Boolean__. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions. -* `enable_natural_language_answer_generation` + -__Boolean__. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions. -* `enable_reasoning` + -__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions. -* `enable_save_chat` + -When set to `true`, adds the conversation to chat history. -|===== - -=== Example request - -With AUTO_MODE for metadata context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "AUTO_MODE" - }, - "conversation_settings": { - "enable_save_chat": true - } -}' ----- - -For a single data source as the data context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "DATA_SOURCE", - "data_source_context": { - "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" - } - }, - "conversation_settings": {} -}' ----- - -For multi-data source context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "DATA_SOURCE", - "data_source_context": { - "data_source_identifiers": [ - "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "b2c3d4e5-f6a7-8901-bcde-f12345678901" - ] - } - }, - "conversation_settings": { - "enable_save_chat": true - } -}' ----- - -=== API response - -If the API request is successful, the API returns the conversation ID and identifier in the response body. - -[source,JSON] ----- -{ - "conversation_id": "wwHQ5j8O8dQC", - "conversation_identifier": "wwHQ5j8O8dQC" -} ----- - -* `conversation_identifier` + -Use this for all subsequent message calls. -* `conversation_id` [.version-badge.deprecated]#Deprecated# + -Returns the same value as `conversation_identifier`. - -== Send queries to a conversation session - -To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint. - -This API operation requires the conversation ID obtained from the conversation creation API endpoint (`/api/rest/2.0/ai/agent/conversation/create`). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format. - -=== Request parameters - -[width="100%" cols="2,2,4"] -[options='header'] -|===== -|Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. -|`messages`|Form parameter|_Array of strings_. Required. Specify at least one query in natural language. For example, `total sales of jackets last month`. -|===== - - -//// -|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: - -* `enable_contextual_change_analysis` + -__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. -* `enable_natural_language_answer_generation` + -__Boolean__. Allows sending natural language queries to the conversation session. -* `enable_reasoning` + -__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. -//// - -=== Request and response examples - -The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "messages": [ - "Sales in 2025 vs 2024" - ] -}' ----- - -If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts: - -[source,JSON] ----- -[ - { - "type": "text", - "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "text", - "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "answer", - "title": "Compare total sales for 2025 vs 2024", - "description": "", - "session_id": "842bb67a-e08e-4861-97e8-8db9538db51d", - "gen_no": 2, - "sage_query": "[sales] [date] = '2025' vs [date] = '2024'", - "tml_tokens": ["[sales]", "[date] = '2025' vs [date] = '2024'"], - "formulas": [], - "parameters": [], - "subqueries": [], - "viz_suggestion": "CAEQIBomEiQ2NjE5NzI0Yy1kMjVlLTU4MDItOWNjOC1jNDA3MWY3OWY5MzAoATIA", - "metadata": { - "output": "", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "chart_type": "KPI", - "interrupted": false, - "data_awareness_enabled": true - }, - "internal": {} - }, - { - "type": "text", - "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.", - "metadata": {}, - "internal": {}, - "agent_context": "" - } -] ----- - -The following example sends a follow-up question to the same conversation session. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "messages": [ - "Now break that down by product category" - ] -}' ----- - -If the request is successful, the agent returns the response for the follow-up question: - -[source,JSON] ----- -[{ - "type": "text", - "text": "I'll add product category to the comparison.", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "answer", - "title": "Sales by Product Category: 2025 vs 2024", - "session_id": "9abc1234-0000-0000-0000-000000000005", - "gen_no": 3, - "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'", - "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"], - "formulas": [], - "parameters": [], - "subqueries": [], - "viz_suggestion": "", - "metadata": { - "chart_type": "BAR", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" - }, - "internal": {} - }] ----- - -In each response, the agent returns the following information: - -* `type` + -Type of the message, such as text, answer, or error. -* `text` + -Response message generated for the query. -* `metadata` + -Additional information based on the message type. For example, answer metadata, chart type, or the data source ID. -* `tml_tokens` + -Query string broken down as TML tokens. - -In case of errors, the response returns the error details: - -[source,JSON] ----- -[{ - "type": "error", - "message": "The conversation session has expired. Please create a new conversation.", - "code": "SESSION_EXPIRED" -}] ----- - - - -//// -The following example shows the response text contents for the `answer` message type. - -[source,JSON] ----- -[ - { - "id": "r24X7D99SROD", - "type": "answer", - "group_id": "o8dQ9SAWdtrL", - "metadata": { - "sage_query": "[sales] [item type] = [item type].'jackets'", - "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", - "gen_no": 1, - "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", - "generation_number": 1, - "warning_details": null, - "ambiguous_phrases": null, - "query_intent": null, - "assumptions": "You want to see the total sales amount for jackets item type.", - "tml_phrases": [ - "[sales]", - "[item type] = [item type].'jackets'" - ], - "cached": false, - "sub_queries": null, - "title": "Net sales of Jackets", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" - }, - "title": "Net sales of Jackets" - } -] ----- - -The session ID and generation number serve as the data context for the Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create`, or download the answer via the `/api/rest/2.0/report/answer` API endpoint. - - -* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. -//// - -== Send a query to agent and get streaming responses - -To send queries to an ongoing conversation session with Spotter agent and receive streaming responses, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally in real time, rather than waiting for the entire response to be generated before sending it to the client. - -The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API can be used as an integrated tool for real-time streaming of conversational interactions between agents and the ThoughtSpot backend. - -=== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Parameter| Description -|`conversation_identifier` |__String__. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. -|`messages`|_Array of strings_. Include at least one natural language query. For example, `Sales data for Jackets`, `Top performing products in the west coast`. -|===== - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "conversation_identifier": "h2I_pTGaRQof", - "messages": [ - "Net sales of Jackets" - ] -}' ----- - -=== API response - -If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. - -Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with the `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). - -The API uses this format so that the clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows, the receiving client or agent listens to the SSE stream, parses each event, and assembles the full response for its users. - -==== Example response -If the request is valid, the API returns SSE streams. Each line has the form `data: [{"type": "...", ...}]`, a JSON array of event objects. - -[source,JSON] ----- -data: [{"type":"ack","node_id":"aGxzcFVrtom8"}] - -data: [{"type":"conv_title","title":"Sales 2025 vs 2024","conv_id":"-XIi04l5rrof"}] - -data: [{"type":"notification","group_id":"cDEsAQbSnd3J","metadata":{"type":"thinking","tool_title":"Analyzing Sales Performance: 2025 vs 2024"},"code":"TOOL_CALL_NOTIFICATION"}] - -data: [{"id":"mNAdvy-NK2l6","type":"text-chunk","group_id":"cDEsAQbSnd3J","metadata":{"format":"markdown","type":"thinking"},"content":"\n\nI need to compare sales performance between 2025 and 2024."}] - -data: [{"type":"notification","group_id":"m1MTvttEUa7o","code":"nls_start"}] - -data: [{"id":"hxWMDP-pgR3B","type":"answer","group_id":"m1MTvttEUa7o","metadata":{"sage_query":"[sales] [date] = '2025' vs [date] = '2024'","session_id":"431adcf9-1328-4d8c-81a1-0faa7fa37ba6","title":"Compare sales for 2025 vs 2024"},"title":"Compare sales for 2025 vs 2024"}] - -data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] ----- -For the complete response in one payload, use the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. - -//// -[source,] ----- -data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] - -data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] ----- -//// - -==== SSE event types -The SSE event types streamed in the API response include: - -* `ack` + -Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. -* `conv_title` + -A conversation title (`title`, `conv_id`). -* `notification` + -Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. -* `type` + -Type can be `thinking`, `text`. -* `text` + -Complete text block in markdown format. -* `text-chunk` + -Text fragments in incremental streaming, often in markdown (`id`, `group_id`, `metadata` with `format`) -* `content` + -The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. -* `text` + -Full text block with same structure as text-chunk. -* `answer` + -Structured answer with metadata (`id`, `group_id`, `metadata` with `sage_query`, `session_id`, `title` and more) -* `error` + -In case of failures. -* `*-interrupt` + -If the generation was stopped mid-stream. -* `group_id` + -Groups related chunks together. - -For more information and examples, see xref:spotter-agent-apis.adoc#_sse_event_payload_reference[SSE event payload reference]. - -=== Thinking versus output events -Spotter responses have two phases: - -* A *thinking phase*, where the AI reasons through the query and calls internal tools, followed by an *output phase* containing the final response delivered to the user. + - -Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All other events are final output. - -Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. - -[listing] ----- -THINKING PHASE -─────────────────────────────────────────────────────────── -ack - -┌─ group_id: g1 ── Tool Call 1 ("Searching data") ─────────┐ -│ notification (thinking, TOOL_CALL_NOTIFICATION) │ -│ text-chunk (thinking) │ -│ answer (thinking) │ -└──────────────────────────────────────────────────────────┘ - -┌─ group_id: g2 ── Tool Call 2 ("Running code") ───────────┐ -│ notification (thinking, TOOL_CALL_NOTIFICATION) │ -│ text-chunk (thinking) │ -│ text-chunk (thinking) │ -└──────────────────────────────────────────────────────────┘ - -notification (FINAL_RESPONSE_NOTIFICATION) ←── boundary -──────────────────────────────────────────────────────────── - -OUTPUT PHASE -──────────────────────────────────────────────────────────── -┌─ group_id: g3 ────────────────────────────────────────────┐ -│ text "Here are the results:" │ -│ answer (final visualization) │ -└───────────────────────────────────────────────────────────┘ -[stream closes] ----- - -==== Notification codes reference - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Code| When it appears -|`QH`|Query handling started -|`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML -|`ANSWER_GEN`|Generating an answer -|`IDENTIFYING_ATTRIBUTES`|Identifying data attributes -|`PERFORMING_CHANGE_ANALYSIS`|Running change analysis -|`PERFORMING_FORECASTING_ANALYSIS`|Running forecasting -|`SUMMARIZING_RESULTS`|Summarizing results -|`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) -|`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output -|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete -|`approval_required`|An external tool requires user permission before proceeding -|===== - -=== SSE event payload reference - -==== ack - -[source,JSON] ----- -data: { - "type": "ack", - "group_id": "a1b2c3", - "id": "evt-001", - "node_id": "resp-node-abc" -} ----- - -==== notification (thinking — tool call) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g1", - "id": "evt-002", - "code": "TOOL_CALL_NOTIFICATION", - "message": "Searching for relevant data", - "metadata": { - "type": "thinking", - "tool_title": "Searching sales data", - "tool_code": "RUNNING_CODE_EXECUTION", - "tool_name": "code_interpreter" - } -} ----- - -==== notification (thinking - external tool with MCP integration) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g2", - "id": "evt-003", - "code": "TOOL_CALL_NOTIFICATION", - "message": "Querying Salesforce", - "metadata": { - "type": "thinking", - "tool_title": "Salesforce: Get Opportunities", - "tool_name": "get_opportunities", - "integration_id": "int-sf-123", - "integration_name": "Salesforce" - } -} ----- - -==== notification (approval required) -Sent when an external MCP tool requires explicit user permission before proceeding. Your application should prompt the user to approve or deny the action before continuing. - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g2", - "id": "evt-005", - "code": "approval_required", - "metadata": { - "request_id": "perm-req-789", - "integration_id": "int-sf-123", - "integration_name": "Salesforce", - "tool_name": "get_opportunities", - "annotated_title": "Access Salesforce Opportunities" - } -} ----- - -==== notification (FINAL_RESPONSE_NOTIFICATION) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g1", - "id": "evt-004", - "code": "FINAL_RESPONSE_NOTIFICATION", - "message": "" -} ----- - -==== text - -[source,JSON] ----- -data: { - "type": "text", - "group_id": "g3", - "id": "evt-007", - "content": "Here is the total revenue breakdown by region for Q4 2025:\n\n- **North America:** $4.2M\n- **EMEA:** $2.8M\n- **APAC:** $1.5M" -} ----- - -==== text-chunk -Multiple chunks sharing the same `id` should be appended together to reconstruct the full text item. - -[source,JSON] ----- -data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "Based on the analysis, " } -data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "revenue grew 12% quarter-over-quarter." } ----- - -==== answer -When an `answer` event is received, the `session_id` and `gen_no` fields are returned. You can export the visualization data using the Export Answer Report API to process the results. This allows users to download the answer as a PDF, PNG, CSV, or XLSX file. - -[source,JSON] ----- -data: { - "type": "answer", - "group_id": "g3", - "id": "evt-010", - "title": "Revenue by Region Q4 2025", - "metadata": { - "session_id": "sess-abc-123", - "gen_no": 1, - "transaction_id": "txn-456", - "worksheet_id": "ws-def-789", - "cached": false, - "is_hidden": false - } -} ----- - -==== search_datasets -Emitted as a start/end pair during Auto mode data source discovery. - - -[source,JSON] ----- -data: { "type": "search_datasets", "group_id": "g0", "id": "evt-012", "code": "search_datasets_start", "metadata": {} } - -data: { - "type": "search_datasets", - "group_id": "g0", - "id": "evt-013", - "code": "search_datasets_end", - "metadata": { - "data_sources": [ - { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Contains revenue columns" }, - { "worksheet_id": "ws-2", "worksheet_name": "Marketing Data", "confidence": "low", "reasoning": "No revenue columns" } - ], - "auto_selected": { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Best match" } - } -} ----- -==== file - -[source,JSON] ----- -data: { - "type": "file", - "group_id": "g3", - "id": "evt-014", - "files": [ - { "ts_file_id": "file-abc-001", "display_name": "quarterly_report.csv", "file_type": "csv", "created_at": "2025-11-15T10:30:00Z" }, - { "ts_file_id": "file-abc-002", "display_name": "chart.png", "file_type": "png", "created_at": "2025-11-15T10:30:01Z" } - ], - "metadata": { "conv_id": "conv-123" } -} ----- -==== conv_title - -[source,JSON] ----- -data: { - "type": "conv_title", - "group_id": "g0", - "id": "evt-015", - "title": "Revenue Analysis Q4 2025", - "conv_id": "conv-123" -} ----- - -==== error - -[source,JSON] ----- -data: { - "type": "error", - "group_id": "g3", - "id": "evt-016", - "code": "RATE_LIMIT_EXCEEDED", - "message": "Too many requests", - "display_message": "You've exceeded the rate limit. Please try again in a few minutes." -} ----- -==== agent-interrupt - -[source,JSON] ----- -Sent when generation is stopped mid-stream. -data: { - "type": "notification", - "group_id": "g3", - "id": "evt-017", - "code": "agent-interrupt", - "message": "Generation stopped" -} ----- - -[#_stop_an_in_progress_agent_response] -== Stop an in-progress agent response - -The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. - -Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. - -=== Request parameters - -[width="100%", cols="2,2,4"] -[options='header'] -|===== -|Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. -|===== - -This endpoint does not require a request body. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' ----- - -=== Example response - -If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. - -If the conversation session is not found or has expired, the API returns an error: - -[source,JSON] ----- -{ - "error_code": "CONVERSATION_NOT_FOUND", - "message": "The specified conversation session does not exist or has expired." -} ----- - -[#process_results] -== Process results generated from a conversation session -To export or download the Answer data generated by the Spotter APIs, use the xref:report-apis-v2.adoc#exportSpotterData[Answer report] API. - -The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. - -NOTE: Requires at least view access to the Answer. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {Bearer_token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "session_identifier": "sess-abc-123", - "generation_number": 1, - "file_format": "CSV" -}' ----- -The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. - -[NOTE] -==== -Using tokens generated by the Spotter API in a xref:data-apis-v2.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:report-apis-v2.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. -==== - - -== Data literacy and query assistance -The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. - -=== Get data source suggestions - -The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. - -==== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|==== -|Parameter| Description -|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: - -* `data_source_identifiers` + -__Array of strings__. IDs of the data source object such as Models. -* `answer_identifiers` + -__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. -* `conversation_identifier` + -__String__. ID of the conversation session. -* `liveboard_identifiers` + -__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. - -| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. -|`limit_relevant_questions` + -__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. -|`bypass_cache` + -__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. -|`ai_context` + -__Optional__. a| Additional context to guide the response. Define the following attributes as needed: -|==== - -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "data_source_identifiers": [ - "cd252e5c-b552-49a8-821d-3eadaa049cca" - ] - }, - "query": "Net sales of Jackets in west coast", - "limit_relevant_questions": 3 -}' ----- - -==== API response -If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. - -[source,JSON] ----- -{ - "relevant_questions": [ - { - "query": "What is the trend of sales by type over time?", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales by item", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales across regions", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - } - ] -} ----- - -The returned results include metadata such as: - -* `confidence` + -A float indicating the Model's confidence in the relevance of each recommendation. -* `details` + -The data source ID, name, and description for each recommended data source. -* `reasoning` + -Reason provided by the LLM to explain why each data source was recommended. - -=== Get relevant questions - -The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. - -During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. - -==== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Parameter| Description -|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: - -* `data_source_identifiers` + -__Array of strings__. IDs of the data source object such as Models. -* `answer_identifiers` + -__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. -* `conversation_identifier` + -__String__. ID of the conversation session. -* `liveboard_identifiers` + -__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. - -| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. -|`limit_relevant_questions` + -__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. -|`bypass_cache` + -__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. -|`ai_context` + -__Optional__. a| Additional context to guide the response. Define the following attributes as needed: - -* `instructions` + -__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. -* `content` + -__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. -|===== - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "data_source_identifiers": [ - "cd252e5c-b552-49a8-821d-3eadaa049cca" - ] - }, - "query": "Net sales of Jackets in west coast", - "limit_relevant_questions": 3 -}' ----- - -==== Example response -If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: - -* `query` + -A string containing the natural language (NL) sub-question. -* `data_source_identifier` + -GUID of the data source object. -* `data_source_name` + -Name of the associated data source object. - -[source,JSON] ----- -{ - "relevant_questions": [ - { - "query": "What is the trend of sales by type over time?", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales by item", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales across regions", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - } - ] -} ----- - == Additional resources +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] + +Create conversation sessions, send synchronous queries, and stop in-progress responses. +* xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs] + +Send queries and receive real-time Server-Sent Events (SSE) responses from the Spotter agent. +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] + +Export or download Answers generated by a Spotter agent conversation session. +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] + +Get data source suggestions and decompose a user query into relevant sub-questions. +* xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs] + +Share saved Spotter conversations with other users and groups. +* xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations] + +Retrieve, update, and delete saved Spotter 3 conversations and their messages. * Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. * For information about MCP tools, see xref:mcp-integration.adoc[MCP server integration]. diff --git a/modules/ROOT/pages/spotter-agent-conversation-apis.adoc b/modules/ROOT/pages/spotter-agent-conversation-apis.adoc new file mode 100644 index 000000000..1e094a6aa --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-conversation-apis.adoc @@ -0,0 +1,385 @@ += Spotter agent conversation APIs +:toc: true +:toclevels: 2 + +:page-title: Spotter agent conversation APIs +:page-pageid: spotter-agent-conversation-apis +:page-description: Use the Spotter agent conversation REST APIs to create conversation sessions, send natural language queries, and stop in-progress responses. + +ThoughtSpot's Spotter agent conversation APIs allow you to create a conversation session with the Spotter agent, send natural language queries to it, and stop an in-progress response. + +For information about receiving responses as a real-time event stream, see xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs]. For information about exporting Answers generated by a conversation, see xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results]. For information about the data source and question suggestion APIs, see xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs]. For information about sharing saved conversations, see xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs]. + +== Create a conversation session with Spotter Agent + +The `/api/rest/2.0/ai/agent/conversation/create` API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID. + +=== Request parameters +The request body must include the `metadata_context`. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries. + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Form parameter| Description +|`metadata_context` a| Defines the data context for the conversation. + +* `type` + +Metadata context type. The context type is mandatory. Select one of the following values: + +** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. +** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + +To set a specific data source object, use `data_source_identifier`. + +To set multi-data context, use `data_source_identifiers`. +** `data_source` [.version-badge.deprecated]#Deprecated# + +This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the `DATA_SOURCE` with `data_source_context` and data source IDs instead. + +|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions. +* `enable_save_chat` + +When set to `true`, adds the conversation to chat history. +|===== + +=== Example request + +With AUTO_MODE for metadata context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "AUTO_MODE" + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +For a single data source as the data context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "DATA_SOURCE", + "data_source_context": { + "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + } + }, + "conversation_settings": {} +}' +---- + +For multi-data source context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "DATA_SOURCE", + "data_source_context": { + "data_source_identifiers": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "b2c3d4e5-f6a7-8901-bcde-f12345678901" + ] + } + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +=== API response + +If the API request is successful, the API returns the conversation ID and identifier in the response body. + +[source,JSON] +---- +{ + "conversation_id": "wwHQ5j8O8dQC", + "conversation_identifier": "wwHQ5j8O8dQC" +} +---- + +* `conversation_identifier` + +Use this for all subsequent message calls. +* `conversation_id` [.version-badge.deprecated]#Deprecated# + +Returns the same value as `conversation_identifier`. + +== Send queries to a conversation session + +To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint. + +This API operation requires the conversation ID obtained from the conversation creation API endpoint (`/api/rest/2.0/ai/agent/conversation/create`). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format. + +=== Request parameters + +[width="100%" cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. Specify the conversation ID received from the xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. +|`messages`|Form parameter|_Array of strings_. Required. Specify at least one query in natural language. For example, `total sales of jackets last month`. +|===== + + +//// +|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. +//// + +=== Request and response examples + +The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "messages": [ + "Sales in 2025 vs 2024" + ] +}' +---- + +If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts: + +[source,JSON] +---- +[ + { + "type": "text", + "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "text", + "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "answer", + "title": "Compare total sales for 2025 vs 2024", + "description": "", + "session_id": "842bb67a-e08e-4861-97e8-8db9538db51d", + "gen_no": 2, + "sage_query": "[sales] [date] = '2025' vs [date] = '2024'", + "tml_tokens": ["[sales]", "[date] = '2025' vs [date] = '2024'"], + "formulas": [], + "parameters": [], + "subqueries": [], + "viz_suggestion": "CAEQIBomEiQ2NjE5NzI0Yy1kMjVlLTU4MDItOWNjOC1jNDA3MWY3OWY5MzAoATIA", + "metadata": { + "output": "", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "chart_type": "KPI", + "interrupted": false, + "data_awareness_enabled": true + }, + "internal": {} + }, + { + "type": "text", + "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.", + "metadata": {}, + "internal": {}, + "agent_context": "" + } +] +---- + +The following example sends a follow-up question to the same conversation session. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "messages": [ + "Now break that down by product category" + ] +}' +---- + +If the request is successful, the agent returns the response for the follow-up question: + +[source,JSON] +---- +[{ + "type": "text", + "text": "I'll add product category to the comparison.", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "answer", + "title": "Sales by Product Category: 2025 vs 2024", + "session_id": "9abc1234-0000-0000-0000-000000000005", + "gen_no": 3, + "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'", + "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"], + "formulas": [], + "parameters": [], + "subqueries": [], + "viz_suggestion": "", + "metadata": { + "chart_type": "BAR", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "internal": {} + }] +---- + +In each response, the agent returns the following information: + +* `type` + +Type of the message, such as text, answer, or error. +* `text` + +Response message generated for the query. +* `metadata` + +Additional information based on the message type. For example, answer metadata, chart type, or the data source ID. +* `tml_tokens` + +Query string broken down as TML tokens. + +In case of errors, the response returns the error details: + +[source,JSON] +---- +[{ + "type": "error", + "message": "The conversation session has expired. Please create a new conversation.", + "code": "SESSION_EXPIRED" +}] +---- + + + +//// +The following example shows the response text contents for the `answer` message type. + +[source,JSON] +---- +[ + { + "id": "r24X7D99SROD", + "type": "answer", + "group_id": "o8dQ9SAWdtrL", + "metadata": { + "sage_query": "[sales] [item type] = [item type].'jackets'", + "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", + "gen_no": 1, + "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", + "generation_number": 1, + "warning_details": null, + "ambiguous_phrases": null, + "query_intent": null, + "assumptions": "You want to see the total sales amount for jackets item type.", + "tml_phrases": [ + "[sales]", + "[item type] = [item type].'jackets'" + ], + "cached": false, + "sub_queries": null, + "title": "Net sales of Jackets", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "title": "Net sales of Jackets" + } +] +---- + +The session ID and generation number serve as the data context for the Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create`, or download the answer via the `/api/rest/2.0/report/answer` API endpoint. + + +* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. +//// + +[#_stop_an_in_progress_agent_response] +== Stop an in-progress agent response + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. + +Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. + +=== Request parameters + +[width="100%", cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. +|===== + +This endpoint does not require a request body. + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' +---- + +=== Example response + +If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. + +If the conversation session is not found or has expired, the API returns an error: + +[source,JSON] +---- +{ + "error_code": "CONVERSATION_NOT_FOUND", + "message": "The specified conversation session does not exist or has expired." +} +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] +* xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs] +* Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. diff --git a/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc b/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc index 371233233..b8b4a1dda 100644 --- a/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc @@ -42,7 +42,7 @@ __Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.__ |===== == Saving a conversation -To save a conversation, set the `enable_save_chat` parameter to `true` when sending a xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[conversation create `POST` request] to the `/api/rest/2.0/ai/agent/conversation/create` API endpoint. +To save a conversation, set the `enable_save_chat` parameter to `true` when sending a xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[conversation create `POST` request] to the `/api/rest/2.0/ai/agent/conversation/create` API endpoint. === API request example @@ -308,7 +308,7 @@ Each item in `conversations` represents a saved conversation. [options="header"] |===== |Field|Description -|`conversation_identifier`|__String__. Unique identifier of the conversation. Use this value as input in your API requests to the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[send message], xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[update conversation], xref:spotter-agent-conversation-mgmt-apis.adoc#delete-conversation[delete conversation], xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop response], and xref:spotter-agent-conversation-mgmt-apis.adoc#load-answer[load answer] endpoints. +|`conversation_identifier`|__String__. Unique identifier of the conversation. Use this value as input in your API requests to the xref:spotter-agent-conversation-apis.adoc#_send_queries_to_a_conversation_session[send message], xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[update conversation], xref:spotter-agent-conversation-mgmt-apis.adoc#delete-conversation[delete conversation], xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[stop response], and xref:spotter-agent-conversation-mgmt-apis.adoc#load-answer[load answer] endpoints. |`conversation_title` a|__String__. Display name of the conversation. |`created_at`|__String__. Timestamp of when the conversation was created. |`updated_at`|__String__. Timestamp of when the conversation was last updated. diff --git a/modules/ROOT/pages/spotter-agent-data-literacy-apis.adoc b/modules/ROOT/pages/spotter-agent-data-literacy-apis.adoc new file mode 100644 index 000000000..85ab15a91 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-data-literacy-apis.adoc @@ -0,0 +1,190 @@ += Spotter agent data literacy APIs +:toc: true +:toclevels: 2 + +:page-title: Spotter agent data literacy APIs +:page-pageid: spotter-agent-data-literacy-apis +:page-description: Use the Spotter data literacy REST APIs to get relevant data source suggestions and decompose a user query into relevant sub-questions. + +The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. + +For information about creating a conversation session, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. + +== Get data source suggestions + +The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|==== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: +|==== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +=== API response +If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +The returned results include metadata such as: + +* `confidence` + +A float indicating the Model's confidence in the relevance of each recommendation. +* `details` + +The data source ID, name, and description for each recommended data source. +* `reasoning` + +Reason provided by the LLM to explain why each data source was recommended. + +== Get relevant questions + +The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. + +During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: + +* `instructions` + +__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. +* `content` + +__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. +|===== + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +=== Example response +If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: + +* `query` + +A string containing the natural language (NL) sub-question. +* `data_source_identifier` + +GUID of the data source object. +* `data_source_name` + +Name of the associated data source object. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] diff --git a/modules/ROOT/pages/spotter-agent-process-results-apis.adoc b/modules/ROOT/pages/spotter-agent-process-results-apis.adoc new file mode 100644 index 000000000..552fc7ed8 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-process-results-apis.adoc @@ -0,0 +1,46 @@ += Process Spotter agent conversation results +:toc: true +:toclevels: 2 + +:page-title: Process Spotter agent conversation results +:page-pageid: spotter-agent-process-results-apis +:page-description: Export or download the Answer data generated by a Spotter agent conversation session using the Answer report API. + +After the Spotter agent generates an Answer in a conversation session, use the Answer report API to export or download that Answer. + +For information about sending queries to a conversation session, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. For information about the streaming response format, see xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs]. + +[#process_results] +== Process results generated from a conversation session +To export or download the Answer data generated by the Spotter APIs, use the xref:report-apis-v2.adoc#exportSpotterData[Answer report] API. + +The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. + +NOTE: Requires at least view access to the Answer. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {Bearer_token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "session_identifier": "sess-abc-123", + "generation_number": 1, + "file_format": "CSV" +}' +---- +The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. + +[NOTE] +==== +Using tokens generated by the Spotter API in a xref:data-apis-v2.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:report-apis-v2.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. +==== + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs] +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] diff --git a/modules/ROOT/pages/spotter-agent-sharing-apis.adoc b/modules/ROOT/pages/spotter-agent-sharing-apis.adoc new file mode 100644 index 000000000..674d88fa3 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-sharing-apis.adoc @@ -0,0 +1,365 @@ += Spotter agent conversation sharing APIs +:toc: true +:toclevels: 2 + +:page-title: Spotter agent conversation sharing APIs +:page-pageid: spotter-agent-sharing-apis +:page-description: Use the Spotter agent conversation sharing REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. + +You can share a Spotter conversation with other users and groups and manage shared content programmatically using REST API endpoints. + +== Supported endpoints + +[width="100%" cols="1"] +|===== +a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` + +xref:spotter-agent-sharing-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation, grants or revokes access to a shared conversation] for one or more principals. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` + +xref:spotter-agent-sharing-apis.adoc#_get_shared_content[Returns the read-only view of the shared conversation], including messages and associated answers. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` + +xref:spotter-agent-sharing-apis.adoc#_get_share_information[Returns sharing state and metadata], and the list of principals that can access the shared content. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ +|===== + +For information about creating, saving, and managing saved conversation, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] and xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. + +== Required privileges + +* To use these APIs, you need the `CAN_USE_SPOTTER` (*Can use Spotter*) privilege. +* To share a conversation or view the sharing status, you must be the owner of the conversation. Only the user who created the conversation can manage its share access. +* To retrieve shared content, you must be the conversation owner or a principal (user or group) that has been granted access. + +[NOTE] +==== +The shared view is a read-only snapshot of the conversation at the time of sharing. Recipients cannot send messages or modify the conversation. +==== + +[#_share_a_conversation] +== Share a conversation +To share a conversation with other ThoughtSpot users and groups, refresh shared content, or revoke access, send a `POST` request to the `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` endpoint. When principals are added, ThoughtSpot creates a read-only shared view of the conversation from its current state. + +The conversation to share is identified by the `conversation_identifier` URL path parameter. In your API request, you must include the GUID of the saved Spotter conversation as a path parameter and add the attributes to grant or revoke access in the request body. + +[NOTE] +==== +Do not include the same principal identifiers in both `grant` and `revoke` arrays in the same request. +==== + +=== Request parameters + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Parameter | Description +| `grant` |__Array of strings__. Array of principals to grant access to the conversation specified in the request. Specify `principal_identifier` and `principal_type`. Specify the principal type, name or GUID of the intended recipients. All recipients are granted a `READ_ONLY` access. +| `revoke` |__Array of strings__. Principals to revoke access from. Specify `principal_identifier` and `principal_type`. Specify the principal type, name or GUID of the recipients to revoke access from. +| `refresh_shared_content` |__Boolean__. When set to `true`, ThoughtSpot regenerates the shared view from the latest conversation state, even if a shared view already exists. When `false`, reuses the existing shared view. Default is `false`. +//| `notify_on_share` |__Boolean__. When set to `true`, ThoughtSpot sends an in-app notification to the recipients of the shared content. Default is `true`. Available from 26.10.0.cl. +|===== + +=== Request examples + +Grant access to a conversation:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "refresh_shared_content": false, + "grant": [ + { "principal_identifier": "user-001", "principal_type": "USER" }, + { "principal_identifier": "group-001", "principal_type": "USER_GROUP" } + ], + "revoke": [] +} +---- + +Revoke access granted to a shared conversation:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "refresh_shared_content": false, + "grant": [], + "revoke": [ + { "principal_identifier": "user-001", "principal_type": "USER" }, + { "principal_identifier": "group-001", "principal_type": "USER_GROUP" } + ] +} +---- + +Refresh shared content:: +To regenerate the shared snapshot for existing recipients without changing access, set `refresh_shared_content` to `true` with empty `grant` and `revoke` arrays. ++ +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "refresh_shared_content": true, + "grant": [], + "revoke": [] +} +---- + +Refresh shared content and update access details:: +To update access and refresh the snapshot in a single call, combine `refresh_shared_content: true` with the recipient details in the `grant` or `revoke` array. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "refresh_shared_content": true, + "grant": [ + { "principal_identifier": "user-002", "principal_type": "USER" }, + { "principal_identifier": "group-002", "principal_type": "USER_GROUP" } + ] +} +---- + +=== API response +If the request is successful, ThoughtSpot returns a 204 response code. + +[#_get_shared_content] +== Get shared conversation content +To retrieve the full read-only view of a shared conversation, including ordered messages and data source metadata, send a `GET` request to the `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` endpoint. This endpoint is accessible to the conversation owner and any principal that has been granted access. + +Use this endpoint to render a shared conversation in a UI or to retrieve its content for post-processing. + +=== Request parameters + +[width="100%"] +[options='header'] +|===== +|Parameter|Type|Description +|`conversation_identifier`|String|The unique ID of the source conversation. +|===== + +=== Example request + +[source,cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' +---- + +=== API response +If the request is successful, the API returns the shared conversation content with the following fields: + +[source,JSON] +---- +{ + "conversation_id": "conv-abc-123", + "shared_conversation_id": "snap-xyz-456", + "conversation_title": "Sales by Region Q1", + "creator_user_id": "5d3e6cc7-2f4a-4b0e-9a1c-8f2b6d4e7a10", + "data_sources": [{ "id": "ds-001", "name": "Retail Sales" }], + "analyst_ids": ["spot-7f2a"], + "messages": [ + { + "message_id": "node-u-01", + "timestamp_in_millis": 1744000000000, + "user_prompt": { + "message": { + "message_id": "msg-u-01", + "content": "Show me revenue by region." + }, + "attachments": [] + }, + "response_items": [ + { + "type": "tool_call", + "tool_call_id": "toolu-01", + "tool_name": "search_datasets", + "step_title": "Searching datasets", + "arguments": { "query": "revenue by region" }, + "timestamp_in_millis": 1744000001000, + "is_thinking": false + }, + { + "type": "answer", + "answer_id": "ans-01", + "tool_call_id": "toolu-02", + "tool_name": "fetch_and_visualize", + "step_title": "Visualizing", + "timestamp_in_millis": 1744000004000, + "is_thinking": false + }, + { + "type": "text", + "content": "Revenue is highest in APAC.", + "content_type": "TEXT_MARKDOWN", + "timestamp_in_millis": 1744000005000, + "is_thinking": false, + "step_title": null, + "file_reference": null + } + ] + } + ], + "code_execution_files": [ + { + "file_id": "revenue_by_region.csv", + "display_name": "revenue_by_region.csv", + "file_type": "csv", + "created_time_in_millis": 1744027200000, + "expired": false + } + ] +} +---- + +==== Response fields + +[width="100%"] +[options='header'] +|===== +|Field|Description +|`conversation_id`|__String__. Conversation ID sent in the request parameter. +|`shared_conversation_id`|__String__. Id of the shared snapshot. This is not the same as `conversation_id`. Pass this value as the `conversation_identifier` parameter in `loadAnswer` calls. This value changes each time the snapshot is refreshed via the share endpoint with `refresh_shared_content: true`. +|`conversation_title`|__String__. Display title of the conversation. `null` if no title was set. +|`creator_user_id`|__String__. Id of the user who created and shared the conversation. This is the original creator, not the caller retrieving the shared content. +|`data_sources`|__Array of strings__. Array of data sources used by the conversation. Each entry includes the `id` and display `name` of the data source. +|`analyst_ids`|__Array of strings__. Array of the identifiers of the AI analysts the conversation ran against. An analyst is a purpose-built agent configured over a set of data sources, with its own instructions and access rules. An empty array is returned if the conversation is not associated with any analyst. +|`messages`|__Array of conversation messages__. Ordered conversation messages, from oldest to newest. The structure is the same as returned by the get conversation endpoint. An empty array is returned when the conversation has no messages. +a|`code_execution_files`|__Array of code execution files__. Sanitized metadata for files generated by the code execution tool. Each entry in the `code_execution_files` array contains the following attributes: + +* `file_id`. __String__. Unique identifier of the file. +* `display_name`. __String__. Name of the file. +* `file_type`. __String__. File type, such as `csv`, `pdf`, or `png`. +* `created_time_in_millis`. __Long__. Milliseconds since Unix epoch when the file was created. +* `expired`.__Boolean__. When `true`, the underlying file is no longer retrievable from code execution storage. Disable download and preview options in your UI for expired files. + +If there are no code execution steps, an empty array is returned. +|===== + +=== Load answer payloads from a shared view +The full answer payload is not embedded in messages. Each `answer` response item in `messages[].response_items` contains an `answer_id` field. To retrieve the full answer payload, call `loadAnswer` with: + +* `conversation_identifier`: the `shared_conversation_id` value from this response. +* `answer_id`: the `answer_id` from the `answer` response item. + +[IMPORTANT] +==== +`shared_conversation_id` is not the same as `conversation_id`. It identifies the shared snapshot, which is a separate internal object from the source conversation. Always use the `shared_conversation_id` value as the `conversation_identifier` parameter when calling `loadAnswer` to hydrate answers from a shared view. Because this value changes each time the snapshot is refreshed, re-fetch the shared content to get the current value before calling `loadAnswer`. +==== + + +[#_get_share_information] +== Get share information +To view the current share state of a conversation you own, send a `GET` request to the `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` endpoint. The response shows whether the shared view reflects the latest conversation content and lists the principals that currently have access. + +Use this endpoint to render a share management UI, audit who has access to a conversation, or determine whether the shared view needs to be refreshed before sending a link. + +=== Request parameters + +[width="100%"] +[options='header'] +|===== +|Parameter|Description +|`conversation_identifier`|__String__. The unique ID of the conversation, as returned when creating a conversation or listing conversations. +|===== + +=== Example request + +[source,cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' +---- + +=== API response + +The following example shows the response for a conversation that is shared and current: + +[source,JSON] +---- +{ + "conversation_id": "conv-abc-123", + "is_shared_content_outdated": false, + "principals": [ + { + "id": "user-001", + "type": "USER", + "display_name": "Alice Example", + "name": "alice.example", + "permission": "READ_ONLY" + }, + { + "id": "group-001", + "type": "USER_GROUP", + "display_name": "Sales Team", + "name": "sales-team", + "permission": "READ_ONLY" + } + ] +} +---- + +The following example shows the response for a conversation that has never been shared: + +[source,JSON] +---- +{ + "conversation_id": "conv-abc-123", + "is_shared_content_outdated": null, + "principals": [] +} +---- + +When `is_shared_content_outdated` is `true`, call the share endpoint with `refresh_shared_content: true` to update the shared view with the latest conversation content. + + +==== Response fields + +[width="100%"] +[options='header'] +|===== +|Field|Description +|`conversation_id`|__String__. Echoes the request parameter. +|`is_shared_content_outdated` a|__Boolean__. + +* `true`, if the shared view was generated before the last edit to the conversation and does not reflect the latest content +* `false` when the shared view is current. +* `null` when the conversation has never been shared. +|`principals`|__Array of strings__. List of principals with access. Empty when no access has been granted. The conversation owner is never included. Each entry in the `principals` array contains the following attributes: + +* `id`. __String__. Unique identifier of the user or group. +* `type`. __String__. `USER` for individual users, `USER_GROUP` for groups. +* `display_name`. __String__. Display name as shown in the ThoughtSpot UI. +* `name`. __String__. Internal name of the user or group. +* `permission`. __String__. Access level. Always `READ_ONLY` for shared conversations. + +|===== + +== Additional resources + +* xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations] +* xref:customize-spotter-sharing.adoc#_spotter_conversation_sharing[Spotter conversation sharing in embedded views] + diff --git a/modules/ROOT/pages/spotter-agent-streaming-apis.adoc b/modules/ROOT/pages/spotter-agent-streaming-apis.adoc new file mode 100644 index 000000000..7c9f6b9b7 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-streaming-apis.adoc @@ -0,0 +1,664 @@ += Spotter agent streaming API +:toc: true +:toclevels: 3 + +:page-title: Spotter agent streaming APIs +:page-pageid: spotter-agent-streaming-apis +:page-description: Use the Spotter agent streaming REST API to receive real-time Server-Sent Events (SSE) responses for conversational queries sent to the Spotter agent. + +ThoughtSpot's Spotter agent streaming API lets you send natural language queries to an existing conversation session and receive the response as a real-time Server-Sent Events (SSE) stream, instead of waiting for the complete response. + +For information about creating a conversation session and sending queries to it, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. + +== Send a query to agent and get streaming responses + +To send queries to an ongoing conversation session with Spotter agent and receive streaming responses, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally in real time, rather than waiting for the entire response to be generated before sending it to the client. + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API can be used as an integrated tool for real-time streaming of conversational interactions between agents and the ThoughtSpot backend. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`conversation_identifier` |__String__. Specify the conversation ID received from the xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. +|`messages`|_Array of strings_. Include at least one natural language query. For example, `Sales data for Jackets`, `Top performing products in the west coast`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "conversation_identifier": "h2I_pTGaRQof", + "messages": [ + "Net sales of Jackets" + ] +}' +---- + +=== API response + +If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. + +Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with the `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). + +The API uses this format so that the clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows, the receiving client or agent listens to the SSE stream, parses each event, and assembles the full response for its users. + +==== Example response +If the request is valid, the API returns SSE streams. Each line has the form `data: [{"type": "...", ...}]`, a JSON array of event objects. + +[source,JSON] +---- +data: [{"type":"ack","node_id":"aGxzcFVrtom8"}] + +data: [{"type":"conv_title","title":"Sales 2025 vs 2024","conv_id":"-XIi04l5rrof"}] + +data: [{"type":"notification","group_id":"cDEsAQbSnd3J","metadata":{"type":"thinking","tool_title":"Analyzing Sales Performance: 2025 vs 2024"},"code":"TOOL_CALL_NOTIFICATION"}] + +data: [{"id":"mNAdvy-NK2l6","type":"text-chunk","group_id":"cDEsAQbSnd3J","metadata":{"format":"markdown","type":"thinking"},"content":"\n\nI need to compare sales performance between 2025 and 2024."}] + +data: [{"type":"notification","group_id":"m1MTvttEUa7o","code":"nls_start"}] + +data: [{"id":"hxWMDP-pgR3B","type":"answer","group_id":"m1MTvttEUa7o","metadata":{"sage_query":"[sales] [date] = '2025' vs [date] = '2024'","session_id":"431adcf9-1328-4d8c-81a1-0faa7fa37ba6","title":"Compare sales for 2025 vs 2024"},"title":"Compare sales for 2025 vs 2024"}] + +data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] +---- +For the complete response in one payload, use the xref:spotter-agent-conversation-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. + +//// +[source,] +---- +data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] + +data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] +---- +//// + +==== SSE event types +The SSE event types streamed in the API response include: + +* `ack` + +Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. +* `conv_title` + +A conversation title (`title`, `conv_id`). +* `notification` + +Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. +* `type` + +Type can be `thinking`, `text`. +* `text` + +Complete text block in markdown format. +* `text-chunk` + +Text fragments in incremental streaming, often in markdown (`id`, `group_id`, `metadata` with `format`) +* `content` + +The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. +* `text` + +Full text block with same structure as text-chunk. +* `answer` + +Structured answer with metadata (`id`, `group_id`, `metadata` with `sage_query`, `session_id`, `title` and more) +* `error` + +In case of failures. +* `*-interrupt` + +If the generation was stopped mid-stream. +* `group_id` + +Groups related chunks together. + +For more information and examples, see xref:spotter-agent-streaming-apis.adoc#_sse_event_payload_reference[SSE event payload reference]. + +=== Thinking versus output events +Spotter responses have two phases: + +* A *thinking phase*, where the AI reasons through the query and calls internal tools, followed by an *output phase* containing the final response delivered to the user. + + +Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All other events are final output. + +Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. + +[listing] +---- +THINKING PHASE +─────────────────────────────────────────────────────────── +ack + +┌─ group_id: g1 ── Tool Call 1 ("Searching data") ─────────┐ +│ notification (thinking, TOOL_CALL_NOTIFICATION) │ +│ text-chunk (thinking) │ +│ answer (thinking) │ +└──────────────────────────────────────────────────────────┘ + +┌─ group_id: g2 ── Tool Call 2 ("Running code") ───────────┐ +│ notification (thinking, TOOL_CALL_NOTIFICATION) │ +│ text-chunk (thinking) │ +│ text-chunk (thinking) │ +└──────────────────────────────────────────────────────────┘ + +notification (FINAL_RESPONSE_NOTIFICATION) ←── boundary +──────────────────────────────────────────────────────────── + +OUTPUT PHASE +──────────────────────────────────────────────────────────── +┌─ group_id: g3 ────────────────────────────────────────────┐ +│ text "Here are the results:" │ +│ answer (final visualization) │ +└───────────────────────────────────────────────────────────┘ +[stream closes] +---- + +==== Notification codes reference + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Code| When it appears +|`QH`|Query handling started +|`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML +|`ANSWER_GEN`|Generating an answer +|`IDENTIFYING_ATTRIBUTES`|Identifying data attributes +|`PERFORMING_CHANGE_ANALYSIS`|Running change analysis +|`PERFORMING_FORECASTING_ANALYSIS`|Running forecasting +|`SUMMARIZING_RESULTS`|Summarizing results +|`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) +|`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output +|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete +|`approval_required`|An external tool requires user permission before proceeding +|===== + +=== SSE event payload reference + +==== ack + +[source,JSON] +---- +data: { + "type": "ack", + "group_id": "a1b2c3", + "id": "evt-001", + "node_id": "resp-node-abc" +} +---- + +==== notification (thinking — tool call) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g1", + "id": "evt-002", + "code": "TOOL_CALL_NOTIFICATION", + "message": "Searching for relevant data", + "metadata": { + "type": "thinking", + "tool_title": "Searching sales data", + "tool_code": "RUNNING_CODE_EXECUTION", + "tool_name": "code_interpreter" + } +} +---- + +==== notification (thinking - external tool with MCP integration) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g2", + "id": "evt-003", + "code": "TOOL_CALL_NOTIFICATION", + "message": "Querying Salesforce", + "metadata": { + "type": "thinking", + "tool_title": "Salesforce: Get Opportunities", + "tool_name": "get_opportunities", + "integration_id": "int-sf-123", + "integration_name": "Salesforce" + } +} +---- + +==== notification (approval required) +Sent when an external MCP tool requires explicit user permission before proceeding. Your application should prompt the user to approve or deny the action before continuing. + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g2", + "id": "evt-005", + "code": "approval_required", + "metadata": { + "request_id": "perm-req-789", + "integration_id": "int-sf-123", + "integration_name": "Salesforce", + "tool_name": "get_opportunities", + "annotated_title": "Access Salesforce Opportunities" + } +} +---- + +==== notification (FINAL_RESPONSE_NOTIFICATION) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g1", + "id": "evt-004", + "code": "FINAL_RESPONSE_NOTIFICATION", + "message": "" +} +---- + +==== text + +[source,JSON] +---- +data: { + "type": "text", + "group_id": "g3", + "id": "evt-007", + "content": "Here is the total revenue breakdown by region for Q4 2025:\n\n- **North America:** $4.2M\n- **EMEA:** $2.8M\n- **APAC:** $1.5M" +} +---- + +==== text-chunk +Multiple chunks sharing the same `id` should be appended together to reconstruct the full text item. + +[source,JSON] +---- +data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "Based on the analysis, " } +data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "revenue grew 12% quarter-over-quarter." } +---- + +==== answer +When an `answer` event is received, the `session_id` and `gen_no` fields are returned. You can export the visualization data using the Export Answer Report API to process the results. This allows users to download the answer as a PDF, PNG, CSV, or XLSX file. + +[source,JSON] +---- +data: { + "type": "answer", + "group_id": "g3", + "id": "evt-010", + "title": "Revenue by Region Q4 2025", + "metadata": { + "session_id": "sess-abc-123", + "gen_no": 1, + "transaction_id": "txn-456", + "worksheet_id": "ws-def-789", + "cached": false, + "is_hidden": false + } +} +---- + +==== search_datasets +Emitted as a start/end pair during Auto mode data source discovery. + + +[source,JSON] +---- +data: { "type": "search_datasets", "group_id": "g0", "id": "evt-012", "code": "search_datasets_start", "metadata": {} } + +data: { + "type": "search_datasets", + "group_id": "g0", + "id": "evt-013", + "code": "search_datasets_end", + "metadata": { + "data_sources": [ + { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Contains revenue columns" }, + { "worksheet_id": "ws-2", "worksheet_name": "Marketing Data", "confidence": "low", "reasoning": "No revenue columns" } + ], + "auto_selected": { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Best match" } + } +} +---- +==== file + +[source,JSON] +---- +data: { + "type": "file", + "group_id": "g3", + "id": "evt-014", + "files": [ + { "ts_file_id": "file-abc-001", "display_name": "quarterly_report.csv", "file_type": "csv", "created_at": "2025-11-15T10:30:00Z" }, + { "ts_file_id": "file-abc-002", "display_name": "chart.png", "file_type": "png", "created_at": "2025-11-15T10:30:01Z" } + ], + "metadata": { "conv_id": "conv-123" } +} +---- +==== conv_title + +[source,JSON] +---- +data: { + "type": "conv_title", + "group_id": "g0", + "id": "evt-015", + "title": "Revenue Analysis Q4 2025", + "conv_id": "conv-123" +} +---- + +==== error + +[source,JSON] +---- +data: { + "type": "error", + "group_id": "g3", + "id": "evt-016", + "code": "RATE_LIMIT_EXCEEDED", + "message": "Too many requests", + "display_message": "You've exceeded the rate limit. Please try again in a few minutes." +} +---- +==== agent-interrupt + +[source,JSON] +---- +Sent when generation is stopped mid-stream. +data: { + "type": "notification", + "group_id": "g3", + "id": "evt-017", + "code": "agent-interrupt", + "message": "Generation stopped" +} +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] +* xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs] diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index a5759e1b9..7e90d5b28 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -25,6 +25,11 @@ For information about supported API operations, see the following pages: * xref:spotter-classic-apis.adoc[APIs for Spotter classic workflow] * xref:spotter-agent-apis.adoc[APIs for Spotter agent workflows] +* xref:spotter-agent-conversation-apis.adoc[APIs for Spotter agent conversations] +* xref:spotter-agent-streaming-apis.adoc[APIs for Spotter agent streaming responses] +* xref:spotter-agent-process-results-apis.adoc[APIs for processing Spotter agent conversation results] +* xref:spotter-agent-data-literacy-apis.adoc[APIs for Spotter agent data literacy] +* xref:spotter-agent-sharing-apis.adoc[APIs for sharing Spotter conversations] * xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for Spotter conversation management] * xref:spotter-nl-instructions.adoc[APIs for Spotter coaching and data model instructions] * xref:spotter-agent-instructions.adoc[APIs for Spotter agent instructions] diff --git a/modules/ROOT/pages/tml-import.adoc b/modules/ROOT/pages/tml-import.adoc index f0640b695..0366c6530 100644 --- a/modules/ROOT/pages/tml-import.adoc +++ b/modules/ROOT/pages/tml-import.adoc @@ -52,7 +52,7 @@ To know the GUID assigned to a new object created from the TML import, check the ==== [#personalized-views-portability] -== Personalized Views portability [earlyAccess eaBackground]#Early Access# +== Personalized Views portability Personalized Views support improved portability across ThoughtSpot environments. When importing a Personalized View TML set the `enable_personalized_view_upsert` to `true` in the API request to `POST /api/rest/2.0/metadata/tml/import`. ThoughtSpot then checks the target environment for an existing Personalized View with a matching `obj_id`. If a match is found, the import updates the existing view rather than creating a duplicate. If no match is found, a new Personalized View is created. diff --git a/modules/ROOT/pages/webhooks-gcs-storage.adoc b/modules/ROOT/pages/webhooks-gcs-storage.adoc index 82482f85a..02da63c95 100644 --- a/modules/ROOT/pages/webhooks-gcs-storage.adoc +++ b/modules/ROOT/pages/webhooks-gcs-storage.adoc @@ -198,7 +198,7 @@ To create a webhook with GCS as the target destination for payload delivery: image::./images/webhook-create-gcp.png[Webhooks for GCS storage] -- //. Select xref:webhooks-ux.adoc#_creating_a_webhook[the authentication method] to authorize payloads to the destination endpoint. + -. To configure xref:webhooks-ux.adoc#_creating_a_webhook_connection[advanced settings] such as signature verification, custom headers, and URL query parameters, click **Advanced settings** and configure the fields as required. +. To configure advanced settings such as signature verification, custom headers, and URL query parameters, click **Advanced settings** and configure the fields as required. . Click *Save*. + If the webhook is created successfully, it is added to the Webhooks list and enabled by default. diff --git a/modules/ROOT/pages/webhooks-ux.adoc b/modules/ROOT/pages/webhooks-ux.adoc index a29518606..306bba6f4 100644 --- a/modules/ROOT/pages/webhooks-ux.adoc +++ b/modules/ROOT/pages/webhooks-ux.adoc @@ -63,7 +63,7 @@ You can create a webhook for the Liveboard schedule event type to send a lightwe For more information, see the following documentation: -* xref:webhooks-lb-schedule.adoc#_through_the_webhooks_page_in_ui[Webhook configuration for Liveboard scheduled events]. +* xref:webhooks-lb-schedule.adoc#_through_the_webhooks_page_in_ui[Webhook configuration for Liveboard scheduled events] * xref:webhooks-s3-storage.adoc[AWS S3 storage configuration for webhooks] * xref:webhooks-gcs-storage.adoc[GCS storage configuration for webhooks] diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index c36d8e9f0..d9fc73c1f 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -22,6 +22,109 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Status:* Current / Supported / Deprecated // *Affects:* Developers, Administrators, End Users // ============================================================ +== September 2026 + +**Release version**: ThoughtSpot Cloud 26.9.0.cl + +*Upgrade notes*: No breaking changes in this release. + +*Recommended SDK versions*: Visual Embed SDK v1.52.0 or later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.9.0.cl* + +a| + +[discrete] +==== Full application embed + +Default page settings:: +You can now embed Collections list page and set it as the default landing page using `Page.Collections` enumeration value. For more information, see xref:set-default-page.adoc#_set_the_default_page_using_pageid[Customizing default page]. + +Navigation panel customization:: +Embed developers can include *Collections* as a navigation option in the left navigation panel in full application embeds. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. + +--- + +[discrete] +==== Spotter embed + +Spotter visual experience enhancements:: +The Spotter interface is redesigned and enhanced to provide a more streamlined and conversational experience to embedding application users. The classic Spotter interface remains the default for existing deployments, and you can choose to enable the new experience using the `updatedSpotterExperience` parameter in the SDK. For more information, see xref:customize-spotter-embed.adoc#_spotter_interface_in_the_embedded_view[Spotter experience]. + +Spotter conversation sharing in embedded views:: +Users can now share saved Spotter conversations with other users and groups directly from the embedded Spotter interface or via REST APIs. For more information, see xref:customize-spotter-sharing.adoc[Customize Spotter conversation sharing] and xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. + +--- + + +[discrete] +==== Browser history management in embedded application +When ThoughtSpot is embedded in a host application, internal navigation pushes new entries onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, set `overrideHistoryState` in the Visual Embed SDK. + +--- + + +[discrete] +==== Lazy loading enabled by default for full-height embeds +To improve the initial load performance of large Liveboards, lazy loading is now enabled by default when `fullHeight` is set to `true`. For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of Liveboard visualizations]. + +--- + +[discrete] +==== Custom app scheme allowlisting for mobile embeds +ThoughtSpot now supports adding custom app schemes such as `capacitor://localhost` and `ionic://localhost` to the CSP and CORS allowlist. This allows mobile applications built with hybrid frameworks such as Capacitor and Ionic to embed ThoughtSpot content. For more information, see xref:security-settings.adoc#custom-app-schemes[Security settings]. + +--- + +[discrete] +==== Upcoming changes to `EmbedEvent.Error` framework +In the upcoming ThoughtSpot Cloud 26.10.0.cl and Visual Embed SDK 1.53.0 versions, `EmbedEvent.Error` will include a `severity` field that categorizes errors into three levels, `SEV1`, `SEV2`, and `SEV3`. ThoughtSpot recommends reviewing your error handling logic to prepare for this change. For more information, see xref:embed-event-error-best-practices.adoc[Handling embed errors]. + +--- + + +[discrete] +==== Personalized Views TML portability + +The Personalized Views TML portability feature is now GA and enabled on all ThoughtSpot Embedded instances. For more information, see xref:tml-import.adoc#personalized-views-portability[Personalized Views portability]. + +--- + + +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.52.0, see xref:api-changelog.adoc[Visual Embed SDK changelog]. + +--- + + +[discrete] +==== REST API v2 +This release introduces new API endpoints for sharing Spotter conversations, managing Snowflake Semantic integrations, and other enhancements. +For more information, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +//// +[discrete] +==== Answer Export API + +The following enhancements in the `POST /api/rest/2.0/report/answer` endpoint are now GA. + +* *Pinned Answer export* from a Liveboard, using the new `type` parameter. +* *Personalized View* support to export data from a specific Personalized View of a Liveboard. +* *Spotter Answer export* in `XLSX` and `PDF`, in addition to `CSV` and `PNG`. +* *Custom PNG output*, using `x_resolution`, `y_resolution`, and `scaling`. + +For more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer Report API]. + +--- +//// + +|=== + == August 2026 **Release version**: ThoughtSpot Cloud 26.8.0.cl + @@ -39,10 +142,10 @@ a| ==== Spotter embedding Spotter Analysts [earlyAccess eaBackground]#Early Access#:: -Spotter now includes an *Analysts* panel in the sidebar that surfaces dedicated Spotter Analyst agents. Each Analyst is scoped to a specific data model and skill set, enabling your embedded users to start focused AI-driven conversations without manually selecting a data source. For more information, see xref:customize-spotter-embed.adoc#_spotter_analysts[Customize Spotter embed]. +Spotter now includes an *Analysts* panel in the sidebar that surfaces dedicated Spotter Analyst agents. Each Analyst is scoped to a specific data model and skill set, enabling your embedded users to start focused AI-driven conversations without manually selecting a data source. For more information, see xref:customize-spotter-analysts.adoc#_spotter_analysts[Customize Spotter Analysts]. Spotter onboarding starter prompts:: -Embedded Spotter interface supports onboarding starter prompts to guide first-time users. When enabled, Spotter presents suggested questions based on the connected data model. For more information, see xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Enable starter prompts in Spotter]. +Embedded Spotter interface supports onboarding starter prompts to guide first-time users. When enabled, Spotter presents suggested questions based on the connected data model. For more information, see xref:customize-spotter-chat-experience.adoc#_spotter_starter_prompts[Enable starter prompts in Spotter]. --- @@ -65,7 +168,7 @@ Enables interactive filter chips that allow users to add, update, or remove filt [discrete] ==== Navigation and homepage V1/V2 deprecated [.version-badge.deprecated]#Deprecated# -Starting from ThoughtSpot Cloud 26.8.0.cl, the classic V1 and V2 navigation and homepage experience modes are deprecated. All ThoughtSpot Embedded sessions now render in the V3 navigation experience by default. For more information, see xref:full-app-customize.adoc#nav-v1-v2-deprecation[V1 and V2 deprecation]. +Starting from ThoughtSpot Cloud 26.8.0.cl, the classic V1 and V2 navigation and homepage experience modes are deprecated. All ThoughtSpot Embedded sessions now render in the V3 navigation experience by default. For more information, see xref:deprecated-features.adoc#v1-v2-exp-fullApp-embed[V1 and V2 deprecation]. --- @@ -73,7 +176,7 @@ Starting from ThoughtSpot Cloud 26.8.0.cl, the classic V1 and V2 navigation and ==== Wide logo dimension [.version-badge.breaking]#Breaking change# Starting from ThoughtSpot Cloud 26.8.0.cl, the recommended dimensions for the wide logo displayed on the ThoughtSpot login page have changed from 330x100px to *250x50px (5:1 aspect ratio)*. Logos uploaded at the previous dimensions may appear distorted or incorrectly scaled on the login screen. If you previously uploaded a wide logo at 330x100px, re-upload it at 250x50px to ensure correct display. -For more information, see xref:customize-style.adoc#wide-logo[Customize the login page logo]. +For more information, see xref:customize-style.adoc#logo-change[Customize the login page logo]. --- @@ -103,7 +206,7 @@ For more information, see xref:tml-import.adoc#personalized-views-portability[Pe [discrete] ==== Discoverability checkbox deprecation [.version-badge.breaking]#Breaking change# -The *Make this Liveboard Discoverable* checkbox has been removed from the ThoughtSpot UI. Embedding applications that relied on discoverability for content visibility should review their sharing logic and update user-facing guidance for content access. For more information, see xref:deprecated-features.adoc#liveboardAnswerDiscoverable[Deprecation announcements]. +The *Make this Liveboard Discoverable* checkbox has been removed from the ThoughtSpot UI. Embedding applications that relied on discoverability for content visibility should review their sharing logic and update user-facing guidance for content access. For more information, see xref:deprecated-features.adoc#liveboardDiscoverable[Deprecation announcements]. --- @@ -263,7 +366,7 @@ This release introduces the following enhancements for Spotter AI workflows and Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. * Spotter AI APIs: + //** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. - New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. + New API endpoint xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. --- diff --git a/modules/tutorials/pages/spotter/spotter-in-custom-chatbot.adoc b/modules/tutorials/pages/spotter/spotter-in-custom-chatbot.adoc index 6156b7802..ba735c836 100644 --- a/modules/tutorials/pages/spotter/spotter-in-custom-chatbot.adoc +++ b/modules/tutorials/pages/spotter/spotter-in-custom-chatbot.adoc @@ -86,9 +86,7 @@ div.append(container); app.insertAdjacentElement("beforeend", div); ---- -== That's all! - -And that’s a wrap! This was a super quick tutorial on how to use Spotter embed APIs to integrate conversational analytics with your chatbot! +== Next steps Visit the link:https://codesandbox.io/p/sandbox/bodyless-sample-doc-5q3dwr[CodeSandbox^] to see it in action in a sample chatbot we created. Here is the complete code used in this tutorial: diff --git a/static/doc-images/images/spotter-default-interface.png b/static/doc-images/images/spotter-default-interface.png new file mode 100644 index 000000000..259d21bc1 Binary files /dev/null and b/static/doc-images/images/spotter-default-interface.png differ diff --git a/static/doc-images/images/spotter-new-experience.png b/static/doc-images/images/spotter-new-experience.png new file mode 100644 index 000000000..e389de9cb Binary files /dev/null and b/static/doc-images/images/spotter-new-experience.png differ diff --git a/static/doc-images/images/spotter3-interface.png b/static/doc-images/images/spotter3-interface.png new file mode 100644 index 000000000..982395d17 Binary files /dev/null and b/static/doc-images/images/spotter3-interface.png differ