Install guide
Adding a chat assistant to a Ghost publication
Ghost has a settings field designed for exactly this, so there is no theme file to edit and no build step. The two things worth knowing before you paste: the field only renders if your theme calls the right helper, and your publication answers on two addresses that a browser treats as unrelated.
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 Ghost
Settings, then Code injection, then the Site Footer box. The alternative is default.hbs in a custom theme.
Code injection is part of Ghost admin whether you are on Ghost's own hosting or running Ghost on your own server. You need the owner or an administrator role: the settings area is not visible to editors or contributors.
Step by step
- 1Sign in as the owner or an administrator. If you cannot see Settings, your role is the reason, not the plan.
- 2Open Settings, then Code injection.
- 3Paste the tag into the Site Footer box rather than Site Header, then save. The tag defers either way, so both work, but keeping third-party markup out of the head makes the head easier to read later.
- 4Open a published post at its real URL and confirm the launcher appears. Code injection applies to the published site, so the editor preview and the admin area are not a fair test.
- 5If you maintain a custom theme and would rather keep the tag in version control, put it in default.hbs immediately before the closing body tag and leave the code injection box empty. Do not do both: the loader refuses to install twice on one page, so the second copy is dead weight that will confuse whoever reads the source next.
- 6Add both the address Ghost gave you and your own domain to the allowlist if you intend to test on either.
What goes wrong on Ghost
A theme that omits ghost_foot swallows the injection silently
Ghost does not inject footer code itself. It hands the content of that settings box to the ghost_foot helper, and the theme decides where to print it. Official and marketplace themes call it just before the closing body tag, but a hand-built theme, or one that has been cut down over the years, sometimes does not.
The symptom is unmistakable once you know it: the box in Settings has your tag in it, you saved it, and the page source has no trace of it anywhere. Add the helper to default.hbs, or put the tag straight into default.hbs and stop using the box.
AMP pages are a separate template and ignore it
If AMP is still switched on for your publication, Ghost serves an alternative, deliberately stripped version of each post at its own URL. That output does not carry arbitrary third-party scripts, so a visitor who arrives from a search result on the AMP version gets a post with no launcher on it, while the same post on your canonical URL has one.
This is not something to fix at the widget end. Either accept that AMP traffic is unassisted, or turn AMP off and serve everyone the canonical page.
The ghost.io address and your domain are different origins
Every Ghost publication keeps its original subdomain even after you connect a custom domain, and a browser treats the two as unrelated origins. Allowlist only the custom domain and the widget vanishes the moment you check the site through the older address, with the refused origin named in the console.
Add both if you use both. If you have finished migrating and never open the subdomain, leave it off the allowlist deliberately rather than by accident.
Origins to allowlist
These are the origins a Ghost site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.
- https://yourpublication.ghost.io
- https://yourdomain.com
- https://www.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 Ghost 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 Ghost that depends on what kind of site this is. These go one level further than this guide.
- For a online coursePaid lessons are gated, so the assistant only ever reads the offer. What it should say when it renders beside a lesson it cannot see.
- For a marketing agencyThe posts the agency is known for sit behind the members gate, so a crawl gets teasers. What is left to answer from is the commercial detail nobody wrote down.
Taking it off again
Clear the Site Footer box in Code injection and save, which takes effect on the next page load. If you put the tag in default.hbs instead, delete the line and upload or redeploy the theme.
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
- Site Header or Site Footer?
- Site Footer. The tag defers, so it never blocks rendering from either position, and the footer keeps your head section free of third-party markup. The one reason to use the header box is if your theme lacks the footer helper, and the better fix there is to add the helper.
- Does it appear on members-only posts?
- Yes. Code injection is part of the page layout rather than the post content, so it renders on gated posts and on the teaser a signed-out visitor sees. That is often where it earns its keep, because the questions asked at a paywall are about membership rather than about the post.
- Why does it work on my domain but not on the ghost.io address?
- The allowlist is checked against the origin the page was served from, and those are two different origins. Add the subdomain if you want it to work there too. The browser console names the refused origin, which is the quickest way to confirm that is what happened.
- What should a Ghost publication index?
- The about page, the membership or pricing page, the posts you refer people back to, and any policy pages. Newsletter publications get most of their questions about billing, access and what a tier includes, not about the writing.
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 DrupalA small custom module attaching a library, an asset injection contributed module, or html.html.twig in a custom theme. Not a custom block.
- Install on JoomlaThe Templates screen, under System in Joomla 4 and 5 and under Extensions in Joomla 3, editing index.php in a copy of your template. Or a Custom module in a footer position.
- 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.