Problem Statement
The iFrame app is a ticket sidebar application that provides embedded access to external web content directly within the ticket context. It dynamically renders a configurable URL inside the sidebar, allowing agents to interact with external tools and workflows without leaving the ticket view.
Location: nav bar.
Prompt
Create a nav_bar app called "Iframe" that embeds an admin-configured external website inside Zendesk Support, allowing agents to quickly navigate to an external resource and return to their tickets without interrupting their workflow.
- The app requires one install-time setting: **Iframe URL** (parameter name `iframeURL`, type: url, required). This is the external website address the admin enters during installation.
- On load, retrieve the setting by calling `const metadata = await zafClient.metadata()` and reading `metadata.settings.iframeURL`. Do NOT use `zafClient.get('setting.iframeURL')` — that is not a valid ZAF path and will throw an APIUnavailable error. The `metadata()` method is the only correct way to access install-time app settings.
- Render the external website inside the app's iframe by setting the iframe `src` to the admin-configured URL. The entire app UI is the embedded website — there are no app-chrome elements, headers, buttons, or controls of your own. The app is a full-bleed iframe that fills the entire nav_bar panel.
- When constructing the iframe URL, merge any query parameters from the current page's URL with the query parameters from the configured URL. This preserves ZAF SDK query parameters (like `origin`, `app_guid`) so the embedded website can use the ZAF SDK if needed. Concatenate both sets of query parameters, keeping the configured URL's protocol, host, pathname, and hash intact.
- If the configured URL does not start with `http:` or `https:`, prepend `http://` to it before processing.
- The visual layout is zero-chrome: no app header, no padding, no borders. The iframe should take 100% width and 100% height of the available nav_bar panel space. From the screenshot, the embedded website (Wikipedia in the example) fills the entire panel edge-to-edge below the app title bar that Zendesk provides automatically.
- Note: The original BBZ app had a background location that customised the nav_bar icon — either using a Zendesk Garden SVG icon name (wrapped in colons like `:icon-name:`) or the first two characters of a text string. App Builder does not support background locations or custom nav_bar icon configuration. The icon will use App Builder's default. If custom icon branding is critical, inform the admin this cannot be replicated.
- Note: The original app had a "ZAF SDK Support" toggle that controlled whether ZAF query parameters were forwarded to the embedded URL. In this recipe, always forward them — this is harmless for sites that don't use ZAF and required for sites that do.
Enhancement Options
Based on your organizational needs, you can extend the iFrame app to support your specific needs using App Builder.
Important Note: This app recipe is for the iFrame app. Any modifications to the recipe or its underlying logic may alter the core functionality of the app. Thoroughly test all changes in a non-production environment before deploying to your production workspace.
Please note: that as App Builder evolves including updates to underlying AI models, design components, and other dependencies, we cannot guarantee that this recipe will continue to function as expected over time. We recommend periodically validating the recipe against any platform updates.