Iframe embed and direct link

What it is

Two ways to publish a chatbot that do not use the script widget, both pointing at the same thing — your chatbot's hosted page at /agent/{handle}.

• Direct link. The hosted page opened as a normal URL. Send it in an email, put it behind a button, print it as a QR code.
• Iframe embed. The same hosted page inside a frame on your own site, so it renders as a panel rather than a floating bubble.

Neither uses the widget token, and neither is subject to the allowed-domains list — the page is served by Agentency itself, so there is nothing to lock down per-website. That has a very practical consequence: the Direct link works on the Free plan, where the script widget does not.

The handle is your chatbot's custom slug, or its numeric id if you have not set one.

When you would use it

Use the Direct link when:

• You are on Free and want a real, shareable chatbot today.
• The chat is the destination, not an add-on to a page — a support URL, an event QR code, a link in a signature.
• You want to share it somewhere you cannot inject scripts at all.

Use the iframe when:

• Your site builder allows custom HTML but not a <script> tag.
• You want the chat as a fixed panel in a page section rather than a corner bubble.

Use the script widget instead when you want the corner bubble, the visitor to stay on your page, or the finer control over launcher position, auto-open, and inline mounting. See Embed the website widget and Hosted page vs. widget.

Where to find it

• Iframe: Dashboard → Chatbots → your chatbot → Integrations → Web widget, in the iframe card.
• Direct link: Dashboard → Chatbots → your chatbot → Integrations → Messaging → Direct link. Always visible, on every plan.

Steps

The Direct link

1. Open Integrations → Messaging and open Direct link.
2. Copy the /agent/{handle} URL.
3. Optionally set access protection in that drawer — public, a secret link, a password, or restricted to accounts. See Hosted page access control.
4. Test it in a private window. A draft or paused chatbot shows a not-found screen, not a chat box.
5. Share it. See Share a hosted link.

The iframe

1. Open Integrations → Web widget and open the iframe card.
2. Copy the snippet. It is a plain <iframe> pointed at your /agent/{handle} page, 400 by 600 pixels by default, with an accessible title already filled in.
3. Paste it wherever your builder allows custom HTML.
4. Adjust the width and height to fit your layout — a wider, taller frame is usually better on desktop, and full width on mobile.
5. Keep the address exactly as generated. Only the /agent page can be framed on another site; pointing an iframe at any other page of the product is blocked by the browser for security. Do not aim it at your dashboard.
6. Publish and test in a private window.

Things that catch people out

Renaming the chatbot breaks both. The handle is derived from the chatbot's name, so a rename regenerates it and every published link and embedded iframe stops resolving. Recopy and update them. If you want a public address that does not follow the display name, set a custom handle instead — see Hosted page handle.

Access protection applies inside the frame too. If the hosted page is protected by a secret, a password, or an accounts restriction, visitors are asked to unlock it inside the iframe before they can chat. The dashboard warns you about this on the iframe card when protection is on. That is often not what you want on a public marketing page — either make the page public or use the script widget.

Old /bot/{id} addresses still work. They permanently redirect to /agent/{id}, so existing embeds, iframes, and shared links keep working. Update printed material when convenient rather than urgently. See Legacy bot URLs.

An iframe is a separate page. It cannot follow your site's scroll, it does not inherit your CSS, and it cannot be repositioned by your page's JavaScript. If you need any of that, you want the inline container option on the script widget instead — see Embed the website widget.

Naming the visitor

Both routes support identifying who is chatting, but the iframe does it differently from the script widget: an iframe has no tag to hang attributes on, so the details go in the address as uid and uname parameters instead.

Keep sensitive details out of that address — URLs are recorded by browsers, proxies, and analytics tools. If the page already carries a share secret, keep it; the parameters are appended without replacing it. See Name visitors on the widget.

What you will see

The iframe card gives a 400×600 frame pointed at your hosted page, plus notes about keeping the address exact, what happens if you rename the handle, and how access control affects it. The Direct link drawer on the Messaging tab shows a copyable URL, an open-in-new-tab control, and the access settings.

Limits and plan notes

Direct link is available on every plan, including Free. The iframe card lives on the Web widget tab and is part of the integrations feature set, so it needs a paid plan — but the underlying hosted page it frames is public on any plan, which means a Free workspace can always link to it or wrap it in an iframe by hand.

Draft and inactive chatbots return a not-found screen on the hosted page, whether opened directly or inside a frame.

Every visitor turn spends message credits at the chatbot's live model rate, whichever route they arrive through.

Common problems

The iframe is blank or the browser blocked it.

Confirm the address is your /agent/{handle} page on the Agentency site, the chatbot is active, and your site builder is not stripping iframes from the saved HTML. Pointing the frame anywhere other than the /agent page is blocked deliberately.

The frame asks visitors to unlock the chat.

The hosted page has access protection turned on. Change it in the Direct link settings, or accept the unlock step.

I shared /bot/123 and the address changed in the browser.

Expected. Legacy addresses permanently redirect to the current /agent form.

The link says the chatbot was not found.

It is draft or inactive, or the handle changed after a rename. See Hosted page 404.

The iframe is too small on mobile.

The 400×600 default is a starting point. Set a responsive width and a taller height in your own CSS.

Can I use the Direct link on a landing page instead of the widget?

Yes — a button or a framed embed both work and both are available on Free. You lose the corner bubble and the auto-open behaviour. See Put the widget on a landing page.