From b3875a19d7318fd1ef681d79ee2a13147ee8d166 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Wed, 11 Mar 2026 10:46:10 +0100
Subject: [PATCH] Add `assistantName` property to Docs Embed (#4095)

---
 .changeset/afraid-peas-argue.md               |  5 ++++
 .changeset/orange-pillows-begin.md            |  5 ++++
 packages/embed/README.md                      | 15 ++++++++++
 packages/embed/src/client/protocol.ts         |  6 ++++
 packages/embed/src/react/GitBookFrame.tsx     | 14 +++++++++-
 packages/gitbook/src/components/AI/useAI.tsx  |  9 +++---
 .../gitbook/src/components/AIChat/AIChat.tsx  |  2 +-
 .../Embeddable/EmbeddableAIChat.tsx           |  8 +++---
 .../EmbeddableAIContextProvider.tsx           | 28 +++++++++++++++++++
 .../Embeddable/EmbeddableRootLayout.tsx       |  6 ++--
 10 files changed, 85 insertions(+), 13 deletions(-)
 create mode 100644 .changeset/afraid-peas-argue.md
 create mode 100644 .changeset/orange-pillows-begin.md
 create mode 100644 packages/gitbook/src/components/Embeddable/EmbeddableAIContextProvider.tsx

diff --git a/.changeset/afraid-peas-argue.md b/.changeset/afraid-peas-argue.md
new file mode 100644
index 000000000..317529092
--- /dev/null
+++ b/.changeset/afraid-peas-argue.md
@@ -0,0 +1,5 @@
+---
+"@gitbook/embed": minor
+---
+
+Support `assistantName` property to override Assistant name
diff --git a/.changeset/orange-pillows-begin.md b/.changeset/orange-pillows-begin.md
new file mode 100644
index 000000000..7bb5f528c
--- /dev/null
+++ b/.changeset/orange-pillows-begin.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Refactor embeddable context to merge local & site properties in one unified way
diff --git a/packages/embed/README.md b/packages/embed/README.md
index 4c24868b9..096546c05 100644
--- a/packages/embed/README.md
+++ b/packages/embed/README.md
@@ -49,6 +49,7 @@ GitBook('configure', {
         }
     ],
     greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
+    assistantName: 'Support Assistant',
     suggestions: ['What is GitBook?', 'How do I get started?'],
     tools: [/* ... */],
     closeButton: true,
@@ -100,6 +101,7 @@ frame.configure({
         }
     ],
     greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
+    assistantName: 'Support Assistant',
     suggestions: ['What is GitBook?', 'How do I get started?'],
     tools: [/* ... */],
     closeButton: true
@@ -126,6 +128,7 @@ import { GitBookProvider, GitBookFrame } from '@gitbook/embed/react';
         }}
         tabs={['assistant', 'docs']}
         greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
