How to Embed a Widget in Confluence
Confluence Cloud includes an iframe macro that lets you embed any external URL as a live, interactive iframe directly in your pages. Paste your Embeddy widget URL into the macro and your widget appears inline — ideal for team wikis, project documentation, and internal dashboards.
On this page
Prerequisites
Before embedding, make sure you have the following ready:
- An Embeddy widget: Create one for free at embeddy.ai/dashboard. Your widget must be published (not in draft mode) so it is publicly accessible.
- Your Embed Link: In the Embeddy dashboard, open your widget and copy the Embed Link — the direct URL that looks like
https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID. - Confluence Cloud: You need edit permissions on the Confluence space and page. The iframe macro is available on all Confluence Cloud plans. Confluence Data Center / Server may require the HTML macro instead (see note below).
Where is my Embed Link? In the Embeddy dashboard, select your widget, click the Share / Embed panel, and look for the Embed Link option. It is the direct URL — not the <iframe> snippet.
Confluence Data Center / Server: The iframe macro is a Confluence Cloud feature. On Data Center or Server, you may need to use the HTML macro (if enabled by your admin) or a third-party iframe app from the Atlassian Marketplace.
Method 1: iframe Macro
Recommended — purpose-built for external content
The iframe macro is Confluence Cloud's dedicated tool for embedding external web pages inline. It accepts a URL and renders it as a live iframe within your Confluence page.
- 1
Open your Confluence page in edit mode
Navigate to the page where you want the widget and click Edit (the pencil icon), or create a new page.
- 2
Type
/iframeIn the editor body, type /iframe. A dropdown menu will appear — select iframe from the macro list. Alternatively, click the + toolbar button, search for "iframe", and insert it.
- 3
Paste your Embeddy widget URL
In the iframe macro configuration panel, paste your Embed Link into the URL field:
https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID
- 4
Set width and height
The iframe macro lets you specify width and height in pixels or percentages. For a responsive layout, set width to
100%and height to something like600(pixels). - 5
Publish the page
Click Publish (or Update for existing pages). The iframe macro renders as a placeholder in the editor — you will see the live widget on the published page.
Tip: The iframe macro shows a placeholder in the editor, not a live preview. This is normal Confluence behavior. Always publish or preview the page to see the actual widget rendering.
Method 2: Paste URL as Smart Link
Alternative — quick inline link or card
Confluence Cloud supports Smart Links — when you paste a URL in the editor, Confluence converts it into a rich preview card. While this does not create a full iframe embed, it provides a clickable card that opens the widget.
- 1
Open your Confluence page in edit mode
Navigate to the page and click Edit.
- 2
Paste the widget URL
Paste your Embeddy Embed Link on its own line. Confluence will show display options:
- →Inline — compact inline link with a small icon
- →Card — rich preview card with title and description
- →Embed — full inline iframe (if available for the URL)
- 3
Select "Embed" if available
If Confluence offers an Embed option for your URL, select it for an inline display. Otherwise, choose Card for a rich preview, or use Method 1 (iframe macro) for a guaranteed inline embed.
Note: Smart Link embed support depends on whether Confluence recognizes the URL provider. If the Embed option is not available for your Embeddy URL, use Method 1 (iframe macro) instead — it works reliably with any URL.
Configuration Options
The iframe macro provides several parameters to control how the embed appears on your page.
Width
Set to 100% for a responsive full-width embed, or specify a pixel value like 800. Full-width works best for most Embeddy widgets.
Height
Specify height in pixels, e.g., 600. There is no percentage option for height — it must be a fixed pixel value. Adjust based on your widget's content.
// Example iframe macro parameters
URL: https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID Width: 100% Height: 600
Editing the macro: To change parameters after inserting the macro, click the iframe placeholder in the editor and select Edit from the floating toolbar. Update the URL, width, or height and publish again.
Limitations
Confluence embeds are powerful but come with a few platform-level constraints:
Admin allowlist
Confluence Cloud admins can restrict which URLs are allowed in iframe macros. If your Embeddy URL is blocked, ask your Confluence admin to add embeddy.ai to the allowlist under Settings > Macro Security.
No live preview in editor
The iframe macro shows a placeholder block in the Confluence editor, not a live preview. You must publish or use the page preview to see the actual rendered widget. This is standard Confluence behavior for all macros.
Fixed height
The iframe macro requires a fixed pixel height — it does not support percentage-based height or auto-sizing. If your widget content is taller than the specified height, users will need to scroll inside the iframe.
Confluence mobile app
Iframe macros may not render in the Confluence mobile app. Users on mobile will see a fallback link instead. This is a Confluence platform limitation — the widget itself works fine on mobile browsers.
Troubleshooting
"This content is blocked" or blank iframe
This usually means the URL is not on your Confluence admin's allowlist:
- Ask your admin to add
https://embeddy.aito the iframe allowlist in Confluence settings. - Check the widget is published. Draft widgets return a 404 and will show a blank frame.
- Set visibility to Public. Widgets that require login will not load in Confluence's sandboxed iframe.
iframe macro not available
The iframe macro is a built-in Confluence Cloud feature. If you do not see it, your admin may have disabled it. Ask your Confluence admin to enable the iframe macro under Settings > Manage Macros. On Confluence Data Center, the HTML macro or a Marketplace app may be needed instead.
Widget appears too small
Edit the iframe macro and increase the width and height values. Set width to 100% for full-width, and increase the height to match your widget's content (e.g., 800).
Widget loads in editor preview but not on published page
This can happen if your browser has cached an older version of the page. Hard-refresh the published page (Ctrl+Shift+R or Cmd+Shift+R). If the issue persists, verify the URL and admin allowlist settings.
Still stuck? Reach out on Discord or contact support. Share your widget's Embed Link and a screenshot of your Confluence page and we will help you debug it.
FAQ
Does this work with Confluence Data Center or Server?
The iframe macro is a Confluence Cloud feature. On Data Center or Server, you will need to use the HTML macro (if your admin has enabled it) or install a third-party iframe app from the Atlassian Marketplace. The Embeddy URL itself works the same — only the embedding mechanism differs.
Can other team members see the embedded widget?
Yes. Anyone who has permission to view the Confluence page can see the embedded widget. The widget loads from Embeddy's servers, so it does not require viewers to have an Embeddy account — as long as the widget is set to Public.
Will the widget update automatically if I change it in Embeddy?
Yes. The iframe macro loads the live URL each time the page is viewed. Any changes you make to your widget in the Embeddy dashboard are reflected immediately on the Confluence page. You do not need to edit the macro or republish the page.
Ready to embed your widget?
Head to your Embeddy dashboard to create or find your widget, copy the Embed Link, and add it to any Confluence page using the iframe macro.