From 81a6bd756a0e82e4419bd1cdb20c7d308ff3881b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 26 Aug 2025 14:08:24 +0200
Subject: [PATCH] Embeddable GitBook API (#3593)

---
 .changeset/forty-trees-sniff.md               |   5 +
 .changeset/sixty-pumas-tell.md                |   5 +
 biome.json                                    |   1 +
 .../embed/src/client/createGitBookFrame.ts    |  25 +++--
 packages/embed/src/client/protocol.ts         |  42 ++++++--
 .../embed/src/react/GitBookAssistantFrame.tsx |  38 -------
 packages/embed/src/react/GitBookFrame.tsx     |  51 +++++++++
 packages/embed/src/react/index.ts             |   1 +
 packages/embed/src/standalone/index.ts        |  42 ++++++--
 .../gitbook/src/components/AI/useAIChat.tsx   |   4 +-
 .../gitbook/src/components/AIChat/AIChat.tsx  | 100 +++++++++---------
 .../components/AIChat/AIChatControlButton.tsx |  40 +++++++
 .../AIChat/AIChatSuggestedQuestions.tsx       |  22 ++--
 .../gitbook/src/components/AIChat/index.ts    |   1 +
 .../Embeddable/EmbeddableAIChat.tsx           |  41 ++++++-
 .../Embeddable/EmbeddableDocsPage.tsx         |  45 ++++++--
 .../components/Embeddable/EmbeddableFrame.tsx |  94 +++++++++++-----
 .../Embeddable/EmbeddableIframeAPI.tsx        |  81 +++++++++++++-
 .../Embeddable/EmbeddableRootLayout.tsx       |  34 +++---
 19 files changed, 480 insertions(+), 192 deletions(-)
 create mode 100644 .changeset/forty-trees-sniff.md
 create mode 100644 .changeset/sixty-pumas-tell.md
 delete mode 100644 packages/embed/src/react/GitBookAssistantFrame.tsx
 create mode 100644 packages/embed/src/react/GitBookFrame.tsx
 create mode 100644 packages/gitbook/src/components/AIChat/AIChatControlButton.tsx

diff --git a/.changeset/forty-trees-sniff.md b/.changeset/forty-trees-sniff.md
new file mode 100644
index 000000000..1696f2f02
--- /dev/null
+++ b/.changeset/forty-trees-sniff.md
@@ -0,0 +1,5 @@
+---
+"@gitbook/embed": minor
+---
+
+Improve API to control the GitBook embed
diff --git a/.changeset/sixty-pumas-tell.md b/.changeset/sixty-pumas-tell.md
new file mode 100644
index 000000000..7a750285b
--- /dev/null
+++ b/.changeset/sixty-pumas-tell.md
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Support customization of buttons and tools through iframe API
diff --git a/biome.json b/biome.json
index 69349302a..53669a0a0 100644
--- a/biome.json
+++ b/biome.json
@@ -18,6 +18,7 @@
             "**/.vercel/**/*",
             "**/.cache/**/*",
             "**/.wrangler/**/*",
+            "packages/embed/standalone/**/*",
             "packages/openapi-parser/src/fixtures/**/*",
             "packages/emoji-codepoints/index.ts",
             "packages/icons/src/data/*.json",
diff --git a/packages/embed/src/client/createGitBookFrame.ts b/packages/embed/src/client/createGitBookFrame.ts
index 031b0c435..baaabf647 100644
--- a/packages/embed/src/client/createGitBookFrame.ts
+++ b/packages/embed/src/client/createGitBookFrame.ts
@@ -1,8 +1,7 @@
 import { createChannel } from 'bidc';
 import type {
     FrameToParentMessage,
-    GitBookPlaceholderSettings,
-    GitBookToolDefinition,
+    GitBookEmbeddableConfiguration,
     ParentToFrameMessage,
 } from './protocol';
 
@@ -22,11 +21,6 @@ export type GitBookFrameClient = {
      */
     postUserMessage: (message: string) => void;
 
-    /**
-     * Register a custom tool.
-     */
-    registerTool: (tool: GitBookToolDefinition) => void;
-
     /**
      * Clear the chat.
      */
@@ -35,7 +29,7 @@ export type GitBookFrameClient = {
     /**
      * Set the placeholder settings.
      */
-    setPlaceholder: (placeholder: GitBookPlaceholderSettings) => void;
+    configure: (settings: Partial<GitBookEmbeddableConfiguration>) => void;
 
     /**
      * Register an event listener.
@@ -53,6 +47,7 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
     const channel = createChannel(iframe.contentWindow);
 
     channel.receive((message: FrameToParentMessage) => {
+        console.log('[gitbook:embed] received message', message);
         if (message.type === 'close') {
             const listeners = events.get('close') || [];
             if (listeners) {
@@ -62,11 +57,19 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
     });
 
     const sendToFrame = (message: ParentToFrameMessage) => {
+        console.log('[gitbook:embed] send message', message);
         channel.send(message);
     };
 
     const events = new Map<string, Array<(...args: any[]) => void>>();
 
+    const configuration: GitBookEmbeddableConfiguration = {
+        buttons: [],
+        welcomeMessage: '',
+        suggestions: [],
+        tools: [],
+    };
+
     return {
         navigateToPage: (pagePath) => {
             sendToFrame({ type: 'navigateToPage', pagePath });
@@ -75,9 +78,11 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
             sendToFrame({ type: 'navigateToAssistant' });
         },
         postUserMessage: (message) => sendToFrame({ type: 'postUserMessage', message }),
-        registerTool: (tool) => sendToFrame({ type: 'registerTool', tool }),
+        configure: (settings) => {
+            Object.assign(configuration, settings);
+            sendToFrame({ type: 'configure', settings: configuration });
+        },
         clearChat: () => sendToFrame({ type: 'clearChat' }),
-        setPlaceholder: (settings) => sendToFrame({ type: 'setPlaceholder', settings }),
         on: (event, listener) => {
             const listeners = events.get(event) || [];
             listeners.push(listener);
diff --git a/packages/embed/src/client/protocol.ts b/packages/embed/src/client/protocol.ts
index 135676899..f19b400e3 100644
--- a/packages/embed/src/client/protocol.ts
+++ b/packages/embed/src/client/protocol.ts
@@ -21,18 +21,42 @@ export type GitBookToolDefinition = AIToolDefinition & {
 };
 
 /**
- * Placeholder settings.
+ * Custom button definition to be passed to the embeddable GitBook.
  */
-export type GitBookPlaceholderSettings = {
+export type GitBookEmbeddableButtonDefinition = {
     /**
-     * Welcome message to be displayed in the placeholder.
+     * Icon to be displayed in the button.
      */
-    welcomeMessage: string;
+    icon: IconName;
 
     /**
-     * Suggestions to be displayed in the placeholder.
+     * Label to be displayed in the button.
      */
+    label: string;
+
+    /**
+     * Callback when the button is clicked.
+     */
+    onClick: () => void | Promise<void>;
+};
+
+/**
+ * Overall configuration for the layout of the embeddable GitBook.
+ */
+export type GitBookEmbeddableConfiguration = {
+    /**
+     * Buttons to be displayed in the header of the embeddable GitBook.
+     */
+    buttons: GitBookEmbeddableButtonDefinition[];
+
+    /** Message to be displayed in the welcome page. */
+    welcomeMessage: string;
+
+    /** Suggestions of questions to be displayed in the welcome page. */
     suggestions: string[];
+
+    /** Tools to be provided to the assistant. */
+    tools: GitBookToolDefinition[];
 };
 
 /**
@@ -43,16 +67,12 @@ export type ParentToFrameMessage =
           type: 'postUserMessage';
           message: string;
       }
-    | {
-          type: 'registerTool';
-          tool: GitBookToolDefinition;
-      }
     | {
           type: 'clearChat';
       }
     | {
-          type: 'setPlaceholder';
-          settings: GitBookPlaceholderSettings;
+          type: 'configure';
+          settings: GitBookEmbeddableConfiguration;
       }
     | {
           type: 'navigateToPage';
diff --git a/packages/embed/src/react/GitBookAssistantFrame.tsx b/packages/embed/src/react/GitBookAssistantFrame.tsx
deleted file mode 100644
index a6e4980f0..000000000
--- a/packages/embed/src/react/GitBookAssistantFrame.tsx
+++ /dev/null
@@ -1,38 +0,0 @@
-import React from 'react';
-import type { GetFrameURLOptions, GitBookFrameClient } from '../client';
-import { useGitBook } from './GitBookProvider';
-
-export type GitBookAssistantFrameProps = {
-    title?: string;
-    className?: string;
-} & GetFrameURLOptions;
-
-/**
- * Render a frame with the GitBook Assistant in it.
- */
-export function GitBookAssistantFrame(props: GitBookAssistantFrameProps) {
-    const { title, className, ...frameOptions } = props;
-
-    const frameRef = React.useRef<HTMLIFrameElement>(null);
-    const gitbookFrameRef = React.useRef<GitBookFrameClient | null>(null);
-    const gitbook = useGitBook();
-    const frameURL = gitbook.getFrameURL(frameOptions);
-
-    React.useEffect(() => {
-        if (frameRef.current) {
-            gitbookFrameRef.current = gitbook.createFrame(frameRef.current);
-        }
-    }, [gitbook]);
-
-    return (
-        <div className={className}>
-            <iframe
-                title={title ?? 'GitBook Assistant'}
-                ref={frameRef}
-                src={frameURL}
-                width="100%"
-                height="100%"
-            />
-        </div>
-    );
-}
diff --git a/packages/embed/src/react/GitBookFrame.tsx b/packages/embed/src/react/GitBookFrame.tsx
new file mode 100644
index 000000000..010d87dd4
--- /dev/null
+++ b/packages/embed/src/react/GitBookFrame.tsx
@@ -0,0 +1,51 @@
+import React from 'react';
+import type {
+    GetFrameURLOptions,
+    GitBookEmbeddableConfiguration,
+    GitBookFrameClient,
+} from '../client';
+import { useGitBook } from './GitBookProvider';
+
+export type GitBookFrameProps = {
+    className?: string;
+} & GetFrameURLOptions &
+    GitBookEmbeddableConfiguration;
+
+/**
+ * Render a frame with the GitBook Assistant in it.
+ */
+export function GitBookFrame(props: GitBookFrameProps) {
+    const { className, visitor, buttons, welcomeMessage, suggestions, tools } = props;
+
+    const frameRef = React.useRef<HTMLIFrameElement>(null);
+    const gitbook = useGitBook();
+    const [gitbookFrame, setGitbookFrame] = React.useState<GitBookFrameClient | null>(null);
+
+    const frameURL = React.useMemo(() => gitbook.getFrameURL({ visitor }), [gitbook, visitor]);
+
+    React.useEffect(() => {
+        if (frameRef.current) {
+            setGitbookFrame(gitbook.createFrame(frameRef.current));
+        }
+    }, [gitbook]);
+
+    React.useEffect(() => {
+        gitbookFrame?.configure({
+            buttons,
+            welcomeMessage,
+            suggestions,
+            tools,
+        });
+    }, [gitbookFrame, buttons, welcomeMessage, suggestions, tools]);
+
+    return (
+        <iframe
+            title="GitBook"
+            ref={frameRef}
+            src={frameURL}
+            width="100%"
+            height="100%"
+            className={className}
+        />
+    );
+}
diff --git a/packages/embed/src/react/index.ts b/packages/embed/src/react/index.ts
index 7b0d5b19c..ff70bb461 100644
--- a/packages/embed/src/react/index.ts
+++ b/packages/embed/src/react/index.ts
@@ -1 +1,2 @@
 export * from './GitBookProvider';
+export * from './GitBookFrame';
diff --git a/packages/embed/src/standalone/index.ts b/packages/embed/src/standalone/index.ts
index a2543c8ba..e9c7135b5 100644
--- a/packages/embed/src/standalone/index.ts
+++ b/packages/embed/src/standalone/index.ts
@@ -4,9 +4,8 @@ import {
     type CreateGitBookOptions,
     type GetFrameURLOptions,
     type GitBookClient,
+    type GitBookEmbeddableConfiguration,
     type GitBookFrameClient,
-    type GitBookPlaceholderSettings,
-    type GitBookToolDefinition,
     createGitBook,
 } from '../client';
 
@@ -29,12 +28,10 @@ type StandaloneCalls =
     | ['toggle']
     // Post a user message
     | ['postUserMessage', string]
-    // Register a tool
-    | ['registerTool', GitBookToolDefinition]
     // Clear the chat
     | ['clearChat']
-    // Configure the placeholder
-    | ['setPlaceholder', GitBookPlaceholderSettings]
+    // Configure the embed
+    | ['configure', Partial<GitBookEmbeddableConfiguration>]
     // Navigate to a page
     | ['navigateToPage', string]
     // Navigate to the assistant
@@ -65,6 +62,12 @@ let widgetIframe: HTMLIFrameElement | undefined;
 let _client: GitBookClient | undefined;
 let _frame: GitBookFrameClient | undefined;
 let frameOptions: GetFrameURLOptions | undefined;
+let frameConfiguration: GitBookEmbeddableConfiguration = {
+    buttons: [],
+    welcomeMessage: '',
+    suggestions: [],
+    tools: [],
+};
 
 function getClient() {
     if (!_client) {
@@ -132,15 +135,30 @@ const GitBook = (...args: StandaloneCalls) => {
         case 'postUserMessage':
             getIframe().frame.postUserMessage(args[1]);
             break;
-        case 'registerTool':
-            getIframe().frame.registerTool(args[1]);
+        case 'configure':
+            frameConfiguration = {
+                ...frameConfiguration,
+                ...args[1],
+            };
+            getIframe().frame.configure({
+                ...frameConfiguration,
+                buttons: [
+                    ...frameConfiguration.buttons,
+
+                    // Always include a close button
+                    {
+                        icon: 'close',
+                        label: 'Close',
+                        onClick: () => {
+                            GitBook('close');
+                        },
+                    },
+                ],
+            });
             break;
         case 'clearChat':
             getIframe().frame.clearChat();
             break;
-        case 'setPlaceholder':
-            getIframe().frame.setPlaceholder(args[1]);
-            break;
         case 'navigateToPage':
             getIframe().frame.navigateToPage(args[1]);
             break;
@@ -156,3 +174,5 @@ const precalls = (window.GitBook as GitBookStandalone | undefined)?.q ?? [];
 // @ts-expect-error - GitBook is not defined in the global scope
 window.GitBook = GitBook;
 precalls.forEach((call) => GitBook(...call));
+
+GitBook('configure', {});
diff --git a/packages/gitbook/src/components/AI/useAIChat.tsx b/packages/gitbook/src/components/AI/useAIChat.tsx
index 43238e21a..992209635 100644
--- a/packages/gitbook/src/components/AI/useAIChat.tsx
+++ b/packages/gitbook/src/components/AI/useAIChat.tsx
@@ -346,7 +346,8 @@ export function AIChatProvider(props: {
                     loading: false,
                     error: false,
                 }));
-            } catch {
+            } catch (error) {
+                console.error('Error streaming AI response', error);
                 globalState.setState((state) => ({
                     ...state,
                     loading: false,
@@ -359,6 +360,7 @@ export function AIChatProvider(props: {
             renderMessageOptions?.withLinkPreviews,
             renderMessageOptions?.withToolCalls,
             renderMessageOptions?.asEmbeddable,
+            language,
         ]
     );
 
diff --git a/packages/gitbook/src/components/AIChat/AIChat.tsx b/packages/gitbook/src/components/AIChat/AIChat.tsx
index b1b00c449..3192636f6 100644
--- a/packages/gitbook/src/components/AIChat/AIChat.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChat.tsx
@@ -11,10 +11,18 @@ import {
     useAIChatController,
     useAIChatState,
 } from '../AI';
-import { EmbeddableFrame } from '../Embeddable/EmbeddableFrame';
+import {
+    EmbeddableFrame,
+    EmbeddableFrameBody,
+    EmbeddableFrameButtons,
+    EmbeddableFrameHeader,
+    EmbeddableFrameHeaderMain,
+    EmbeddableFrameSubtitle,
+    EmbeddableFrameTitle,
+} from '../Embeddable/EmbeddableFrame';
 import { useNow } from '../hooks';
 import { Button } from '../primitives';
-import { DropdownMenu, DropdownMenuItem } from '../primitives';
+import { AIChatControlButton } from './AIChatControlButton';
 import { AIChatIcon } from './AIChatIcon';
 import { AIChatInput } from './AIChatInput';
 import { AIChatMessages } from './AIChatMessages';
@@ -66,45 +74,17 @@ export function AIChat(props: { trademark: boolean }) {
             data-testid="ai-chat"
             className="ai-chat inset-y-0 right-0 z-40 mx-auto flex max-w-3xl animate-present scroll-mt-36 px-4 py-4 transition-all duration-300 sm:px-6 lg:fixed lg:w-80 lg:animate-enter-from-right lg:pr-4 lg:pl-0 xl:w-96"
         >
-            <EmbeddableFrame
-                className="relative circular-corners:rounded-3xl rounded-corners:rounded-md depth-subtle:shadow-lg shadow-tint ring-1 ring-tint-subtle"
-                icon={<AIChatDynamicIcon trademark={trademark} />}
-                title={getAIChatName(language, trademark)}
-                subtitle={
-                    chat.loading
-                        ? chat.messages[chat.messages.length - 1].content
-                            ? tString(language, 'ai_chat_working')
-                            : tString(language, 'ai_chat_thinking')
-                        : ''
-                }
-                buttons={
-                    <>
-                        {chat.messages.length > 0 ? (
-                            <DropdownMenu
-                                button={
-                                    <Button
-                                        onClick={() => {}}
-                                        iconOnly
-                                        icon="ellipsis"
-                                        label={tString(language, 'actions')}
-                                        variant="blank"
-                                        size="default"
-                                    />
-                                }
-                            >
-                                <DropdownMenuItem
-                                    onClick={() => {
-                                        chatController.clear();
-                                    }}
-                                >
-                                    <Icon
-                                        icon="broom-wide"
-                                        className="size-3 shrink-0 text-tint-subtle"
-                                    />
-                                    {t(language, 'ai_chat_clear_conversation')}
-                                </DropdownMenuItem>
-                            </DropdownMenu>
-                        ) : null}
+            <EmbeddableFrame className="relative circular-corners:rounded-3xl rounded-corners:rounded-md depth-subtle:shadow-lg shadow-tint ring-1 ring-tint-subtle">
+                <EmbeddableFrameHeader>
+                    <AIChatDynamicIcon trademark={trademark} />
+                    <EmbeddableFrameHeaderMain>
+                        <EmbeddableFrameTitle>
+                            {getAIChatName(language, trademark)}
+                        </EmbeddableFrameTitle>
+                        <AIChatSubtitle chat={chat} />
+                    </EmbeddableFrameHeaderMain>
+                    <EmbeddableFrameButtons>
+                        <AIChatControlButton />
                         <Button
                             onClick={() => chatController.close()}
                             iconOnly
@@ -113,10 +93,11 @@ export function AIChat(props: { trademark: boolean }) {
                             variant="blank"
                             size="default"
                         />
-                    </>
-                }
-            >
-                <AIChatBody chatController={chatController} chat={chat} trademark={trademark} />
+                    </EmbeddableFrameButtons>
+                </EmbeddableFrameHeader>
+                <EmbeddableFrameBody>
+                    <AIChatBody chatController={chatController} chat={chat} trademark={trademark} />
+                </EmbeddableFrameBody>
             </EmbeddableFrame>
         </div>
     );
@@ -139,7 +120,7 @@ export function AIChatDynamicIcon(props: {
                 chat.error
                     ? 'error'
                     : chat.loading
-                      ? chat.messages[chat.messages.length - 1].content
+                      ? chat.messages[chat.messages.length - 1]?.content
                           ? 'working'
                           : 'thinking'
                       : chat.messages.length > 0
@@ -152,6 +133,24 @@ export function AIChatDynamicIcon(props: {
     );
 }
 
+/**
+ * Subtitle of the AI chat window.
+ */
+export function AIChatSubtitle(props: {
+    chat: AIChatState;
+}) {
+    const { chat } = props;
+    const language = useLanguage();
+
+    return (
+        <EmbeddableFrameSubtitle className={chat.loading ? 'h-3 opacity-11' : 'h-0 opacity-0'}>
+            {chat.messages[chat.messages.length - 1]?.content
+                ? tString(language, 'ai_chat_working')
+                : tString(language, 'ai_chat_thinking')}
+        </EmbeddableFrameSubtitle>
+    );
+}
+
 /**
  * Body of the AI chat window.
  */
@@ -159,8 +158,10 @@ export function AIChatBody(props: {
     chatController: AIChatController;
     chat: AIChatState;
     trademark: boolean;
+    welcomeMessage?: string;
+    suggestions?: string[];
 }) {
-    const { chatController, chat, trademark } = props;
+    const { chatController, chat, trademark, suggestions } = props;
 
     const [input, setInput] = React.useState('');
 
@@ -246,7 +247,10 @@ export function AIChatBody(props: {
                             </p>
                         </div>
                         {!chat.error ? (
-                            <AIChatSuggestedQuestions chatController={chatController} />
+                            <AIChatSuggestedQuestions
+                                chatController={chatController}
+                                suggestions={suggestions}
+                            />
                         ) : null}
                     </div>
                 ) : (
diff --git a/packages/gitbook/src/components/AIChat/AIChatControlButton.tsx b/packages/gitbook/src/components/AIChat/AIChatControlButton.tsx
new file mode 100644
index 000000000..f909b62ab
--- /dev/null
+++ b/packages/gitbook/src/components/AIChat/AIChatControlButton.tsx
@@ -0,0 +1,40 @@
+'use client';
+
+import { useLanguage } from '@/intl/client';
+import { t, tString } from '@/intl/translate';
+import { Icon } from '@gitbook/icons';
+import { useAIChatController, useAIChatState } from '../AI';
+import { Button, DropdownMenu, DropdownMenuItem } from '../primitives';
+
+/**
+ * Button to control the chat (clear, etc.)
+ */
+export function AIChatControlButton() {
+    const language = useLanguage();
+    const chat = useAIChatState();
+    const chatController = useAIChatController();
+
+    return chat.messages.length > 0 ? (
+        <DropdownMenu
+            button={
+                <Button
+                    onClick={() => {}}
+                    iconOnly
+                    icon="ellipsis"
+                    label={tString(language, 'actions')}
+                    variant="blank"
+                    size="default"
+                />
+            }
+        >
+            <DropdownMenuItem
+                onClick={() => {
+                    chatController.clear();
+                }}
+            >
+                <Icon icon="broom-wide" className="size-3 shrink-0 text-tint-subtle" />
+                {t(language, 'ai_chat_clear_conversation')}
+            </DropdownMenuItem>
+        </DropdownMenu>
+    ) : null;
+}
diff --git a/packages/gitbook/src/components/AIChat/AIChatSuggestedQuestions.tsx b/packages/gitbook/src/components/AIChat/AIChatSuggestedQuestions.tsx
index 5f0089ebd..f3951698e 100644
--- a/packages/gitbook/src/components/AIChat/AIChatSuggestedQuestions.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChatSuggestedQuestions.tsx
@@ -2,19 +2,23 @@ import { tString, useLanguage } from '@/intl/client';
 import type { AIChatController } from '../AI';
 import { Button } from '../primitives';
 
-export default function AIChatSuggestedQuestions(props: { chatController: AIChatController }) {
-    const { chatController } = props;
+export default function AIChatSuggestedQuestions(props: {
+    chatController: AIChatController;
+    suggestions?: string[];
+}) {
     const language = useLanguage();
-
-    const DEFAULT_SUGGESTED_QUESTIONS = [
-        tString(language, 'ai_chat_suggested_questions_about_this_page'),
-        tString(language, 'ai_chat_suggested_questions_read_next'),
-        tString(language, 'ai_chat_suggested_questions_example'),
-    ];
+    const {
+        chatController,
+        suggestions = [
+            tString(language, 'ai_chat_suggested_questions_about_this_page'),
+            tString(language, 'ai_chat_suggested_questions_read_next'),
+            tString(language, 'ai_chat_suggested_questions_example'),
+        ],
+    } = props;
 
     return (
         <div className="flex flex-col items-center gap-2">
-            {DEFAULT_SUGGESTED_QUESTIONS.map((question, index) => (
+            {suggestions.map((question, index) => (
                 <Button
                     key={question}
                     variant="secondary"
diff --git a/packages/gitbook/src/components/AIChat/index.ts b/packages/gitbook/src/components/AIChat/index.ts
index 0c0dbd093..12eaa899e 100644
--- a/packages/gitbook/src/components/AIChat/index.ts
+++ b/packages/gitbook/src/components/AIChat/index.ts
@@ -2,3 +2,4 @@ export * from './AIChat';
 export * from './AIChatButton';
 export * from './AIChatIcon';
 export * from './AIResponseFeedback';
+export * from './AIChatControlButton';
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
index f050a0b64..ad3097546 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
@@ -1,7 +1,21 @@
 'use client';
 
 import { useAIChatController, useAIChatState } from '@/components/AI';
-import { AIChatBody } from '@/components/AIChat';
+import {
+    AIChatBody,
+    AIChatControlButton,
+    AIChatDynamicIcon,
+    AIChatSubtitle,
+} from '@/components/AIChat';
+import {
+    EmbeddableFrame,
+    EmbeddableFrameBody,
+    EmbeddableFrameButtons,
+    EmbeddableFrameHeader,
+    EmbeddableFrameHeaderMain,
+    EmbeddableFrameTitle,
+} from './EmbeddableFrame';
+import { EmbeddableIframeButtons, useEmbeddableConfiguration } from './EmbeddableIframeAPI';
 
 /**
  * Embeddable AI chat window in an iframe.
@@ -12,6 +26,29 @@ export function EmbeddableAIChat(props: {
     const { trademark } = props;
     const chat = useAIChatState();
     const chatController = useAIChatController();
+    const configuration = useEmbeddableConfiguration();
 
-    return <AIChatBody trademark={trademark} chatController={chatController} chat={chat} />;
+    return (
+        <EmbeddableFrame>
+            <EmbeddableFrameHeader>
+                <AIChatDynamicIcon trademark={trademark} />
+                <EmbeddableFrameHeaderMain>
+                    <EmbeddableFrameTitle>GitBook Assistant</EmbeddableFrameTitle>
+                    <AIChatSubtitle chat={chat} />
+                </EmbeddableFrameHeaderMain>
+                <EmbeddableFrameButtons>
+                    <AIChatControlButton />
+                    <EmbeddableIframeButtons />
+                </EmbeddableFrameButtons>
+            </EmbeddableFrameHeader>
+            <EmbeddableFrameBody>
+                <AIChatBody
+                    trademark={trademark}
+                    chatController={chatController}
+                    chat={chat}
+                    suggestions={configuration.suggestions}
+                />
+            </EmbeddableFrameBody>
+        </EmbeddableFrame>
+    );
 }
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
index c481363e0..685190629 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
@@ -3,6 +3,15 @@ import { type PagePathParams, getSitePageData } from '@/components/SitePage';
 import { PageBody } from '@/components/PageBody';
 import type { GitBookSiteContext } from '@/lib/context';
 import type { Metadata } from 'next';
+import { Button } from '../primitives';
+import {
+    EmbeddableFrame,
+    EmbeddableFrameBody,
+    EmbeddableFrameButtons,
+    EmbeddableFrameHeader,
+    EmbeddableFrameHeaderMain,
+} from './EmbeddableFrame';
+import { EmbeddableIframeButtons } from './EmbeddableIframeAPI';
 
 export const dynamic = 'force-static';
 
@@ -22,15 +31,33 @@ export async function EmbeddableDocsPage(props: EmbeddableDocsPageProps) {
     });
 
     return (
-        <div className="flex-1 overflow-auto p-6">
-            <PageBody
-                context={context}
-                page={page}
-                ancestors={ancestors}
-                document={document}
-                withPageFeedback={withPageFeedback}
-            />
-        </div>
+        <EmbeddableFrame>
+            <EmbeddableFrameHeader>
+                <EmbeddableFrameHeaderMain>
+                    <Button
+                        href={context.linker.toPathInSite('~gitbook/embed/assistant')}
+                        size="default"
+                        variant="blank"
+                        icon="arrow-left"
+                        label="Back"
+                    />
+                </EmbeddableFrameHeaderMain>
+                <EmbeddableFrameButtons>
+                    <EmbeddableIframeButtons />
+                </EmbeddableFrameButtons>
+            </EmbeddableFrameHeader>
+            <EmbeddableFrameBody>
+                <div className="flex-1 overflow-auto p-6">
+                    <PageBody
+                        context={context}
+                        page={page}
+                        ancestors={ancestors}
+                        document={document}
+                        withPageFeedback={withPageFeedback}
+                    />
+                </div>
+            </EmbeddableFrameBody>
+        </EmbeddableFrame>
     );
 }
 
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx
index a558fb2ba..9b233da75 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx
@@ -1,27 +1,17 @@
 import { tcls } from '@/lib/tailwind';
 import React from 'react';
 
-export type EmbeddableFrameHeaderProps = {
-    icon: React.ReactNode;
-
-    title: string;
-    subtitle?: string;
-
-    buttons?: React.ReactNode;
+export type EmbeddableFrameProps = React.ComponentProps<'div'> & {
+    children: React.ReactNode;
 };
 
-export type EmbeddableFrameProps = EmbeddableFrameHeaderProps &
-    React.ComponentProps<'div'> & {
-        children: React.ReactNode;
-    };
-
 /**
  * Presentation component to display an embeddable frame.
  * It is used for the AI chat window in the docs, but also when embedded in another website.
  */
 export const EmbeddableFrame = React.forwardRef<HTMLDivElement, EmbeddableFrameProps>(
     (props, ref) => {
-        const { icon, title, subtitle, buttons, children, ...divProps } = props;
+        const { children, ...divProps } = props;
 
         return (
             <div
@@ -32,22 +22,70 @@ export const EmbeddableFrame = React.forwardRef<HTMLDivElement, EmbeddableFrameP
                 )}
                 ref={ref}
             >
-                <div className="flex select-none items-center gap-2 border-tint-subtle border-b bg-tint-subtle px-4 py-2 text-tint-strong">
-                    {icon}
-                    <div className="flex flex-col">
-                        <div className="font-bold">{title}</div>
-                        <div
-                            className={`text-tint text-xs leading-none transition-all duration-500 ${
-                                subtitle ? 'h-3 opacity-11' : 'h-0 opacity-0'
-                            }`}
-                        >
-                            {subtitle}
-                        </div>
-                    </div>
-                    <div className="ml-auto flex gap-2">{buttons}</div>
-                </div>
-                <div className="flex flex-1 flex-col overflow-hidden">{children}</div>
+                {children}
             </div>
         );
     }
 );
+
+export function EmbeddableFrameHeader(props: {
+    children: React.ReactNode;
+}) {
+    const { children } = props;
+
+    return (
+        <div className="flex select-none items-center gap-2 border-tint-subtle border-b bg-tint-subtle px-4 py-2 text-tint-strong">
+            {children}
+        </div>
+    );
+}
+
+export function EmbeddableFrameHeaderMain(props: {
+    children: React.ReactNode;
+}) {
+    const { children } = props;
+
+    return <div className="flex flex-1 flex-col">{children}</div>;
+}
+
+export function EmbeddableFrameBody(props: {
+    children: React.ReactNode;
+}) {
+    const { children } = props;
+
+    return <div className="flex flex-1 flex-col overflow-hidden">{children}</div>;
+}
+
+export function EmbeddableFrameTitle(props: {
+    children: React.ReactNode;
+}) {
+    const { children } = props;
+
+    return <div className="font-bold">{children}</div>;
+}
+
+export function EmbeddableFrameSubtitle(props: {
+    children: React.ReactNode;
+    className?: string;
+}) {
+    const { children, className } = props;
+
+    return (
+        <div
+            className={tcls(
+                'text-tint text-xs leading-none transition-all duration-500',
+                className
+            )}
+        >
+            {children}
+        </div>
+    );
+}
+
+export function EmbeddableFrameButtons(props: {
+    children: React.ReactNode;
+}) {
+    const { children } = props;
+
+    return <div className="ml-auto flex gap-2">{children}</div>;
+}
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
index 85abe0cfb..f37dd4c55 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
@@ -1,15 +1,31 @@
 'use client';
 
-import type { ParentToFrameMessage } from '@gitbook/embed';
+import type { GitBookEmbeddableConfiguration, ParentToFrameMessage } from '@gitbook/embed';
 import { createChannel } from 'bidc';
 import React from 'react';
 
 import { useAIChatController } from '@/components/AI';
+import { useRouter } from 'next/navigation';
+import { createStore, useStore } from 'zustand';
+import { integrationsAssistantTools } from '../Integrations';
+import { Button } from '../primitives';
+
+const embeddableConfiguration = createStore<GitBookEmbeddableConfiguration>(() => ({
+    buttons: [],
+    welcomeMessage: '',
+    suggestions: [],
+    tools: [],
+}));
 
 /**
  * Expose the API to communicate with the parent window.
  */
-export function EmbeddableIframeAPI() {
+export function EmbeddableIframeAPI(props: {
+    baseURL: string;
+}) {
+    const { baseURL } = props;
+
+    const router = useRouter();
     const chatController = useAIChatController();
 
     React.useEffect(() => {
@@ -17,11 +33,14 @@ export function EmbeddableIframeAPI() {
             return;
         }
 
+        console.log('[gitbook] create channel with parent window');
         const channel = createChannel();
 
         channel.receive((payload) => {
             const message = payload as ParentToFrameMessage;
 
+            console.log('[gitbook] received message', message);
+
             switch (message.type) {
                 case 'clearChat': {
                     chatController.clear();
@@ -33,12 +52,64 @@ export function EmbeddableIframeAPI() {
                     });
                     break;
                 }
-                // TODO: Handle other messages
+                case 'configure': {
+                    embeddableConfiguration.setState(message.settings);
+                    integrationsAssistantTools.setState({
+                        tools: message.settings.tools,
+                    });
+                    break;
+                }
+                case 'navigateToPage': {
+                    router.push(`${baseURL}/page/${message.pagePath}`);
+                    break;
+                }
+                case 'navigateToAssistant': {
+                    router.push(`${baseURL}/assistant`);
+                    break;
+                }
             }
         });
 
-        return channel.cleanup();
-    }, [chatController]);
+        return () => {
+            console.log('[gitbook] cleanup');
+            channel.cleanup();
+        };
+    }, [chatController, router, baseURL]);
 
     return null;
 }
+
+/**
+ * Hook to get the configuration from the parent window.
+ */
+export function useEmbeddableConfiguration<T = GitBookEmbeddableConfiguration>(
+    // @ts-expect-error - This is a workaround to allow the function to be optional.
+    fn: (state: GitBookEmbeddableConfiguration) => T = (state) => state
+) {
+    return useStore(embeddableConfiguration, fn);
+}
+
+/**
+ * Display the buttons defined by the parent window.
+ */
+export function EmbeddableIframeButtons() {
+    const buttons = useEmbeddableConfiguration((state) => state.buttons);
+
+    return (
+        <>
+            {buttons.map((button) => (
+                <Button
+                    key={button.label}
+                    size="default"
+                    variant="blank"
+                    icon={button.icon}
+                    label={button.label}
+                    iconOnly
+                    onClick={() => {
+                        button.onClick();
+                    }}
+                />
+            ))}
+        </>
+    );
+}
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
index 9267e4e8a..3e2ecd1ff 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
@@ -1,6 +1,4 @@
 import { AIChatProvider, AIContextProvider } from '@/components/AI';
-import { AIChatDynamicIcon } from '@/components/AIChat';
-import { EmbeddableFrame } from '@/components/Embeddable';
 import { CustomizationRootLayout } from '@/components/RootLayout';
 import {
     SiteLayoutClientContexts,
@@ -29,26 +27,22 @@ export async function EmbeddableRootLayout({
                 externalLinksTarget={context.customization.externalLinks.target}
                 contextId={context.contextId}
             >
-                <EmbeddableFrame
-                    icon={<AIChatDynamicIcon trademark={context.customization.trademark.enabled} />}
-                    title="Test"
-                    className="fixed inset-0"
+                <AIContextProvider
+                    aiMode={CustomizationAIMode.Assistant}
+                    trademark={context.customization.trademark.enabled}
                 >
-                    <AIContextProvider
-                        aiMode={CustomizationAIMode.Assistant}
-                        trademark={context.customization.trademark.enabled}
+                    <AIChatProvider
+                        renderMessageOptions={{
+                            withLinkPreviews: false,
+                            asEmbeddable: true,
+                        }}
                     >
-                        <AIChatProvider
-                            renderMessageOptions={{
-                                withLinkPreviews: false,
-                                asEmbeddable: true,
-                            }}
-                        >
-                            {children}
-                            <EmbeddableIframeAPI />
-                        </AIChatProvider>
-                    </AIContextProvider>
-                </EmbeddableFrame>
+                        <div className="fixed inset-0 flex flex-col">{children}</div>
+                        <EmbeddableIframeAPI
+                            baseURL={context.linker.toPathInSpace('~gitbook/embed/')}
+                        />
+                    </AIChatProvider>
+                </AIContextProvider>
             </SiteLayoutClientContexts>
         </CustomizationRootLayout>
     );