diff --git a/.spelling b/.spelling index e6601448c..a3f0f89f6 100644 --- a/.spelling +++ b/.spelling @@ -300,6 +300,7 @@ invocable analytics ClientID chatbot +chatbots OAuth2 LLMs npm diff --git a/content/guides/embed/box-embed.md b/content/guides/embed/box-embed.md index 3aa10ad77..9f4c56c80 100644 --- a/content/guides/embed/box-embed.md +++ b/content/guides/embed/box-embed.md @@ -11,13 +11,13 @@ alias_paths: # Box Embed Box Embed is a HTML-based framework that allows embedding the entire -Box Web App experience in a custom-made application. Box Embed provides the ability to upload, search, comment, share, tag, and edit files using Box Edit. +Box Web App experience in a custom-made application. Box Embed provides the ability to upload, search, comment, share, tag, and edit files using Box Edit. You can also embed Box Hubs AI Chat for a focused chatbot experience. ## Before you start To create a widget, you need to: -* Set an embeddable element, such as a **folder**, **file**, **Hub**, **note**, or **app** for sharing. +* Set an embeddable element, such as a folder, file, hub, note, or app for sharing. * Have at least **Viewer** [permissions][5]. ## Using web app @@ -32,19 +32,23 @@ To fetch the Box Embed widget code from the Box web app, perform the following s ### Hubs -1. Navigate to the chosen Hub. -2. Click on the ellipsis menu in the top right corner. +1. Navigate to the chosen hub. +2. Click on the ellipsis menu in the upper-right corner. 3. Click **Embed Hub**. + +You can also embed only the AI chat interface from a hub. Users can ask questions and get AI-powered answers based on the hub's files, without accessing navigation or file browsing features. For more information, see the [Box Hubs AI Chat embedding][6] section. + + ### Notes -1. Navigate to the chosen Box Note. +1. Navigate to the chosen note. 2. Click on the ellipsis menu. 3. Click **Embed Box Note**. ### Apps -1. Navigate to the chosen Box App or Box App View. +1. Navigate to the chosen app or Box App View. 2. Click on the ellipsis menu. 3. Click **Embed**. @@ -54,9 +58,14 @@ To fetch the Box Embed widget code from the Box web app, perform the following s In the next step, configure the parameters of an embeddable element. -| Files | Folders | Hubs | Notes | Apps | -|----------|----------|------------------------| --- | --- | -| Size of the widget.| Size of the widget, sorting of the files in a folder, hiding the navigation path and sidebar. | Size of the widget, hiding the parent navigation path and sidebar. | Size of the widget, skipping cloud game (results in note being in read only mode), hiding notes navigation. | Size of the widget. | +| Element Type | Configuration Options | +|--------------|----------------------| +| Files | Size of the widget. | +| Folders | Size of the widget, sorting of the files in a folder, hiding the navigation path and sidebar. | +| Hubs | Size of the widget, hiding the parent navigation path and sidebar. | +| Hubs AI Chat | Chat mode: button or widget. | +| Notes | Size of the widget, skipping cloud game (results in note being in read only mode), hiding notes navigation. | +| Apps | Size of the widget. | ![Box Embed Configuration](./embed-configuration.png) @@ -75,7 +84,8 @@ If you want to customize Box Embed even further, you can do it programmatically. width="{pixels}" height="{pixels}" frameborder="0" - allow="local-network-access; clipboard-read; clipboard-write" + + allow="local-network-access *; clipboard-read *; clipboard-write *" allowfullscreen webkitallowfullscreen msallowfullscreen> @@ -132,8 +142,8 @@ You can also set the page to Root Folder/All Files page. Set the URL to Next, you will want to choose your view customization options. The following is a list of optional parameters you can configure. -| | | -| --------------------- | -------------------------------------------------------------------------------------------- | +| | | +| -- | -- | | `hideHubsGallery` | Hide or show navigation chevron button to go back to Hubs gallery. Can be `true` or `false` (default). | | `hideNavigationControls` | Hide or show navigation controls in Box Notes.| | `showItemFeedActions` | Hide or show file comments or tasks. Can be `true` (default) or `false`. | @@ -161,6 +171,133 @@ within an ` +``` + +#### Using the close button + +When embedding the Box AI chat directly with `iframe` (without using the provided script), you can enable a close button within the chat interface that communicates with your parent application through `postMessage`. + +##### Enabling the close button + +To display a close button (✕) in the corner of the iframe, add the `showCloseButton=true` query parameter to your `iframe` URL as follows: +`https://app.box.com/ai-chat?hubId=YOUR_HUB_ID&showCloseButton=true` + +##### How it works + +1. When `showCloseButton=true` is set, an X button appears in the corner of the chat iframe. +2. When a user clicks this button, the iframe sends a `postMessage` event to the parent window. +3. The event contains `event.data.type` set to `"BOX_AI_CHAT_CLOSE"`. +4. Your hosting application listens for this event and handles the closing logic. + +##### Implementation example + +```javascript +window.addEventListener('message', (event) => { + // Optional: validate origin is from Box for additional security + // if (event.origin !== 'https://app.box.com') return; + + if (event.data && event.data.type === 'BOX_AI_CHAT_CLOSE') { + closeChat(); + } +}); +``` + +##### Event reference + +| Property | Value | Description | +|----------|-------|-------------| +| `event.data.type` | `"BOX_AI_CHAT_CLOSE"` | Indicates the user clicked the close button in the chat iframe. | + ## Expiring embed links For files, another option is to call the [`GET /files/:id`][1] @@ -231,9 +368,9 @@ would look something like this. https://app.box.com/preview/expiring_embed/[HASH]?[parameterName]=true ``` -| | | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `showDownload` | Shows the download button in the embedded header bar if the viewer has permissions to download the file. Document file types will also show a print button since print and download are governed by the same permissions. Defaults to `false`. | +| | | +| --- | --- | +| `showDownload` | Shows the download button in the embedded header bar if the viewer has permissions to download the file. Document file types will also show a print button since print and download are governed by the same permissions. Defaults to `false`. | | `showAnnotations` | Enables users with permission Preview and above to annotate document and image previews. Also shows annotations that are already on the document. To learn more about the file types that annotations is available on as well as the types of annotations, you can refer to our Annotations page. Annotations are available today on web browsers only. On mobile browsers, users will be able to view annotations but not create new ones. | ## Cloud game @@ -278,3 +415,7 @@ and **print** options might not show in mobile browsers. [4]: e://put-folders-id--add-shared-link [5]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels [cloud-game]: https://support.box.com/hc/en-us/articles/360043691034-How-Does-Box-Prevent-Clickjacking +[6]: g://embed/box-embed/#box-hubs-ai-chat-embedding +[7]: g://embed/box-embed/#chat-button +[8]: g://embed/box-embed/#chat-widget +[9]: g://embed/box-embed/#using-the-close-button \ No newline at end of file diff --git a/content/guides/embed/chat-button.png b/content/guides/embed/chat-button.png new file mode 100644 index 000000000..56be2f22d Binary files /dev/null and b/content/guides/embed/chat-button.png differ diff --git a/content/guides/embed/chat-widget.png b/content/guides/embed/chat-widget.png new file mode 100644 index 000000000..cd4753af4 Binary files /dev/null and b/content/guides/embed/chat-widget.png differ