Install guide
Installing a chat assistant on a Zendesk help centre
Guide keeps the theme in the admin rather than in a repository, so the install is a few clicks and one paste. The part that needs a decision rather than a click is your access settings, because an assistant can only learn from articles a signed out visitor is allowed to open.
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 Zendesk Guide
Guide admin, then Customize design, then Edit code on your live theme, then footer.hbs.
Any Guide help centre where you can edit theme code. Editing and publishing a theme is an administrator level action, and a plan that restricts theme customisation restricts this along with it.
Step by step
- 1Open Guide admin and choose Customize design.
- 2On the live theme choose Edit code. Duplicate the theme first if you want something to fall back to, because editing the live theme edits what visitors are seeing right now.
- 3Open footer.hbs from the template list. It renders at the end of the document on every help centre page.
- 4Paste the tag on its own line at the end of that template. Handlebars acts only on its own brace delimiters, so plain markup passes through exactly as written.
- 5Save, then publish the theme. Saving updates the working copy only, and until you publish, visitors keep getting the previous version.
- 6Open the help centre in a private window while signed out and confirm the launcher appears there, not just for you.
What goes wrong on Zendesk Guide
A restricted help centre hides its articles from the crawl too
If your help centre requires a sign in, or if some articles are visible only to signed in users or to particular organisations, a crawl reads what an anonymous visitor reads and no more. The assistant then answers confidently from the public subset and says it does not know about the rest.
That reads as a broken assistant to the agents who can see the whole library, when it is behaving correctly. Either open the material to the crawl, or upload the restricted articles directly so what it knows matches what you expect it to answer.
Saving is not publishing
Theme code has a working copy and a published version. It is completely normal to save an edit, reload the help centre, see no change, and conclude the paste did not take.
Publish the theme, then reload. If you duplicated the theme before editing, check you published the copy you actually edited and not the original.
The Zendesk address and your mapped host are two origins
A help centre answers on its Zendesk address, and if you have host mapped it, on your own subdomain as well. The browser treats those as different origins, so allowlisting only the mapped host leaves the widget missing for anyone who arrives on the Zendesk address from an older link or an email.
List both. The console on the failing page names the origin that was refused, which tells you immediately which one you forgot.
Origins to allowlist
These are the origins a Zendesk Guide site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.
- https://yourbrand.zendesk.com
- https://support.yourdomain.com
- https://help.yourdomain.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 Zendesk Guide 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 Zendesk Guide that depends on what kind of site this is. These go one level further than this guide.
- For a healthtech appA help centre is where somebody describes their symptoms to explain a problem, and the handover emails that description to whichever inbox you nominated.
- For a online storeShoppers can read the delivery article and cannot open a ticket without an account. That makes the handover email the only route to a person.
- For a fintech appA published article is a communication in the firm's name. Guide lets any agent publish one, and the corpus keeps it until the next crawl.
- For a SaaS companyThe help centre holds how-to articles. Plans, limits and trust pages live on your marketing site, a separate origin and a separate crawl.
Taking it off again
Open footer.hbs again, delete the line, save, and publish the theme. If you duplicated the theme before editing, publishing the untouched copy achieves the same thing in one step.
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
- Will it clash with the messaging widget Zendesk provides?
- They are separate scripts and neither knows about the other, so if both are enabled both will render. Two launchers in the same corner is a poor experience, so pick one and switch the other off in the admin.
- footer.hbs or document_head.hbs?
- Either works, because the tag defers. footer.hbs keeps it at the end of the document where scripts usually live, and the head template is a sensible alternative if your footer is heavily customised and you would rather not touch it.
- Can it answer questions about a specific ticket?
- No. It answers from the material you index, so it handles your published articles well. A question about somebody's own ticket needs a person, and the assistant should be set up to hand those over rather than attempt them.
- Do I need to recrawl after publishing an article?
- Yes. The assistant answers from what it has already read, so a new or edited article is not part of its material until the next crawl. Run one after a batch of article edits rather than assuming it noticed.
Keep reading
- Install on DocusaurusThe scripts array in docusaurus.config.js, at the top level of the exported configuration object.
- Install on MkDocsAn overrides directory named by custom_dir under the theme key in mkdocs.yml, holding a main.html that extends the theme's base template.
- Install on VitePressThe head array in .vitepress/config.ts, or the .js, .mjs or .mts file of the same name, at the top level of the exported configuration.
- 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.