Add the chat to a Magento store

What it is

Magento Open Source and Adobe Commerce build every page from theme templates. The head of the page comes from a template file called head.phtml, and adding the Agentency <script> tag there puts the chat bubble on every page of the store. After saving you flush the Magento cache so the new head is served.

This is the one platform in the list where you will probably want your developer or agency to do the paste. It involves a file on the server, not a box in an admin screen.

When you would use it

Use this for a self-hosted Magento 2 or Adobe Commerce store. If your store still runs Magento 1, the file layout is different and this guide does not apply — ask your developer to place the same tag in the head of your theme.

If nobody on your team has server access, there is a route that needs none: put a "Chat with us" link in your store's footer or a CMS block pointing at your hosted chatbot page.

Where to find it

Open Dashboard → Chatbots → your chatbot → Integrations → Plugins → Magento.

Before you start

• You need file access to the Magento installation and the ability to run bin/magento commands, or someone who does.
• Work in a custom or child theme, never in a core Magento theme. An upgrade overwrites core theme files and takes your snippet with it.
• Add your storefront domain — and the secondary domain if your store runs a separate secure host — to the widget allowlist. See Allow the widget on your domains.
• Confirm the chatbot is Active on its Playground tab.

Steps

1. Open Dashboard → Chatbots → your chatbot → Integrations → Plugins and click the Magento card.
2. Click Copy template code.
3. On the server, navigate to your theme's template directory.
4. Open (or create, by copying from the parent theme) the head.phtml template in your theme.
5. Paste the snippet so it sits before the closing </head> tag.
6. Save the file.
7. Flush the cache so the new head template is served: php bin/magento cache:flush. Reindex as well if your deployment normally requires it.
8. If you are in production mode, redeploy static content the way your team normally does.
9. Open a product page on the live storefront and send a test message. Confirm it lands in Conversations.

What the snippet looks like

This is what the Plugins drawer gives you for Magento — the widget tag with a comment naming its destination. Copy your own; the token here is a placeholder:

<!-- Add this to your Magento theme's head.phtml file -->
<script src="https://agentency.com/js/chatbot-widget.js" defer data-widget-token="wt_YOUR_WIDGET_TOKEN" data-api-base-url="https://api.agentency.com" referrerpolicy="strict-origin-when-cross-origin" crossorigin="anonymous"></script>

If your team prefers to add head assets through layout XML rather than by editing a template, that works equally well — the requirement is only that this exact tag, with data-widget-token intact, ends up in the page head.

What you will see

Nothing changes in the Magento admin; this is a file-level change. On the storefront, the bubble appears in the corner your chatbot's appearance settings specify, on category, product, cart, and CMS pages alike.

Because the tag is in the theme, it also loads for logged-in customers and on the checkout, unless your checkout runs on a separate theme.

Limits and plan notes

Embedding requires a paid Agentency plan. Free is hosted-link only — see Which plans include integrations and the pricing page.

The snippet does not read Magento's catalogue, customer accounts, or orders. Two things that often get confused: the chatbot can be taught about your products by adding knowledge or crawling your storefront, which gives it a good but static picture; and it can look something up live through a Call action pointing at your own endpoint. Neither happens automatically by pasting this tag.

Common problems

I saved the file and the storefront is unchanged.

The cache is still serving the old head. Run php bin/magento cache:flush, and in production mode redeploy static content.

The change disappeared after an upgrade.

The snippet went into a core theme rather than your own child theme. Redo it in the child theme.

The widget loads on the storefront but not on checkout.

Your checkout may use a different theme or a separate host. Check both, and add the checkout host to the allowlist.

Chat is blocked with a security error.

If your store sends a Content Security Policy, the Agentency script and API host must be allowed by it. Your developer adds them to the policy's script and connect rules. See The widget is blocked.

Two bubbles appear.

The tag is in both a parent and a child template, or in layout XML and a template. Remove one.