Question 1

Where do I find the widget token?

Accepted Answer

Only on Dashboard → Chatbots → your chatbot → Integrations → Web widget. It is not on the chatbot list, not on the Playground, and not in any export.

Question 2

Can I put the token in the script URL instead of an attribute?

Accepted Answer

No. The loader boots from the data attribute and ignores a token in the URL. An attribute also keeps the token out of referrer headers, proxy logs, and analytics.

Question 3

Can I host the widget script on my own server?

Accepted Answer

It is unsupported. You lose automatic updates and end up debugging a version from months ago. Load it from the address the dashboard gives you.

Question 4

Why are there two chat bubbles on my page?

Accepted Answer

The snippet is on the page twice, usually once in the theme header and once in a page-level block. Remove one, and in a single-page app call AgentencyWidget.destroyAll() when leaving the route that had the chat.

Question 5

How do I know it really worked?

Accepted Answer

Open your live site in a private window, send a real question, then check the chatbot's Conversations tab for a thread with the channel recorded as Website widget.

Question 6

Do chats from the widget create customer records automatically?

Accepted Answer

No. A visitor who chats anonymously produces a conversation but no contact. Turn on lead capture for that chatbot, or pass your own visitor identity, before anyone appears under Customers.

Question 7

What happens if I clear the list in production?

Accepted Answer

The widget is blocked on every origin until you add at least one valid host. An empty list means not configured, never allow everyone.

Question 8

Does the hosted page need this list?

Accepted Answer

No. The hosted /agent/{handle} page is served by Agentency, uses no widget token, and needs no allowlist. The iframe embed of it is likewise unaffected.

Question 9

Should I use a wildcard or exact hostnames?

Accepted Answer

Exact hosts when you have two or three that rarely change. A wildcard like *.example.com when you have many subdomains and the whole domain is yours and trusted.

Question 10

It works on example.com but not www.example.com.

Accepted Answer

Those are different hosts to a browser. Add both, or use *.example.com to cover them together.

Question 11

What is a valid entry?

Accepted Answer

A bare hostname with no scheme, path, or port — example.com, shop.example.com, *.example.com, localhost, or a plain IPv4 address. A bare * is rejected.

Question 12

Does this sign the visitor into anything?

Accepted Answer

No. It only labels the conversation. Restricting who can open the hosted page is a separate feature in the Direct link access settings.

Question 13

Will the chatbot use the name in its answers?

Accepted Answer

No. Visitor identity is not sent to the model, so the chatbot does not know the name and will not greet anyone by it. It is for your dashboard and CRM.

Question 14

Every conversation shows the same person. Why?

Accepted Answer

The snippet ships with template placeholders and someone hardcoded one id. Your server has to print the current user's values per request.

Question 15

My single-page app misses the first conversation.

Accepted Answer

The identify call runs after the visitor has already sent a message. Call it as soon as your own session resolves — it is safe before the chat has finished mounting.

Question 16

What is the payoff once identity is flowing?

Accepted Answer

Clicking a visitor cell filters the list to every conversation that person has had, there is a visitor filter in the filter bar, and people flow into the Customers list.

Question 17

Does the iframe need allowed domains?

Accepted Answer

No. The allowlist applies to the script widget only. The hosted page is served by Agentency itself, so there is nothing to lock down per-website.

Question 18

Can I name the visitor in an iframe?

Accepted Answer

Yes — the details go in the address instead of an attribute. Keep an existing share secret in the URL, and keep sensitive values out of it since addresses are widely logged.

Question 19

Why can I only frame the /agent page?

Accepted Answer

Pointing an iframe at any other page of the product is blocked by the browser for security. Keep the address exactly as the dashboard generated it.

Question 20

My old /bot/ links changed in the address bar.

Accepted Answer

Expected. Legacy /bot/{id} addresses permanently redirect to the current /agent form, so existing embeds and shared links keep working.

Question 21

Visitors are asked to unlock the chat inside my iframe.

Accepted Answer

The hosted page has access protection turned on — a secret, a password, or an accounts restriction. Change it in the Direct link settings, or use the script widget instead.

Question 22

Should I save defaults or bake settings into the snippet?

Accepted Answer

Save as default when every embed should match — the live widget picks it up without re-pasting. Bake them into a snippet only to override the default on one page.

Question 23

Why does auto-open do nothing on phones?

Accepted Answer

Auto-open is desktop-only by default, because a chat window covers a phone screen entirely and reads as an ad. There is a separate switch if you want it anyway.

Question 24

The bubble covers my Buy button. What do I change?

Accepted Answer