+        assistantName="Support Assistant"
         suggestions={['What is GitBook?', 'How do I get started?']}
         actions={[
             {
@@ -328,6 +331,18 @@ greeting: {
 }
 ```
 
+### `assistantName`
+
+Available in: Standalone script, NPM package, React components
+
+Override the assistant name displayed in the chat header and assistant entry points (for example, sidebar tabs and action labels). This name will be limited to 32 characters to prevent text overflow.
+
+- **Type**: `string`
+
+```javascript
+assistantName: 'Support Assistant'
+```
+
 ### `suggestions`
 
 Available in: Standalone script, NPM package, React components
diff --git a/packages/embed/src/client/protocol.ts b/packages/embed/src/client/protocol.ts
index 7413783b8..2f5fcadcf 100644
--- a/packages/embed/src/client/protocol.ts
+++ b/packages/embed/src/client/protocol.ts
@@ -62,6 +62,12 @@ export type GitBookEmbeddableConfiguration = {
         subtitle: string;
     };
 
+    /**
+     * Override the assistant name displayed in the UI.
+     * Limited to 32 characters.
+     */
+    assistantName?: string;
+
     /** Suggestions of questions to be displayed in the welcome page. */
     suggestions: string[];
 
diff --git a/packages/embed/src/react/GitBookFrame.tsx b/packages/embed/src/react/GitBookFrame.tsx
index 479943b55..28bee3449 100644
--- a/packages/embed/src/react/GitBookFrame.tsx
+++ b/packages/embed/src/react/GitBookFrame.tsx
@@ -27,6 +27,7 @@ export function GitBookFrame(props: GitBookFrameProps) {
         tabs = ['assistant', 'docs'],
         trademark = true,
         closeButton = false,
+        assistantName,
     } = props;
 
     const frameRef = useRef<HTMLIFrameElement>(null);
@@ -50,8 +51,19 @@ export function GitBookFrame(props: GitBookFrameProps) {
             tools,
             closeButton,
             trademark,
+            assistantName,
         });
-    }, [gitbookFrame, actions, greeting, suggestions, tools, tabs, closeButton, trademark]);
+    }, [
+        gitbookFrame,
+        actions,
+        greeting,
+        suggestions,
+        tools,
+        tabs,
+        closeButton,
+        trademark,
+        assistantName,
+    ]);
 
     return (
         <iframe
diff --git a/packages/gitbook/src/components/AI/useAI.tsx b/packages/gitbook/src/components/AI/useAI.tsx
index 6229cb302..ba704623f 100644
--- a/packages/gitbook/src/components/AI/useAI.tsx
+++ b/packages/gitbook/src/components/AI/useAI.tsx
@@ -17,6 +17,7 @@ export type AIConfig = {
     aiMode: CustomizationAIMode;
     suggestions?: string[];
     trademark: boolean;
+    assistantName?: string;
     greeting?: {
         title: string;
         subtitle: string;
@@ -54,10 +55,10 @@ export type Assistant = Omit<GitBookAssistant, 'icon'> & {
 const AIContext = React.createContext<AIConfig | null>(null);
 
 export function AIContextProvider(props: React.PropsWithChildren<AIConfig>): React.ReactElement {
-    const { aiMode, trademark, suggestions, greeting, children } = props;
+    const { aiMode, trademark, suggestions, greeting, assistantName, children } = props;
     const value = React.useMemo(
-        () => ({ aiMode, trademark, suggestions, greeting }),
-        [aiMode, trademark, suggestions, greeting]
+        () => ({ aiMode, trademark, suggestions, greeting, assistantName }),
+        [aiMode, trademark, suggestions, greeting, assistantName]
     );
     return <AIContext.Provider value={value}>{children}</AIContext.Provider>;
 }
@@ -91,7 +92,7 @@ export function useAI(): AIContext {
     if (config.aiMode === CustomizationAIMode.Assistant) {
         assistants.push({
             id: 'gitbook-assistant',
-            label: getAIChatName(language, config.trademark),
+            label: config.assistantName ?? getAIChatName(language, config.trademark),
             icon: (
                 <AIChatIcon
                     state={chat.loading ? 'thinking' : 'default'}
diff --git a/packages/gitbook/src/components/AIChat/AIChat.tsx b/packages/gitbook/src/components/AIChat/AIChat.tsx
index 28ef35af0..54fd715ce 100644
--- a/packages/gitbook/src/components/AIChat/AIChat.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChat.tsx
@@ -92,7 +92,7 @@ export function AIChat() {
                         <AIChatDynamicIcon trademark={config.trademark} />
                         <EmbeddableFrameHeaderMain>
                             <EmbeddableFrameTitle>
-                                {getAIChatName(language, config.trademark)}
+                                {config.assistantName ?? getAIChatName(language, config.trademark)}
                             </EmbeddableFrameTitle>
                             <AIChatSubtitle chat={chat} />
                         </EmbeddableFrameHeaderMain>
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
index 43cda0c1b..ae63adc8e 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
@@ -66,7 +66,7 @@ export function EmbeddableAIChat(props: EmbeddableAIChatProps) {
 
     const tabsRef = React.useRef<HTMLDivElement>(null);
     const hasDocsTab = embedConfig.tabs.includes('docs');
-    const trademark = siteConfig.trademark && (embedConfig.trademark ?? true);
+    const trademark = siteConfig.trademark;
     const currentLinkContext = use(LinkContext);
     const linkContext: LinkContextType = useMemo(
         () =>
@@ -100,7 +100,7 @@ export function EmbeddableAIChat(props: EmbeddableAIChatProps) {
                     ) : null}
                     <EmbeddableFrameHeaderMain>
                         <EmbeddableFrameTitle>
-                            {getAIChatName(language, trademark)}
+                            {siteConfig.assistantName ?? getAIChatName(language, trademark)}
                         </EmbeddableFrameTitle>
                         <AIChatSubtitle chat={chat} />
                     </EmbeddableFrameHeaderMain>
@@ -113,8 +113,8 @@ export function EmbeddableAIChat(props: EmbeddableAIChatProps) {
                         <AIChatBody
                             chatController={chatController}
                             chat={chat}
-                            suggestions={embedConfig.suggestions}
-                            greeting={embedConfig.greeting}
+                            suggestions={siteConfig.suggestions}
+                            greeting={siteConfig.greeting}
                             trademark={trademark}
                         />
                     </LinkContext>
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableAIContextProvider.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableAIContextProvider.tsx
new file mode 100644
index 000000000..ba26bcf58
--- /dev/null
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableAIContextProvider.tsx
@@ -0,0 +1,28 @@
+'use client';
+
+import { type AIConfig, AIContextProvider } from '@/components/AI';
+import type { PropsWithChildren } from 'react';
+import { useEmbeddableConfiguration } from './EmbeddableIframeAPI';
+
+type EmbeddableAIContextProviderProps = PropsWithChildren<AIConfig>;
+
+/**
+ * AI context provider for embeddable routes.
+ * Merges the static site AI config with runtime embed configuration updates.
+ */
+export function EmbeddableAIContextProvider(props: EmbeddableAIContextProviderProps) {
+    const { aiMode, suggestions, greeting, trademark, children } = props;
+    const embedConfig = useEmbeddableConfiguration();
+
+    return (
+        <AIContextProvider
+            aiMode={aiMode}
+            suggestions={embedConfig.suggestions ?? suggestions}
+            greeting={embedConfig.greeting ?? greeting}
+            trademark={trademark && (embedConfig.trademark ?? true)}
+            assistantName={embedConfig.assistantName?.substring(0, 32)} // Limit to 32 characters
+        >
+            {children}
+        </AIContextProvider>
+    );
+}
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
index 6b574ce50..4ac6915ed 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
@@ -1,4 +1,3 @@
-import { AIContextProvider } from '@/components/AI';
 import { CustomizationRootLayout } from '@/components/RootLayout';
 import {
     SiteLayoutClientContexts,
@@ -11,6 +10,7 @@ import { SiteInsightsTrademarkPlacement } from '@gitbook/api';
 import { SpaceLayoutServerContext } from '../SpaceLayout';
 import { Trademark } from '../TableOfContents/Trademark';
 import { NavigationLoader } from '../primitives/NavigationLoader';
+import { EmbeddableAIContextProvider } from './EmbeddableAIContextProvider';
 import { EmbeddableIframeAPI } from './EmbeddableIframeAPI';
 import { IfEmbeddableTrademark } from './EmbeddableTrademark';
 
@@ -41,7 +41,7 @@ export async function EmbeddableRootLayout({
                 contextId={context.contextId}
                 proxyOrigin={context.site.proxy?.origin}
             >
-                <AIContextProvider
+                <EmbeddableAIContextProvider
                     aiMode={context.customization.ai.mode}
                     suggestions={context.customization.ai.suggestions}
                     trademark={context.customization.trademark.enabled}
@@ -72,7 +72,7 @@ export async function EmbeddableRootLayout({
                             baseURL={context.linker.toPathInSite('~gitbook/embed/')}
                         />
                     </SpaceLayoutServerContext>
-                </AIContextProvider>
+                </EmbeddableAIContextProvider>
             </SiteLayoutClientContexts>
         </CustomizationRootLayout>
     );