Install the widget
One script tag puts the chat on your site. What it does to your page, what it stores in the browser, and the options you can set on the tag.
The script tag
Open Deploy on your agent and copy the snippet under Chat widget. It looks like this, with your own address and agent id filled in:
<script src="https://YOUR-ADDRESS/w.js" data-agent="YOUR-AGENT-ID" async></script>
Paste it just before </body> on every page where the chat should appear. In most site builders that is a "custom code" or "footer code" box: once there, it is on every page.
That is all. A chat button appears in the bottom corner, and a click opens the conversation.
What it does to your page
- It is light. The script draws the button and nothing else. The chat itself is only loaded when a visitor opens it for the first time, so it costs your page speed next to nothing.
- It keeps to itself. Button and panel live in a sealed part of the page (a shadow root). Your stylesheet cannot break the widget, and the widget cannot touch your page.
- It sits on top, fixed in the bottom corner, above other elements. On a phone the panel takes nearly the whole screen.
- It respects the visitor. The Escape key closes it, and animations are off for visitors who have asked their device for reduced motion.
- Including the tag twice by accident does no harm. The second one notices the first and stops.
The page the visitor is on
Visitors often ask about what they are looking at: "is this one suitable outdoors?" on a product's page. So each time a visitor is about to ask, the script tells the agent the address of the page they are on. If the agent has read that page as a website source, it answers from that page first. How an answer is made.
- Only the address. Not the query string or the part after
#, where order numbers and reset links live, and not the title or anything else on the page. - A page the agent does not know is kept by its address, with anything that looks like a number, a code or an e-mail address in it replaced by
:id. Such an address is shown in Activity but not as a link, since it leads nowhere. A name written into an address, such as/team/jan-jansen, cannot be told from a product's and stays as it is. - It works on sites that change pages without reloading, since the address is asked for at the moment of asking.
- The iframe snippet below cannot do this. It has no script on your page to ask.
You can see the page next to each question in Activity, and try it out in the Playground.
Options on the tag
| Attribute | What it does |
|---|---|
data-agent | Which agent. Required. |
data-locale | The widget's language on this page: en, nl, fr, de or es. Without it, the agent's own language is used. See Languages. |
data-side | left puts the button on the left of this page, whatever the agent's setting says. |
data-color | A hex colour such as #0f766e for the button on this page, whatever the agent's setting says. |
data-consent | true on a site that loads the script only once the visitor has accepted its cookies. It lets the second nudge count pages. |
Everything else (colours, logo, texts, icon) is set once under Appearance and applies everywhere. A change there can take up to five minutes to reach a visitor's button, because browsers keep the settings for that long.
The iframe alternative
Under Inline iframe is a second snippet. It places the conversation in your page, as a block of 384 by 560 pixels, with no button. Use it for a dedicated help or contact page. The rest of this page applies to it as well, except that it cannot tell the agent which page the visitor is on.
What is stored in the visitor's browser
The widget sets no cookies, and without your site's consent it stores nothing until the visitor sends a message or a file. Then it keeps two small values in the browser's own storage:
| What | Why | How long |
|---|---|---|
| A random visitor number | So that one visit's messages and files stay together, and can be told apart from other visits in your Activity | Until the tab is closed |
| The number of the current conversation | So that a reload, or a click to another page, continues the same conversation | Until the tab is closed |
Neither contains anything about the person. If a browser blocks this storage, the chat works anyway, and only the memory between pages is lost.
On a site that passes the visitor's consent, and only while its greeting or second nudge is on, the button keeps one more value for the length of the visit, before the visitor has used the chat: when the visit began, how many pages were seen and which message was shown.
A visitor who comes back the next day starts a new conversation. That is deliberate: a thread that grows for weeks helps nobody. The restart button in the chat's header does the same at once. It clears the visitor's screen and nothing else: the conversation stays in your Activity.
Limits that protect you
- A visitor can send 20 messages per 60 seconds. Beyond that the chat says so and asks them to wait a few seconds. No person types that fast, and it stops a script from emptying your credits.
- A message can be 4,000 characters long.
- Only the sites you list may show your agent. Set this up: Allowed domains.
If your site has a Content Security Policy
Most sites have none, and then there is nothing to do. If yours sends a Content-Security-Policy header, allow the address in your snippet in four places: script-src (the script), frame-src (the chat), connect-src (the button's settings) and img-src (your button image, if you use one). The button's own styling is a style element the script adds, so a style-src without 'unsafe-inline' leaves the button unstyled.
If the button does not appear
See Troubleshooting.