Embed your agent anywhere

About 5 minutesCopy one line of codeUpdated July 2026

One script tag puts your agent's chat bubble or voice orb on any website — no framework required. This page gives you the snippet, then shows exactly where to paste it on the most common site builders.

Before you start, make sure you have:

A widget and its full token — create one under Deploy and copy the secret token from the one-time dialog shown at creation; see the web widget guide for the full flow

A way to edit your site's HTML, or a custom-code box in your site builder

Note:

these are generic placements that work because the widget is plain JavaScript — there is no Qalyb app to install from a marketplace. If you can edit a page's HTML or add a custom-code block, you can embed the widget.

The one line of code

Add this one tag anywhere before the closing </body> tag. It loads from cdn.qalyb.ai, reads its configuration from the data-qalyb-token attribute, and starts itself — no extra code to call. Your agent appears automatically: a chat bubble for a Chat Widget, a voice orb for a Voice Widget.

index.html · html

<script
  src="https://cdn.qalyb.ai/widget.js"
  data-qalyb-token="wgt_yourfulltoken"
  async
></script>

Swap in your real token:

the snippet on the widget's Embed tab contains only the token prefix as a placeholder — after creation, the full token is never shown again. Always replace it with the full wgt_... token you saved when you created the widget, or the widget won't connect.

Tip:

the async attribute keeps the script out of your page's critical path, so it never slows your content down. The widget appears as soon as the loader finishes downloading in the background.

That's the entire integration. Everything else — appearance, launcher, position, welcome message, allowed domains — is set in the dashboard and read live by the script, so you never touch the snippet again. The sections below only differ in where you paste it.

Screenshot: the Embed tab on a widget detail page showing the Script Tag, JavaScript API, and React Component snippets with copy buttons — Grab the ready-made snippet from the widget's Embed tab, then swap in your full token.

Plain HTML

For a hand-built or statically generated site, open the HTML file (or layout template) for every page that should show the widget and paste the snippet just before </body>.

layout.html · html

<!-- Paste just before the closing </body> tag -->
<script
  src="https://cdn.qalyb.ai/widget.js"
  data-qalyb-token="wgt_yourfulltoken"
  async
></script>

If your site uses a shared footer or a base template, paste it there once and the widget appears site-wide. To show it on only some pages, paste it into just those templates instead.

WordPress

Open your theme footer or a code plugin

For most themes, go to Appearance → Theme File Editor and open footer.php. If your theme has no editable footer, install a snippet plugin such as WPCode or Insert Headers and Footers — it gives you a safe place to add custom code without editing PHP.

Paste the snippet before the closing body tag

Drop the script tag immediately before </body> — or into the plugin's "Footer" / "Before </body>" box.

Save and reload

Save the file or publish the snippet, then open your site in a fresh tab. The launcher should appear in the corner you configured.

Heads up:

edits to footer.php are overwritten when the theme updates. Prefer a child theme or a headers-and-footers plugin so your snippet survives upgrades.

Wix

Open the custom-code panel

In the Wix Editor, go to Settings → Custom Code (under Advanced), then click + Add Custom Code.

Paste the snippet and set placement

Paste the script tag, choose to load it on All pages, and set Place Code in to Body - end.

Apply and publish

Apply the code, then Publish your site. Custom code doesn't run in the editor preview — open the live, published URL to see the widget.

Webflow

Open project or page settings

For a site-wide widget, go to Project Settings → Custom Code. For a single page, open that page's settings and use its Custom Code section instead.

Paste into the Before </body> tag field

Paste the script tag into the Before </body> tag box (not the head field).

Save and publish

Save, then Publish to your .webflow.io domain or custom domain. Custom code only runs on the published site, not the Designer canvas.

Framer

Open site settings

In Framer, open Site Settings → General and find the Custom Code section.

Paste into End of body

Paste the script tag into the End of <body> tag field, then save.

Publish

Click Publish. Custom code runs only on the published site, so verify on the live URL rather than the preview.

Shopify

Open your theme code

From your Shopify admin, go to Online Store → Themes, then click Actions → Edit code on your live theme.

Edit theme.liquid

Under Layout, open theme.liquid and paste the script tag just before the closing </body> tag so it loads on every storefront page.

Save

Save the file and open your storefront. Because theme.liquid wraps every page, the widget now appears across the whole store.

Tip:

on themes that support app embeds or a theme "custom code" block, paste the snippet there instead of editing theme.liquid — it survives theme updates more cleanly.

Keep it on your own domains

Pasting the snippet on a page does not, by itself, authorize it. If you set Allowed Domains on the widget, Qalyb checks where each request comes from and refuses to load on any site that isn't on the list. Add every domain and subdomain you embed on (for example example.com and shop.example.com); leave the list empty to allow any site. Manage this on the widget's settings — see the web widget guide.

Important:

publishing a widget counts against your plan's channel and deployed-agent limits. On the Free plan an agent can't be deployed to a live channel at all (playground-only), so the widget won't connect until you upgrade.

Check that it worked

After pasting and publishing, load your site in a clean browser tab (or a private window, to avoid cached scripts):

The launcher should appear in the position you configured — by default, bottom right.
Click it to open the panel. A Chat Widget shows the chat bubble; a Voice Widget opens the voice orb.
If nothing appears, open your browser's developer console and check for a blocked request to cdn.qalyb.ai/widget.js or an Origin not allowed error — the latter means the page's domain is missing from your Allowed Domains list.

For every data-qalyb-* attribute, the JavaScript API, and the React component, see the embed script reference.

Was this guide helpful?

← Previous

Share links

Brand & appearance