Switch the launcher corner, or raise the offset — up to 200 pixels from the anchored corner. Around 60 to 80 pixels usually clears a standard cookie banner.

Question 25

Can I hide the bubble and open chat from my own button?

Accepted Answer

Yes. Hide the launcher, then add data-agentency-open to any element on your page, or call AgentencyWidget.open() from your own code. The Control the widget from your code article lists every method and event.

Question 26

I changed the colours and the snippet looks identical.

Accepted Answer

Correct — brand colours are not in the snippet. The widget fetches them from the chatbot at load time, so hard-refresh your site rather than re-pasting.

Question 27

It works in Test Chatbot but not on my site.

Accepted Answer

Expected. Test Chatbot is the owner's private door and bypasses the plan gate, the widget token, and the allowlist. Fix the live script attributes and the allowed domains.

Question 28

The script is on the page and still nothing happens.

Accepted Answer

Allowed domains in production, nine times out of ten. Add the exact hostname visitors use, including www, save, and hard-refresh.

Question 29

Will a content blocker hide the widget?

Accepted Answer

Sometimes. Test in a private window with extensions disabled — but only after you have confirmed the plan, activation, snippet, and allowlist.

Question 30

It worked yesterday and stopped today.

Accepted Answer

Ask what changed: a site deploy that dropped the snippet, a new domain, a plan downgrade, or exhausted message credits. Check the credits meter first.

Question 31

Does a messaging channel showing as unavailable break the widget?

Accepted Answer

No. Messaging apps are a different tab entirely and have no bearing on the website bubble.

Question 32

Should the campaign reuse my support chatbot or get its own?

Accepted Answer

Reuse it when the same knowledge answers both. Create a dedicated one when the campaign has its own offer, needs separate reporting, or wants a more sales-oriented tone.

Question 33

The bubble shows on my app but not the campaign domain.

Accepted Answer

Allowed domains is per host, and a wildcard covers subdomains of one domain only. Add the campaign hostname as its own entry and save.

Question 34

My page builder saved the snippet but nothing renders.

Accepted Answer

It probably stripped the tag. View the live page source and search for the widget script; if it is missing, use the iframe embed or a link to the hosted page instead.

Question 35

Can I use the hosted link on a landing page instead?

Accepted Answer

Yes. A button pointing at the hosted page works on every plan, including Free, and you can frame that page by hand. You lose the corner bubble and the auto-open behaviour.

Question 36

Are people chatting on Agentency's own site my leads?

Accepted Answer

No. That bubble is Agentency's Help Assistant, answering from the Help Center, and those conversations land in Agentency's dashboard rather than yours.

Question 37

Why is AgentencyWidget undefined in my script?

Accepted Answer

The widget script is deferred, so an inline script placed after it runs first. Put your calls in a click handler, an agentency:ready listener, or AgentencyWidget.ready(callback). Listening with window.addEventListener("agentency:…") is safe anywhere.

Question 38

Can I open the chat with a question already sent?

Accepted Answer

Yes. Call AgentencyWidget.sendMessage("your question") — it opens the chat and sends the text as if the visitor typed it. Without code, add data-agentency-open and data-agentency-message="your question" to any button.

Question 39

How do I know when the visitor closes the chat?

Accepted Answer

Listen for the close event: window.addEventListener("agentency:close", handler) works from anywhere on the page, and AgentencyWidget.on("close", handler) works once the widget has loaded. It fires only on a real open-to-closed change.

Question 40

Does sending a message from code cost credits?

Accepted Answer

Yes. sendMessage() and a data-agentency-message button go through the same path as a typed message, so each one spends message credits at the chatbot's model rate and counts toward the widget rate limits. prefill() only fills the composer and costs nothing until the visitor sends.

Question 41

Do I need JavaScript to make my own button open the chat?

Accepted Answer

No. Add data-agentency-open to any element and it opens the chat; data-agentency-toggle and data-agentency-close work the same way. Elements your framework adds after page load are picked up too.

Question 42

Can the chatbot know which page the visitor is on?

Accepted Answer

Yes, with page context. Call AgentencyWidget.setPageContext({ title, url, text }) from your code, or add data-page-context="auto" to the script tag so the widget reads the page title, address (never the query string or hash), meta description, first heading and an excerpt of the main content at send time — navigation, header, footer, sidebar and hidden content are skipped. The chatbot uses it only when a question refers to the page, answers still come from your knowledge base, and the page text is visible only to the account that owns the chatbot. The owner can turn it off, keep it manual (the default) or set it to auto in the Website embed settings. Never put personal data or secrets in it.

Website widget FAQ