Why a component rather than editing the theme directly?

Because a component is a separate object that a theme includes. Update the theme, switch to another theme, or swap the whole look, and the component is still there to add back in one click. An edit typed into a theme is gone the moment that theme changes.

Does it reinstall itself as members move between topics?

No. Discourse routes in the browser after the first load, so the document stays put and the loader runs once. A member can open a conversation, keep reading topics and still have it open.

Should the assistant answer inside topics?

It does not post anything. It is a separate panel a visitor opens, so it never appears in a thread and never touches your moderation queue. That distinction is worth stating to your moderators before you switch it on.

Which field, body or head?

The body field. Both accept script tags, and the tag would work in either because it defers, but the end of the body is where third party markup belongs and it keeps the head to what Discourse itself puts there.

Install guide

Installing a chat assistant on a Discourse forum

Discourse has a purpose built field for markup at the end of the body, and a component system that keeps your addition separate from the theme it decorates. Using both is what makes this install survive the next theme update. The other thing to think about before you start is what the assistant is allowed to read.

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 Discourse

Admin, then Appearance, then Themes and components. Create a component, open Edit Code, and use the field labelled body.

Any Discourse community where you have administrator access. The theme system is core, so there is no plugin to install, but note that Discourse enforces a content policy of its own on scripts, which is a further reason to install through the theme system rather than any other route.

Step by step

1Sign in as an administrator and open Admin, then Appearance, then Themes and components.
2Switch to the Components tab and create a new component. Give it a name that says what it is, because the list gets long.
3Open the component and choose Edit Code.
4Select the field labelled body. Its own description says it is HTML inserted at the end of the body element, with support for script tags, which is precisely what you need.
5Paste the tag into that field and save.
6Go back to the Themes tab, open the theme your community actually uses, and add the component to it. A component does nothing until a theme includes it.
7Reload the forum with a hard refresh and confirm the launcher appears on a topic page as well as on the topic list.

What goes wrong on Discourse

A theme pulled from a repository is not yours to edit

Themes installed from a git address are kept in step with that repository, and Discourse tells you so: it points you at the repository and asks you to submit the change there instead. Even where an edit goes through, the next update pulls the upstream version back over it.

A component you create in the admin has no upstream, so nothing overwrites it. That is the whole reason to spend the extra minute creating a component rather than typing into the theme in front of you.

Discourse enforces its own script policy

Discourse ships a content policy switched on by default, and it has a setting for additional allowed script sources whose own description warns that host entries are ignored while its strict mode is active. So the usual instinct, adding the loader host to an allowlist setting, is not reliably the fix here.

The observable difference matters: a policy problem prints a browser console message naming a policy directive, while an allowlist problem prints a message naming your forum address as refused. Read which one you have before changing anything. Installing through the theme component field, rather than through any other injection route, is the path Discourse supports for a script tag.

A private community shows the crawl a sign in page

Communities frequently require an account to read anything, and categories can be restricted to groups on top of that. An unauthenticated crawl of such a forum reaches the sign in screen and stops, so the assistant ends up with one page of material: the sign in screen.

This is not an install problem and it will not look like one. The widget appears and answers nothing useful. Point the assistant at whatever public material you do have, your documentation, your policies, your public categories, and treat the private discussion as out of scope rather than trying to force it in.

Origins to allowlist

These are the origins a Discourse site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.

https://community.yourdomain.com
https://forum.yourdomain.com
https://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.

Loader behaviour
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 Discourse 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 Discourse that depends on what kind of site this is. These go one level further than this guide.

For a developer tools companyThe threads are written by your users, not by you. What to index when the documentation and the forum sit on two origins.

Taking it off again

Open the component, clear the body field and save, or remove the component from the theme that includes it. Removing it from the theme switches it off everywhere while keeping the component for later.

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 a component rather than editing the theme directly?: Because a component is a separate object that a theme includes. Update the theme, switch to another theme, or swap the whole look, and the component is still there to add back in one click. An edit typed into a theme is gone the moment that theme changes.
Does it reinstall itself as members move between topics?: No. Discourse routes in the browser after the first load, so the document stays put and the loader runs once. A member can open a conversation, keep reading topics and still have it open.
Should the assistant answer inside topics?: It does not post anything. It is a separate panel a visitor opens, so it never appears in a thread and never touches your moderation queue. That distinction is worth stating to your moderators before you switch it on.
Which field, body or head?: The body field. Both accept script tags, and the tag would work in either because it defers, but the end of the body is where third party markup belongs and it keeps the head to what Discourse itself puts there.

Keep reading

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.

Start free See what it does