Install guide
Adding a chat assistant to HubSpot pages
HubSpot has a field for footer markup in the website settings, which makes the install a paste and a save. Two things make it less predictable than that sounds: the field is set per domain rather than per account, and a consent banner can hold the script until a visitor opts in.
The tag
<script src="https://cdn.askably.xyz/w.js" data-key="pk_live_YOUR_KEY" defer></script>Your own key replaces the placeholder. You will find it on the install tab of the assistant.
The origin the page is served from has to be on the allowlist for that assistant, or nothing renders and the browser console says which origin was refused. An apex domain and its www are two different origins to a browser, so list both, along with any staging or preview host you want it to work on.
Where it goes on HubSpot
Settings, then Website, then Pages, then the templates tab, and the site footer HTML field. Per page footer HTML lives in a page's advanced settings.
Available wherever you host pages with HubSpot and have permission to edit website settings. A user without that permission can still add footer HTML to a single page they own, which is a reasonable way to trial it on one page.
Step by step
- 1In settings open the website pages area, then the templates tab.
- 2Check the domain selector at the top of that screen before you paste anything. The footer HTML is stored per domain, so on a multi-domain account you are editing one site and not all of them.
- 3Paste the tag into the site footer HTML field. HubSpot places it before the closing body tag on the pages served from that domain.
- 4Save. There is no separate publish step for this setting, though pages that were already built may need republishing before they pick it up.
- 5If you only want it on one page, skip the settings field and use that page's advanced settings footer HTML instead. Do not use both for the same page: the loader refuses a second install, so the extra copy does nothing but confuse the next person who reads the source.
- 6Open the live page rather than a preview, and confirm the launcher. If your account shows a cookie banner, test once before consenting and once after.
What goes wrong on HubSpot
The consent banner can hold the script back
HubSpot's own cookie banner sorts scripts into consent categories, and in an opt-in configuration nothing outside the strictly necessary category runs until the visitor accepts. The result is a launcher that appears for you, because you accepted weeks ago, and never appears for a first-time visitor in a region where the banner defaults to opt-in.
This is a policy decision rather than a bug, so make it deliberately: check which category the footer script falls under in your banner settings, and decide whether an assistant that answers questions belongs there. Whatever you choose, test in a private window before accepting the banner, because that is the state most of your visitors are in.
The preview address and the live domain are different origins
HubSpot serves pages on an hs-sites.com address before a domain is connected, and continues to use it for previews afterwards. A browser treats that address and your domain as unrelated origins, so a page that works when published shows nothing in preview, with the refused origin named in the console.
Add the preview address to the allowlist if you review work there. Remember it is not an address a customer ever sees, so there is no harm in leaving it off once you have finished building.
A coded template that omits the standard footer includes never prints it
The site footer HTML field is emitted by the standard footer includes call in the template. Templates built in the drag and drop editor always have it. A hand-coded template written by an agency sometimes does not, particularly if it was trimmed for speed.
The symptom is a saved field and a page source with no trace of the tag on some templates while other pages on the same domain are fine. Add the includes call to the template, or put the tag directly into that template before the closing body tag.
Origins to allowlist
These are the origins a HubSpot site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.
- https://yourdomain.com
- https://www.yourdomain.com
- https://12345678.hs-sites.com
How the tag behaves, wherever you put it
The rest of this is the same on every platform, so it is worth reading once rather than on each guide.
| One tag, nothing else | There is no second file, no stylesheet and no package to install. The tag is the whole install. |
|---|---|
| Where it goes | Immediately before the closing body tag. It works in the head too, because it defers, but the body keeps it out of the way of anything that measures render order. |
| data-key is required | Without it the loader stops and writes a warning to the browser console rather than rendering anything. |
| It finds itself | The loader reads the tag it was loaded from, and falls back to the first tag on the page carrying a data-key. Platforms that move or re-inject the tag do not break it. |
| It installs once | A second copy of the tag on the same page is ignored, so a template that renders twice does not produce two launchers. |
| Assets follow the tag | Everything else it needs is fetched from the same origin the tag was served from, so a proxy or a private domain needs no extra configuration. |
| The panel loads late | Only the small launcher is on the page at first. The conversation panel is fetched the first time a visitor opens it, in its own frame. |
| Styles cannot collide | The launcher renders inside a closed shadow root and the panel inside a frame, so nothing on the host page can restyle either, and neither can restyle the host page. |
Set up on HubSpot for a particular trade
The tag is the same everywhere. What is not the same is which of your pages the assistant can read once it is running, and on HubSpot that depends on what kind of site this is. These go one level further than this guide.
- For a recruitment agencyThe footer field covers HubSpot domains only, so the job board on your ATS subdomain is out of reach. What the assistant answers instead.
- For a marketing agencyOne portal, several client domains, a footer field stored per domain. Where the tag goes, and why the gated case studies stay unread.
Taking it off again
Clear the site footer HTML field for that domain and save, then remove any per page footer HTML you added while testing. Republish pages that were built before the change if they still show the old markup.
Before you remove it
- Removing the tag stops the widget on that site. It does not delete the assistant, its material, or the enquiries it has already collected.
- If you are moving the widget to a different host rather than retiring it, add the new origin to the allowlist before you remove the old tag, or there is a window where neither works.
Questions
- Why do only some visitors see it?
- Almost always the consent banner. In an opt-in configuration the script is held until the visitor accepts, so it is present for anyone who consented and absent for everyone else. Check which consent category your footer scripts sit in, then test in a private window before accepting.
- Site footer HTML or a single page's footer HTML?
- The settings field for anything you want on the whole site, because you set it once per domain and new pages inherit it. The per page field is for a genuine one-off, such as trialling it on one landing page before rolling it out.
- Why is nothing showing on my hs-sites.com preview?
- That preview address is a different origin from your live domain, so the allowlist refuses it and the browser console names it. Add it if you want previews to work.
- Does it appear on blog posts as well as pages?
- It appears on anything served from that domain by a template that includes the standard footer includes, blog listings and posts included. If posts are missing it and pages are not, compare the two templates before changing anything in settings.
Keep reading
- Install on WordPressA code snippets plugin, or a small plugin of your own, hooking wp_footer. Not Appearance, then the theme file editor.
- Install on GhostSettings, then Code injection, then the Site Footer box. The alternative is default.hbs in a custom theme.
- Install on DrupalA small custom module attaching a library, an asset injection contributed module, or html.html.twig in a custom theme. Not a custom block.
- Every install guideThe same one line of HTML, and where it goes on each platform.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.