The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
docs - embedded ai chat updates (#80940)
Jeff Bruemmera1c217c51bc7
diff --git a/docs/ai/overview.md b/docs/ai/overview.mdindex a533caaed05..cbe3a690b91 100644--- a/docs/ai/overview.md+++ b/docs/ai/overview.md@@ -19,7 +19,7 @@ Here are the different ways to use AI with Metabase:**Best for: daily tasks in Metabase; granular control over people's AI usage.**-Metabot is Metabase's built-in AI agent. Metabot can help you with most daily tasks around Metabase, like answering questions about your data, creating queries, generating SQL code, explaining charts, or creating Documents. If you're embedding Metabase into your product, you can get the Metabot agent through the [AI chat component](../embedding/components.md#ai-chat). See [non-exhaustive list of things Metabot can do](metabot.md#what-metabot-can-do), as well as its [limitations](metabot.md#current-limitations).+Metabot is Metabase's built-in AI agent. Metabot can help you with most daily tasks around Metabase, like answering questions about your data, creating queries, generating SQL code, explaining charts, or creating Documents. If you're embedding Metabase into your product, you can get the Metabot agent through the [AI chat component](../embedding/ai-chat.md). See a [non-exhaustive list of things Metabot can do](metabot.md#what-metabot-can-do), as well as its [limitations](metabot.md#current-limitations).**Controls:** Metabot will only see what the person using it can see. Metabot also comes with additional permission controls and usage limits so that you control who can use which Metabot tools (e.g. chat vs SQL generation) and how many tokens they can spend.@@ -30,7 +30,7 @@ Metabot is Metabase's built-in AI agent. Metabot can help you with most daily ta**Plans**: available on all plans. You can only use Metabase's AI Service on Metabase Cloud.-See [full docs for Metabot](metabot.md) and [embedded AI chat](../embedding/components.md#ai-chat).+See [full docs for Metabot](metabot.md) and [embedded AI chat](../embedding/ai-chat.md).## MCP serverdiff --git a/docs/ai/settings.md b/docs/ai/settings.mdindex 3ab29e7d246..ff531a9abee 100644--- a/docs/ai/settings.md+++ b/docs/ai/settings.md@@ -100,10 +100,10 @@ Toggling off Metabot only turns off in-app Metabot features. People can still us_Embedded tab._-The **Embedded Metabot is enabled** toggle turns embedded Metabot on or off. The toggle affects both full-app embeds and modular embeds.+The **Enable Embedded Metabot** toggle turns embedded Metabot on or off. The toggle affects both full-app embeds and modular embeds.- [Full-app embedding](../embedding/full-app-embedding.md): The Metabot icon and keyboard shortcuts are only available when Metabot is enabled. Turning off Embedded Metabot will hide these icons and disable the keyboard shortcuts.-- [Modular embedding](../embedding/modular-embedding.md): The toggle doesn't add Metabot anywhere; you have to explicitly include a chat component (like the SDK's [`MetabotQuestion`](../embedding/sdk/ai-chat.md)) in your application. If, however, you've added a component, and you turn off the Embedded Metabot toggle, your chat component will stop working, so you should also remove or hide the component in your application.+- [Modular embedding](../embedding/modular-embedding.md): The toggle doesn't add Metabot anywhere; you have to explicitly include a chat component (like the SDK's [`MetabotQuestion`](../embedding/ai-chat.md)) in your application. If, however, you've added a component, and you turn off the Embedded Metabot toggle, your chat component will stop working, so you should also remove or hide the component in your application.### Verified content@@ -127,7 +127,11 @@ People can still @-mention items outside of this collection when prompting in AI_Embedded tab._-If you're embedding the Metabot component in an app, you can specify a different collection that embedded Metabot is allowed to use for creating queries. Click **Pick a different collection** to choose the collection (and its subcollections) that embedded Metabot can query.+If you're embedding the Metabot component in an app, you can point embedded Metabot at a different collection to use for creating queries. Click **Pick a different collection** to choose the collection (and its subcollections) that embedded Metabot searches for metrics, models, and saved questions.++Picking **Our analytics** is the same as picking no collection at all, so pick something narrower if you want the scoping to do anything. And once you set a collection, tables drop out of embedded Metabot's search results, so pick a collection with the metrics and models you want people building on.++This setting narrows where embedded Metabot searches; it's _not_ a substitute for setting permissions. Embedded Metabot can still read and query anything the person using it has permissions for. Embedded Metabot can also see the items that person viewed recently, whichever collection those live in. Restricting Metabot to [verified content](#verified-content) narrows those recent items to verified, official, and [Library](../data-studio/library.md) content, but it doesn't confine them to the collection you picked. To control what data people can get to in an embed, set [data permissions](../permissions/embedding.md). See also [Set up AI chat in Metabase](../embedding/ai-chat.md#set-up-ai-chat-in-metabase).### Prompt suggestionsdiff --git a/docs/dashboards/subscriptions.md b/docs/dashboards/subscriptions.mdindex 072871dad49..1fc3ab0621f 100644--- a/docs/dashboards/subscriptions.md+++ b/docs/dashboards/subscriptions.md@@ -155,7 +155,7 @@ See [Remove Metabase branding from exports](../questions/exporting-results.md#re## Subscriptions in embedded dashboards exclude links-Since people viewing embedded dashboards likely don't have direct access to your Metabase, Metabase will omit the links to Metabase items in subscriptions sent from embedded dashboards. That way people don't get broken links in their email. See [embedded dashboards](../embedding/components.md).+Since people viewing embedded dashboards likely don't have direct access to your Metabase, Metabase will omit the links to Metabase items in subscriptions sent from embedded dashboards. That way people don't get broken links in their email. See [Embed a dashboard](../embedding/dashboard.md).## Custom visualizations fall back to the default chartdiff --git a/docs/embedding/ai-chat.md b/docs/embedding/ai-chat.mdnew file mode 100644index 00000000000..3e9793ffdb4--- /dev/null+++ b/docs/embedding/ai-chat.md@@ -0,0 +1,204 @@+---+title: Embed an AI chat+summary: "Embed an AI chat in your app with a web component or the React SDK, so people can ask questions of their data in natural language."+redirect_from:+ - /docs/latest/embedding/sdk/ai-chat+---++# Embed an AI chat++++{% include plans-blockquote.html feature="AI chat component" convert_pro_link_to_embedding=true%}++You can embed an AI chat in your app, so people can ask questions of their data in natural language. Embedded chat is a focused version of [Metabot](../ai/metabot.md): it builds a question in the query builder and charts the answer.++To build that question, embedded chat first searches your Metabase for the best thing to build on: a [metric](../data-modeling/metrics.md), a [model](../data-modeling/models.md), a saved question, or a table (tables drop out once you [scope the chat to a collection](#set-up-ai-chat-in-metabase)). Then it writes a query against whatever it picked. So embedded chat does look through your saved content, but as raw material for a new question, not as results to hand back. What people get back is always a new question they can drill into, and save if you [turn saving on](#let-people-save-questions-metabot-creates).++Embedded chat won't write SQL, build or edit dashboards, or create metrics and models — it builds on the ones you already have. It also won't work as a search box for finding existing content. For those, chat will suggest doing the work in Metabase itself.++AI chat requires the embed to use SSO authentication that signs people into your Metabase.++## Try the AI chat demo++For what AI chat looks like in action, check out the [AI chat component](https://embedded-analytics-sdk-demo.metabase.com/admin/analytics/new/ask-metabot) running on Shoppy, our modular embedding demo app. The demo's chat uses the [dedicated chart component](#ai-chat-with-dedicated-chart-panel).++## Set up AI chat in Metabase++An admin sets up embedded Metabot in your Metabase:++1. Click the **grid** icon in the upper right.+2. Select **Admin**.+3. Click the **AI** tab.+4. In the left sidebar, click **AI Settings**.+5. The first card on the page is your AI provider connection. If the card says **Connect to an AI provider**, [set one up](../ai/settings.md#enable-ai-features). If you're self-hosting, that means [bringing your own API key](../ai/settings.md#bring-your-own-api-key). If the card says **AI providers**, you're already connected.+6. In the **Metabot settings** card, click the **Embedded** tab.+7. Turn on **Enable Embedded Metabot**.+8. Under **Collection Embedded Metabot can use**, click **Pick a different collection** and choose the collection that holds the metrics, models, and saved questions embedded Metabot should build on.++The collection you pick narrows what embedded chat finds when it searches for something to build on: that collection and everything under it. It doesn't limit what embedded chat can query, since people can still get to any data they have [permissions](../permissions/embedding.md) for. And once you set a collection, tables drop out of the chat's search results, so pick a collection with the metrics and models you want people building on.++The **Embedded** tab configures Metabot in an embedded context, which is separate from the [Metabot](../ai/settings.md) in your own Metabase (which lives on the **Internal** tab). Both tabs control what each Metabot can see, not what it runs on: the AI provider, API key, and model are set once for the whole instance, above the **Metabot settings** card, and both Metabots use them.++With embedded Metabot set up, there are two ways to add the chat to your app:++- **[Web component](#web-component-ai-chat)**: the whole chat interface, chart and all, from a single tag.+- **[React SDK](#react-sdk-ai-chat)**: the same interface from the `MetabotQuestion` component, or the [`useMetabot`](#build-a-custom-ai-chat-ui-with-usemetabot-react-sdk-only) hook if you'd rather build the interface yourself.++Both the web component and `MetabotQuestion` let you [set where the chart appears](#set-where-the-chart-appears) and [whether people can save questions](#let-people-save-questions-metabot-creates).++## Web component AI chat++You can use the in-app wizard to generate the code:++1. Open the command palette with Ctrl/Cmd+K and type **New embed**.+2. For the experience, select **Metabot**.+3. Pick a [layout](#set-where-the-chart-appears) and decide whether people can [save questions](#let-people-save-questions-metabot-creates).+4. Click **Get code** and paste the snippet into your app.++The **Metabot** option only shows up once an admin has turned on embedded Metabot, and only for SSO authentication. For what the rest of the generated snippet does, see [modular embedding](./modular-embedding.md).++To render the AI chat interface:++```html+<metabase-metabot></metabase-metabot>+```++### Web component `metabase-metabot` attributes++{% include_file "{{ dirname }}/eajs/snippets/MetabaseMetabotAttributes.md" snippet="properties" %}++Depending on the framework you're using, you may need to stringify attributes before passing them to the component. And if you surround an attribute's value with double quotes, use single quotes inside it.++For all modular embeds, you can also set a `locale` in your page-level configuration to [translate embedded content](./translations.md). But [Metabot's own text isn't translated](./translations.md#the-ai-chat-component-isnt-translated).++## React SDK AI chat++{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %}++To embed an AI chat with the [SDK](./sdk/introduction.md), use the `MetabotQuestion` component. Wrap the component in the `MetabaseProvider` component with your auth config.++```typescript+{% include_file "{{ dirname }}/sdk/snippets/questions/ai-question.tsx" %}+```++### React SDK `MetabotQuestion` props++- [Component](./sdk/api/MetabotQuestion.html)+- [Props](./sdk/api/MetabotQuestionProps.html)++{% include_file "{{ dirname }}/sdk/api/snippets/MetabotQuestionProps.md" snippet="properties" %}++## Set where the chart appears++- [Web component](#web-component-chart-layout)+- [React SDK](#react-sdk-chart-layout)++The `layout` setting positions the chart relative to the chat interface:++- `auto` (default): Metabot uses the `stacked` layout on mobile screens, and a `sidebar` layout on larger screens.+- `stacked`: the chart stacks on top of the chat interface.+- `sidebar`: the chart appears to the left of the chat interface, which sits in a sidebar on the right.++`layout` only applies to the built-in chat component. If you're building your own interface with [`useMetabot`](#build-a-custom-ai-chat-ui-with-usemetabot-react-sdk-only), you position the chart yourself.++### Web component chart layout++Set the `layout` attribute:++```html+<metabase-metabot layout="stacked"></metabase-metabot>+```++### React SDK chart layout++Set the `layout` prop on `MetabotQuestion`:++```tsx+<MetabotQuestion layout="stacked" />+```++## Let people save questions Metabot creates++- [Web component](#web-component-question-saving)+- [React SDK](#react-sdk-question-saving)++Turning on the chat's save button lets people keep a question Metabot built. Saving is off by default.++Setting a target collection is optional, but it's worth doing: it picks the collection that new questions land in, so people's work doesn't scatter across your Metabase. It also hides the collection picker in the save modal, so nobody has to decide where their question goes.++### Web component question saving++Turn saving on with `is-save-enabled="true"`, and set the collection with `target-collection`:++```html+<metabase-metabot+ is-save-enabled="true"+ target-collection="123"+></metabase-metabot>+```++### React SDK question saving++The equivalent props on `MetabotQuestion` are `isSaveEnabled` and `targetCollection`:++```tsx+<MetabotQuestion isSaveEnabled targetCollection={123} />+```++## Build a custom AI chat UI with `useMetabot` (React SDK only)++If `MetabotQuestion`'s built-in layouts don't fit your app, use the `useMetabot` hook to read Metabot's conversation state directly and render your own UI. The hook gives you the messages, the chart the agent most recently produced, processing and error state, and actions to submit, cancel, retry, or reset the conversation.++### AI chat with inline charts++++When an agent responds, the message can contain a `Chart` component. You can walk the agent's messages and render charts inline alongside the chat transcript:++```typescript+{% include_file "{{ dirname }}/sdk/snippets/questions/use-metabot-inline-charts.tsx" %}+```++### AI chat with dedicated chart panel++++The `CurrentChart` component is bound to the latest chart the agent produced. Render `CurrentChart` once, and it will swap in new charts as the agent creates them. You'll want to filter chart messages out of the transcript so they don't render twice:++```typescript+{% include_file "{{ dirname }}/sdk/snippets/questions/use-metabot-dedicated-chart.tsx" %}+```++### React SDK `useMetabot` return values++- [Hook](./sdk/api/useMetabot.html)+- [Return values](./sdk/api/UseMetabotResult.html)++{% include_file "{{ dirname }}/sdk/api/snippets/UseMetabotResult.md" snippet="properties" %}++### Guard against null while the SDK bundle loads++`useMetabot` returns `null` until the SDK bundle has loaded and `<MetabaseProvider>` has mounted, so always guard before you use it. The SDK ships its Metabot internals in a code-split chunk that isn't available synchronously, which means an unguarded first render throws `Cannot read properties of null` as soon as you reach for `metabot.messages`, `metabot.submitMessage`, or anything else on the hook.++### Bring your own markdown renderer++`MetabotQuestion` renders agent text messages for you, markdown formatting and all, along with transcript scrolling and input styling. The `useMetabot` hook hands you the raw conversation state instead, so you can handle the markdown rendering.++Agent text messages (the ones where `message.type === 'text'`) contain markdown (like links, bold, lists, inline code). The snippets above render `message.message` as plain text to keep them short, but in production you'll want to pass that text through a markdown renderer, like `react-markdown` or `markdown-to-jsx`, so links and formatting come out right.++### Strip links back to Metabase++Agent text can include links pointing back to the Metabase it's running against, like a link to a chart the agent just created. Opening one requires an authenticated Metabase session, so people viewing your app will hit a login screen. Strip those links out when you render the message, or swap them for a route in your own app.++## Further reading++- [Modular embedding components](./components.md)+- [Metabot](../ai/metabot.md)+- [Metabot settings](../ai/settings.md)+- [Embed a chart](./chart.md)+- [Embed a dashboard](./dashboard.md)+- [Appearance](./appearance.md)+- [Authentication](./authentication.md)+- [Modular embedding](./modular-embedding.md)+- [Modular embedding SDK](./sdk/introduction.md)diff --git a/docs/embedding/browser.md b/docs/embedding/browser.mdindex 904cb888ea0..de3257ab366 100644--- a/docs/embedding/browser.md+++ b/docs/embedding/browser.md@@ -142,3 +142,4 @@ One quirk: when someone clicks on a collection, `CollectionBrowser` navigates in- [Collection permissions](../permissions/collections.md)- [Authentication](./authentication.md)- [Modular embedding SDK](./sdk/introduction.md)+- [Modular embedding components](./components.md)diff --git a/docs/embedding/chart.md b/docs/embedding/chart.mdindex b04096d6a14..1ffa6c853d5 100644--- a/docs/embedding/chart.md+++ b/docs/embedding/chart.md@@ -277,9 +277,9 @@ For both the SDK props (`initialSqlParameters`, `sqlParameters`, and `onSqlParamTo hide a parameter from the question's UI, use the [`hidden-parameters`](./question-reference.md#web-component-metabase-question-attributes) attribute (web component) or the `hiddenParameters` prop (SDK). Both work in any modular embed, on any plan.-In practice you'll reach for them on [SSO embeds](./introduction.md#components-with-sso-authentication), where every parameter on the question shows up by default. On a [guest embed](./guest-embedding.md), a parameter that you haven't set to **Editable** or **Locked** is already hidden.+In practice you'll reach for them on an [SSO embed](./introduction.md#components-with-sso-authentication), where every parameter on the question shows up by default. On a [guest embed](./guest-embedding.md#configuring-parameters), a parameter that you haven't set to **Editable** or **Locked** is already hidden, so the embed wizard won't generate `hidden-parameters` for you. You can still add the attribute by hand to hide a parameter you've made editable.-Hiding a parameter declutters the UI; it doesn't restrict what people can query. Setting a value with `initial-sql-parameters` and then hiding the widget isn't a secure way to filter data, because your app sets that value in the browser. To restrict the data itself, see [Show people only their own data](#show-people-only-their-own-data).+Hiding a parameter declutters the UI; it doesn't restrict what people can query. Setting a value with `initial-sql-parameters` and then hiding the widget isn't a secure way to filter data, because your app sets that value in the browser. Instead, see [Show people only their own data](#show-people-only-their-own-data), or set [data permissions](../permissions/embedding.md).## Let people set up alerts on a question@@ -346,4 +346,5 @@ On the OSS and Starter plans, Metabase adds a "Powered by Metabase" banner to gu- [Guest embeds](./guest-embedding.md)- [Authentication](./authentication.md)- [Modular embedding SDK](./sdk/introduction.md)-- [AI chat](./sdk/ai-chat.md)+- [Modular embedding components](./components.md)+- [Embed an AI chat](./ai-chat.md)diff --git a/docs/embedding/components.md b/docs/embedding/components.mdindex 2d7d0c72d1b..ddf651227ee 100644--- a/docs/embedding/components.md+++ b/docs/embedding/components.md@@ -1,33 +1,35 @@---title: Modular embedding components-summary: Embed dashboards, questions, query builder, AI chat, and a collection browser.+summary: "A map of the modular embedding docs: dashboards, charts, the query builder, a collection browser, and AI chat."---# Modular embedding components-There are different components you can embed, each with various options.+Modular embedding gives you a handful of components you can drop into your app, with either web components or the React SDK. This page maps out the docs for each one.-> While you can use component parameters to show or hide parts of the embedded component, these parameters are _not_ a substitute for [permissions](../permissions/start.md). Even if you hide stuff, people could still grab their token from the frontend and use it to query the Metabase API.--This page covers what you can embed. For theming your embeds, see [Appearance](./appearance.md).--> Depending on the framework you're using, you may need to stringify attributes before passing them to the embedded components.+> While you can use attributes and props to show or hide parts of an embedded component, they're _not_ a substitute for [permissions](../permissions/start.md). Even if you hide stuff, people could still grab their token from the frontend and use it to query the Metabase API.## Dashboard+Embed a dashboard view-only, interactive, or editable, and let people create dashboards from your app.+- [Embed a dashboard](./dashboard.md)- [Dashboard component reference](./dashboard-reference.md), for `<metabase-dashboard>` attributes and SDK props## Question+Embed a single chart, or the query builder and SQL editor so people can build questions from scratch.+- [Embed a chart](./chart.md)-- [Embed a query editor](./query-builder.md)+- [Embed the query builder](./query-builder.md)- [Question component reference](./question-reference.md), for `<metabase-question>` attributes and SDK props## Browser{% include plans-blockquote.html feature="Browser component" convert_pro_link_to_embedding=true%}+Embed a browsable collection, so people can find and open dashboards and questions themselves.+- [Embed a collection browser](./browser.md)- [Browser component reference](./browser-reference.md), for `<metabase-browser>` attributes and SDK props@@ -35,34 +37,25 @@ This page covers what you can embed. For theming your embeds, see [Appearance](.{% include plans-blockquote.html feature="AI chat component" convert_pro_link_to_embedding=true%}-AI chat component is only available for authenticated modular embeds. It's unavailable for [Guest embeds](./guest-embedding.md).--To render the AI chat interface:--```html-<metabase-metabot></metabase-metabot>-```--If you're using the SDK, you can use either the [`MetabotQuestion`](./sdk/ai-chat.md#example) component or the [`useMetabot`](./sdk/ai-chat.md#building-custom-ai-chat-uis-with-usemetabot) hook for a custom UI.--### Attributes--{% include_file "{{ dirname }}/eajs/snippets/MetabaseMetabotAttributes.md" snippet="properties" %}--## Customizing loader and error components+Embed an AI chat, so people can ask questions of their data in natural language.-{% include plans-blockquote.html feature="Customizing loader and error components" convert_pro_link_to_embedding=true%}+- [Embed an AI chat](./ai-chat.md), for the `<metabase-metabot>` attributes, the `MetabotQuestion` props, and the `useMetabot` hook-If you're using the [modular embedding SDK](./sdk/introduction.md), you can provide your own components for loading and error states by specifying `loaderComponent` and `errorComponent` as props to `MetabaseProvider`.+## Things you can only do with the React SDK-```tsx-{% include_file "{{ dirname }}/sdk/snippets/appearance/customizing-loader-and-components.tsx" snippet="imports" %}+Web components cover the components above. A few features are React-only, because they take React components or hooks that an HTML attribute can't carry. For those, use the [Modular embedding SDK](./sdk/introduction.md).-{% include_file "{{ dirname }}/sdk/snippets/appearance/customizing-loader-and-components.tsx" snippet="example" %}-```+- [Plugins](./sdk/plugins.md), to customize component menus and click actions+- [Actions](./sdk/actions.md), to run Metabase actions from your app with the `useAction` hook+- [Custom question layouts](./question-reference.md#customize-the-layout-of-an-interactive-chart), to lay out a question yourself with namespaced `InteractiveQuestion` components+- [Customize loading, error, and empty states](./sdk/loading-and-errors.md), to swap in your own loading and error components, and your own no-results image## Further reading- [Appearance](./appearance.md)+- [Modular embedding SDK config](./sdk/config.md), for the `MetabaseProvider` props+- [Modular embedding parameters](./parameters.md)- [Custom visualizations in embeds](./custom-visualizations.md)-- [Modular embedding SDK](./sdk/introduction.md).+- [Translating embeds](./translations.md)+- [Authentication](./authentication.md)+- [Modular embedding SDK](./sdk/introduction.md)diff --git a/docs/embedding/dashboard.md b/docs/embedding/dashboard.mdindex ec45d5f9559..2b0f5fc7b46 100644--- a/docs/embedding/dashboard.md+++ b/docs/embedding/dashboard.md@@ -553,4 +553,5 @@ On the OSS and Starter plans, Metabase adds a "Powered by Metabase" banner to gu- [Guest embeds](./guest-embedding.md)- [Authentication](./authentication.md)- [Modular embedding SDK](./sdk/introduction.md)-- [AI chat](./sdk/ai-chat.md)+- [Modular embedding components](./components.md)+- [Embed an AI chat](./ai-chat.md)diff --git a/docs/embedding/guest-embedding.md b/docs/embedding/guest-embedding.mdindex 07d5cef9f68..577f3c5174e 100644--- a/docs/embedding/guest-embedding.md+++ b/docs/embedding/guest-embedding.md@@ -33,7 +33,7 @@ To create a guest embed:3. Select **Embed**.4. Under **Authentication**, select **Guest**.5. Optional: [customize the appearance of the embed](./appearance.md)-6. Optional: [Add parameters to the embed](./components.md).+6. Optional: [set the visibility of each parameter](#configuring-parameters).7. Click **Publish**.8. Get the code snippet that the wizard generates and add it to your app.@@ -41,7 +41,7 @@ To create a guest embed:## Notes on the code the wizard generates-You can edit the code (see [components](./components.md) and [appearance](./appearance.md)). But here's an overview of the code the wizard generates, and where to put it.+You can edit the code (see the [question component reference](./question-reference.md), the [dashboard component reference](./dashboard-reference.md), and [appearance](./appearance.md)). But here's an overview of the code the wizard generates, and where to put it.### Client-side code@@ -113,7 +113,7 @@ You can set different attributes to enable/disable UI. Here are some example att\* Disabling downloads is only available on [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans.-Attributes will differ based on the type of thing you're embedding. Guest embeds have fewer options than embeds that use SSO. See more on [components and their attributes](./components.md).+Attributes will differ based on the type of thing you're embedding. Guest embeds have fewer options than embeds that use SSO. For every attribute, see the [dashboard component reference](./dashboard-reference.md) and the [question component reference](./question-reference.md).### Customizing appearance of guest embeds@@ -540,7 +540,7 @@ Guest embeds can't take advantage of:- [Drill-through](../questions/visualizations/drill-through.md)- [Usage analytics](../usage-and-performance-tools/usage-analytics.md)- [Query builder](../questions/query-builder/editor.md)-- [AI chat](./sdk/ai-chat.md)+- [AI chat](./ai-chat.md)- [Custom visualizations](./custom-visualizations.md)For those features, check out [Modular embedding with SSO](./modular-embedding.md).diff --git a/docs/embedding/images/custom-error.png b/docs/embedding/images/custom-error.pngnew file mode 100644index 00000000000..4a916b6f0c5Binary files /dev/null and b/docs/embedding/images/custom-error.png differdiff --git a/docs/embedding/introduction.md b/docs/embedding/introduction.mdindex 9aa9faa8da8..9fc733932ba 100644--- a/docs/embedding/introduction.md+++ b/docs/embedding/introduction.md@@ -48,7 +48,7 @@ All SSO options require a Pro or Enterprise plan.| [Drill-through menus](../questions/visualizations/drill-through.md) | ✅ | ❌ || [Query builder](../questions/query-builder/editor.md) | ✅ | ❌ || [SQL editor](../questions/native-editor/writing-sql.md) | ✅ | ❌ |-| [AI chat](./sdk/ai-chat.md) | ✅ | ❌ |+| [AI chat](./ai-chat.md) | ✅ | ❌ || [Collection browser](./browser.md) | ✅ | ❌ || Advanced [Tenant](./tenants.md) and [permissions](../permissions/embedding.md) management | ✅ | ❌ || [Advanced theming](./appearance.md) | ✅ | ❌ |diff --git a/docs/embedding/modular-embedding.md b/docs/embedding/modular-embedding.mdindex 4677f34cc44..83aba0ab060 100644--- a/docs/embedding/modular-embedding.md+++ b/docs/embedding/modular-embedding.md@@ -106,7 +106,7 @@ The code snippet has three parts:- Loading the modular embedding library from your Metabase instance.- Setting global configuration settings, like the URL of your Metabase and the `theme`. See [Page-level config](#page-level-config).-- The component(s) to embed, with their parameters. See [Components](./components.md).+- The component(s) to embed, with their attributes. To pick a component, see [Modular embedding components](./components.md). For the attributes each one takes, see the [dashboard](./dashboard-reference.md), [question](./question-reference.md), and [browser](./browser-reference.md) component references.Here's an example snippet:@@ -162,7 +162,7 @@ In addition to this, we consider shared accounts to be unfair usage. Fair usageThe exact customization options you see will depend on which type of entity you're embedding. These are the settings for authenticated embeds available on [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans. For guest embeds (OSS and paid), see [guest embedding options](./guest-embedding.md#component-attributes).-When you're creating a new embed using **Admin > Embedding > Setup guide > Embed in your code**, you'll see some or all of the following customization options in the interactive creation flow. These options correspond to parameters in [components](./components.md).+When you're creating a new embed using **Admin > Embedding > Setup guide > Embed in your code**, you'll see some or all of the following customization options in the interactive creation flow. These options correspond to attributes on the component you're embedding. For each attribute, see the [dashboard](./dashboard-reference.md) and [question](./question-reference.md) component references.- **Allow people to drill through on data points**: determines whether people can interact with the chart (or charts on a dashboard). Interactivity includes [drilling down](../questions/visualizations/drill-through.md) to individual records from aggregated questions, filtering on click, zooming in, etc. Disabling drill-through for an embedded _question_ also disables people's ability to add filters and summaries.diff --git a/docs/embedding/sdk/ai-chat.md b/docs/embedding/sdk/ai-chat.mddeleted file mode 100644index 80e837bb167..00000000000--- a/docs/embedding/sdk/ai-chat.md+++ /dev/null@@ -1,88 +0,0 @@-----title: "Modular embedding SDK - AI chat"-summary: Embed an AI chat component in your app that can create queries from natural language questions.------# Modular embedding SDK - AI chat----{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %}--You can embed an AI chat in your application similar to [Metabot](../modular-embedding.md) in Metabase.--Embedded Metabot is a more focused version of [Metabot](../../ai/metabot.md) designed to work well in an embedded context. Embedded Metabot can only display ad-hoc questions and metrics; it doesn't know about dashboards.--To help embedded Metabot more easily find and focus on the data you care about most, select the collection containing the models and metrics it should be able to use to create queries.--If you're embedding the Metabot component in an app, you can specify a different collection that embedded Metabot is allowed to use for creating queries.--## Chat preview--You can check out a [demo of the AI chat component](https://embedded-analytics-sdk-demo.metabase.com/admin/analytics/new/ask-metabot) on our Shoppy demo site.--## Example--```typescript-{% include_file "{{ dirname }}/snippets/questions/ai-question.tsx" %}-```--## `MetabotQuestion` props--{% include_file "{{ dirname }}/api/snippets/MetabotQuestionProps.md" snippet="properties" %}--## API reference--- [Component](./api/MetabotQuestion.html)-- [Props](./api/MetabotQuestionProps.html)--## Setting up AI chat--To configure your embedded AI chat in your Metabase:--1. Click the **grid** icon in the upper right.-2. Select **Admin**.-3. Click the **AI** tab.-4. In the left sidebar, click **Embedded Metabot**.--When embedding the Metabot component in your app, you should specify a collection that embedded Metabot is allowed to use for creating queries. Embedded Metabot will only have access to that collection.--For tips and more, see [Metabot settings](../../ai/settings.md).--## Layout--Use the `layout` prop to specify which layout to use for the Metabot component:--- `auto` (default): Metabot uses the `stacked` layout on mobile screens, and a `sidebar` layout on larger screens.-- `stacked`: the question visualization stacks on top of the chat interface.-- `sidebar`: the question visualization appears to the left of the chat interface, which is on a sidebar on the right.--## Building custom AI chat UIs with `useMetabot`--If `MetabotQuestion`'s built-in layouts don't fit your app, use the `useMetabot` hook to read Metabot's conversation state directly and render your own UI. The hook gives you the messages, the chart the agent most recently produced, processing and error state, and actions to submit, cancel, retry, or reset the conversation.--### AI chat with inline charts----When an agent responds, the message can contain a `Chart` component. You can walk the agent's messages and render charts inline alongside the chat transcript:--```typescript-{% include_file "{{ dirname }}/snippets/questions/use-metabot-inline-charts.tsx" %}-```--### AI chat with dedicated chart panel----The `CurrentChart` component is bound to the latest chart the agent produced. Render `CurrentChart` once, and it will swap in new charts as the agent creates them. You'll want to filter chart messages out of the transcript so they don't render twice:--```typescript-{% include_file "{{ dirname }}/snippets/questions/use-metabot-dedicated-chart.tsx" %}-```--### Notes on `useMetabot`--- **Guard against null while waiting for the SDK bundle**: `useMetabot` returns `null` until the SDK bundle has loaded and `<MetabaseProvider>` has mounted. Always guard before use. If you don't guard it, the first render will throw `Cannot read properties of null` when you reach for `metabot.messages`, `metabot.submitMessage`, etc., because the SDK ships its Metabot internals via a code-split chunk that isn't available synchronously.-- **Bring your own Markdown renderer**: `MetabotQuestion` renders agent text messages internally, including markdown formatting, transcript scrolling, and input styling. The `useMetabot` hook hands you the raw conversation state, which means you own the rendering. In particular, agent text messages (`message.type === 'text'`) contain **markdown**: links, bold, lists, inline code. The snippets above render `message.message` as plain text for brevity, but production usage should pass the text through a markdown renderer (`react-markdown`, `markdown-to-jsx`, or your own) so links and formatting display correctly.-- **Strip links returned by the agent**: the agent text may include links pointing back to the host Metabase (like a link to a chart it created). Those links require an authenticated Metabase session, so people won't be able to view the links.diff --git a/docs/embedding/sdk/config.md b/docs/embedding/sdk/config.mdindex 2cf6d74ea26..0438f4bed2c 100644--- a/docs/embedding/sdk/config.md+++ b/docs/embedding/sdk/config.md@@ -36,6 +36,10 @@ To pass a theme, use `defineMetabaseTheme`. See [Reuse a saved theme in the SDK]The SDK can render [custom visualizations](../../questions/visualizations/custom.md) that you allowlist with the `allowedCustomVisualizations` prop on `MetabaseProvider`. See [Custom visualizations in embeds](../custom-visualizations.md).+## Loading and error components++The `loaderComponent` and `errorComponent` props swap the SDK's default loading and error screens for your own React components. See [Customize loading, error, and empty states](./loading-and-errors.md).+## Global event handlersYou can listen for events by defining the `eventHandlers` prop for `MetabaseProvider`.diff --git a/docs/embedding/sdk/introduction.md b/docs/embedding/sdk/introduction.mdindex f4922ec836a..ea7914967c0 100644--- a/docs/embedding/sdk/introduction.md+++ b/docs/embedding/sdk/introduction.md@@ -105,7 +105,7 @@ Start with one of the quickstarts, then see these pages for more info on compone- [Authentication](../authentication.md)- [Embed a chart](../chart.md)-- [AI chat](./ai-chat.md)+- [Embed an AI chat](../ai-chat.md)- [Embed a dashboard](../dashboard.md)- [Actions](./actions.md)- [Appearance](../appearance.md)@@ -113,6 +113,7 @@ Start with one of the quickstarts, then see these pages for more info on compone- [Custom visualizations](../custom-visualizations.md)- [Plugins](./plugins.md)- [Config](./config.md)+- [Customize loading, error, and empty states](./loading-and-errors.md)- [Versioning](./version.md)- [Notes on Next.js](./next-js.md)diff --git a/docs/embedding/sdk/loading-and-errors.md b/docs/embedding/sdk/loading-and-errors.mdnew file mode 100644index 00000000000..32c5f0d4475--- /dev/null+++ b/docs/embedding/sdk/loading-and-errors.md@@ -0,0 +1,51 @@+---+title: Customize loading, error, and empty states+summary: "Replace the modular embedding SDK's default loading screen, error screen, and no-results image with your own."+---++# Customize loading, error, and empty states++++{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %}++While an embedded component is loading, when it fails, or when a query comes back with no rows, the [modular embedding SDK](./introduction.md) renders a screen of its own. You can swap in your own React components and images instead, so all three states match the rest of your app.++These customizations are SDK only. `loaderComponent` and `errorComponent` are props on `MetabaseProvider`, the no-results image comes from a [plugin](./plugins.md), and there's no web component equivalent for any of them.++## Replace the loading and error components++Pass `loaderComponent` and `errorComponent` to `MetabaseProvider`. Every embedded component inside that provider picks them up.++```tsx+{% include_file "{{ dirname }}/snippets/appearance/customizing-loader-and-components.tsx" snippet="imports" %}++{% include_file "{{ dirname }}/snippets/appearance/customizing-loader-and-components.tsx" snippet="example" %}+```++`loaderComponent` receives an optional `label` prop with the loading message, which you can render or ignore. `errorComponent` receives the error details, so you can decide how much of the error to show, and where to put it.++## Error component props++These are the props Metabase passes to your `errorComponent`. The `type` prop tells you how Metabase intended to display the error: `relative` errors sit in the flow of the component, while `fixed` errors are meant to overlay the page, like a toast.++{% include_file "{{ dirname }}/api/snippets/SdkErrorComponentProps.md" snippet="properties" %}++## Replace the no-results illustration++By default, Metabase displays a sailboat image when a query returns no results. To use a different image, set the `getNoDataIllustration` and `getNoObjectIllustration` plugins.++Unlike `loaderComponent` and `errorComponent`, these are [plugins](./plugins.md), so they go in `pluginsConfig` rather than being props of their own. And instead of a React component, each one returns a base64-encoded image:++```typescript+{% include_file "{{ dirname }}/snippets/plugins/custom-images.tsx" snippet="example" %}+```++`getNoDataIllustration` covers a query that came back with no rows. `getNoObjectIllustration` covers a search that turned up nothing, like a search page or an entity picker with no matches. Both can only be set [globally](./plugins.md#plugin-scope), on the provider.++## Further reading++- [Modular embedding SDK plugins](./plugins.md)+- [Appearance](../appearance.md)+- [Modular embedding SDK config](./config.md)+- [Modular embedding components](../components.md)diff --git a/docs/embedding/sdk/plugins.md b/docs/embedding/sdk/plugins.mdindex bd57ebc0589..887bfde24e8 100644--- a/docs/embedding/sdk/plugins.md+++ b/docs/embedding/sdk/plugins.md@@ -58,15 +58,12 @@ To create clickable links in your table columns, set the column's formatting to### `getNoDataIllustration` and `getNoObjectIllustration`-By default, Metabase displays a sailboat image when a query returns no results. To use a different image, you can use `getNoDataIllustration` and `getNoObjectIllustration` plugins which can accept a custom base64-encoded image:+By default, Metabase displays a sailboat image when a query returns no results. The plugins `getNoDataIllustration` and `getNoObjectIllustration` swap in an image of your own. Both can only be used [globally](#plugin-scope) on provider level.-```typescript-{% include_file "{{ dirname }}/snippets/plugins/custom-images.tsx" snippet="example" %}-```--The plugins `getNoDataIllustration` and `getNoObjectIllustration` can only be used [globally](#plugin-scope) on provider level.+See [Replace the no-results illustration](./loading-and-errors.md#replace-the-no-results-illustration) for more information and examples.## Further reading- [Question plugins](../chart.md#customize-what-happens-when-someone-clicks-on-a-chart)- [Dashboard plugins](../dashboard.md#customize-the-menu-on-dashboard-cards-react-sdk-only)+- [Customize loading, error, and empty states](./loading-and-errors.md)diff --git a/docs/embedding/start.md b/docs/embedding/start.mdindex f4e5ba48487..0ce3651a833 100644--- a/docs/embedding/start.md+++ b/docs/embedding/start.md@@ -26,6 +26,10 @@ With the Modular embedding SDK, you can embed individual Metabase components witJump to a SDK quickstart with a sample React application.+### [Modular embedding components](./components.md)++A map of the components you can embed, with links to each component's docs and its attribute and prop reference.+### [Embed a dashboard](./dashboard.md)Embed a dashboard, view-only or interactive, with web components or the React SDK. Let people edit and create dashboards from your app.@@ -54,10 +58,18 @@ Embed a browsable collection with web components or the React SDK, so people canEvery `<metabase-browser>` attribute and the `CollectionBrowser` props.+### [Embed an AI chat](./ai-chat.md)++Embed an AI chat with web components or the React SDK, so people can ask questions of their data in natural language.+### [Guest embedding](./guest-embedding.md)Guest embedding is a secure way to embed charts and dashboards. Guest embeds are view-only; people won't be able to drill-through charts and tables.+### [Customize loading, error, and empty states](./sdk/loading-and-errors.md)++Replace the React SDK's default loading screen, error screen, and no-results image with your own.+### [Custom visualizations in embeds](./custom-visualizations.md)Allowlist the custom visualizations that your embedded components can load. Available in modular embeds that use SSO, with web components or the React SDK.diff --git a/docs/embedding/translations.md b/docs/embedding/translations.mdindex d7e32585c29..0d22cf8a17b 100644--- a/docs/embedding/translations.md+++ b/docs/embedding/translations.md@@ -109,7 +109,7 @@ If the strings you want to translate include markdown formatting, you'll need to## The AI chat component isn't translated-One exception is that Metabase won't translate the text in the [AI chat component](./sdk/ai-chat.md). While Metabot can understand other languages, it works best in English.+One exception is that Metabase won't translate the text in the [AI chat component](./ai-chat.md). While Metabot can understand other languages, it works best in English.## Further readingdiff --git a/frontend/src/metabase/admin/ai/EmbeddedMetabotUpsell.tsx b/frontend/src/metabase/admin/ai/EmbeddedMetabotUpsell.tsxindex 4f68d174417..f6453fc0617 100644--- a/frontend/src/metabase/admin/ai/EmbeddedMetabotUpsell.tsx+++ b/frontend/src/metabase/admin/ai/EmbeddedMetabotUpsell.tsx@@ -31,7 +31,7 @@ export function EmbeddedMetabotUpsell() {><Text lh="lg">{t`With Modular Embedding, you can put an AI chat component in your app to make it easier for your customers to get answers from data.`}{" "}- <ExternalLink href="https://www.metabase.com/docs/latest/embedding/sdk/ai-chat">{t`Learn more`}</ExternalLink>+ <ExternalLink href="https://www.metabase.com/docs/latest/embedding/ai-chat">{t`Learn more`}</ExternalLink></Text></UpsellCard>);