How to use Deacon

Everything it takes to run AI customer support inside your own product: how to install Deacon, how to dress it in your own colors, what you can feed it, how to open it from your own button, and what happens the first time a visitor asks something your documentation never answered.

Last updated August 2026

Install it

One line of HTML, pasted once. Everything after this — colors, knowledge, behavior — is set in the dashboard, and none of it asks you to touch the snippet again.

Create your workspace
Sign up and name your workspace. That name is what Deacon calls you in its opening greeting until you give it a company name, so it is worth typing the name your customers know you by.
Add your domains
On the Install page, list the sites the widget may run on. No https:// needed, www and non-www count as one site, and localhost works so you can try it before anything ships. Deacon appears on every page of a domain you list.
Paste one line before </body>
Copy your snippet and put it at the bottom of every page you want the widget on. It works anywhere you can add HTML — Shopify, WordPress, a bare template — and it loads deferred, so it never blocks your own page.
```
<script src="https://heydeacon.com/widget/v1/loader.js" data-key="dk_live_····" defer></script>
```
Watch it go live
The Install page notices the widget the first time it loads on one of your pages and tells you where it saw it. A hit from localhost is reported as a local test rather than a launch, so “live” always means live.

If the widget doesn’t appear

Deacon refuses to run on an origin you haven’t listed, which is what stops someone else embedding your agent on their site. When that happens it leaves one line in the browser console naming the origin and the fix, so the answer is usually a domain you meant to add and didn’t. Check the console first; the Install page’s live check is the second place to look.

Try Deacon for free

Install Deacon

Style it

The Widget page walks the journey your visitors take — the button, the chat window, the conversation, the message they get when there is no answer — and you set the colors at each stop against a live preview. Nothing changes on your site until you press Save, and a saved change reaches your live widget on its own. The aim is something that reads as part of your product rather than a bolted-on chatbot: your colors, your corner, your company’s name in the opening line.

The Help button

The pill in the corner, as visitors first see it. Deacon flags any pair of colors that falls under a 4.5:1 contrast ratio while you pick them, so a legible button is the default rather than a lucky one.

Label: Up to 24 characters. “Help” unless you say otherwise — “Ask us”, “Support”, your own word for it.
Background and text: Any two colors. Hover, press and focus states are derived from whichever background you choose, so a themed button keeps its own matching states.
Visibility: Visible pill, or invisible — no button at all, so Deacon opens only from your own UI. See “Open it yourself” below.
Placement: Bottom left, bottom center or bottom right, plus a side and bottom offset up to 64px each — enough to clear a cookie bar or your own floating button.

The chat window

The panel Deacon opens over your page, and the box visitors type their question into. On a phone it becomes a full-width bottom sheet whichever placement you chose, because there is nowhere else for it to go.

Company name: How Deacon introduces itself: “Hi — I’m Deacon, Acme’s AI Assistant. How can I help you?” Leave it blank and it uses your workspace name.
The greeting itself: Fixed, and deliberately so — it is the line that tells a visitor they are talking to an AI, and that disclosure is not ours to make optional.
Surface, border, text and placeholder: Four colors for the chat window and the ask box. Left unset, each falls back to Deacon’s own paper-and-ink default.
Corner radius: Square, Soft, Round, or anywhere between 0 and 24px on the slider. Default is the window’s own 32px corner.

The conversation

Turns are plain text on the chat window rather than bubbles, so there is no fill to color — just the ink for each voice, and one message whose wording is not yours to set.

Your visitor’s words: The ink questions are set in. Quieter than the reply by default, so the thread reads as a conversation rather than a transcript.
Deacon’s words: The ink answers are set in — the color most of the chat window will be.
The “can’t answer” message: Fixed wording, previewed on the same page. What you can add is a support email, which puts a direct “or email …” line under it.

Teach it

Deacon answers from what you give it and nothing else. There are four ways to give it something, and most teams end up using all four — a crawl for the docs, a file for the handbook, pasted text for the FAQ nobody published, and a handful of Q&As for the answers that have to be worded exactly.

A website

Paste a page address and Deacon learns from that page. Paste a site address and it crawls the site, lists what it found, and waits: nothing is indexed until you tick it. That distinction matters more than it sounds — a support knowledge base is your docs and help center, not your careers page and your blog archive. Re-fetch any page later when you change it.

A file

PDF, Word (.docx), plain text, markdown, CSV or HTML. Upload the handbook, the price list, the onboarding deck — anything your team already wrote and never turned into a web page. Re-uploading a file with the same name replaces that source rather than duplicating it.

Pasted text

Give it a title and paste the content. This is the fastest way to get an FAQ that lives in someone’s notes app into the knowledge base, and the right home for the policies that were never written down anywhere formal. Re-using a title replaces that source.

A Q&A

An exact answer to a specific question, and the one source type that outranks the others: when a visitor asks that question, this is the answer they get. Use it for the things you need worded precisely — refund windows, what your free plan includes, whether you support a particular integration.

Sources go into one table, whatever they came from, so “what does my agent actually know?” has a single answer you can read in one screen. Add or edit anything and the table tells you there is retraining to do; press it and Deacon re-reads what changed.

Every plan carries a knowledge budget and a page limit for crawls — enough on the free plan to point Deacon at a documentation site and see what it does with it. The plans page has the current figures.

Then try it in the Playground, which runs the real agent against your real sources without anything being installed anywhere. Ask it the five questions your customers actually ask. It is a faster way to find the gaps than waiting for someone to fall into one.

Brief it

What Deacon knows is its knowledge sources. What it may say is the Instructions page: a few paragraphs about your business, the tone to take, and the things it should hand to a person rather than attempt — billing, account specifics, anything with a refund attached. It still answers only from your material; this shapes how it helps, not what it knows.

A blank box asking you to describe your own business is a surprisingly hard place to start, so Deacon will read your homepage and write a first draft. The draft lands in the editor unsaved — read it, correct the parts it got wrong about you, then save. Instructions take effect on new conversations from the moment you do.

Open it yourself

The embed defines a small API on window as soon as it has run, so any element on your page can open the widget:

<button onclick="Deacon.open()">Ask a question</button>

There are four calls. Deacon.open(), Deacon.close() and Deacon.toggle() do what they say; Deacon.preload() warms the widget without showing it, which is worth calling on hover if you want the click to land on something already running.

Pair this with the launcher’s invisible mode and Deacon paints nothing of its own — no pill, no corner — until your own UI asks for it. A link in your nav, an item in your help menu, a button under an empty state: the widget becomes a thing your product opens rather than a thing parked on top of it.

The panel lives behind a closed shadow root, so your page cannot inspect it and no stylesheet of yours can leak into it. To react to it, listen for the deacon:open and deacon:close events on window — those fire whichever way the panel opened or closed, including from the visitor’s own Escape key. The hexagon on our own home page presses itself in when it opens Deacon and waits on deacon:close to come back, because that event is the only way it can know the visitor dismissed the panel.

Two deliberate absences. Deacon claims no keyboard shortcut, so it can never collide with a command palette or a search field you already own. And it never throws onto your page: on a domain you haven’t allowed, on a bad key, or with storage blocked, the calls above quietly do nothing and one console warning explains why.

What visitors get

Conversational AI is easy to judge on the questions it answers well. What decides whether yours is any good is the other two paths — the opener too vague to answer, and the question your documentation has no answer for. Here is what Deacon does with all three.

When it has the answer

The visitor opens the widget — your button, the Help pill, or the thread they already had open on the last page
Deacon opens with its greeting, which names you and says plainly that it is an AI
They ask. Deacon retrieves the passages from your sources that bear on the question and answers from those
The answer cites where it came from, so the visitor can go and read the source themselves
Too vague to answer — “help”, “it’s broken” — and it asks a clarifying question instead of guessing
The conversation survives navigation, so reading that page doesn’t cost them the thread

When it doesn’t

Deacon says it doesn’t know rather than assembling something plausible
It offers to take the visitor’s email so your team can follow up — plus a direct “or email …” line if you set a support address
You get the whole conversation by email, with the visitor on Reply-To, so hitting reply goes straight to them
The same question is waiting in your dashboard, marked unanswered and not in your docs
You answer it once, and that answer becomes a curated Q&A the next person gets straight away

That first column is what a personalized customer experience means in practice, and it is worth being exact about. Someone asking about your refund window does not get five suggested articles and a search box. They get an answer to the question they actually asked, composed from the passages of your material that bear on it, in a sentence or two — your documentation is the raw material, not the thing the visitor is handed. Ask about a feature using a word you have never used for it and Deacon still recognizes it; ask something your docs half cover and it answers the half it can and says plainly what it can’t.

The third path sits between the two, and it is the one most bots get wrong. A message too vague to act on — “help”, “it’s broken”, “I’m stuck” — is an invitation, not a failure, so Deacon neither guesses nor declines. It acknowledges the problem in a sentence and asks the one or two clarifying questions that would let it answer on the next turn: never a list of them, never something the conversation has already told it, and never the same question twice.

Then the loop. Answering an unanswered question is the part worth doing weekly, because your gap list is voice of the customer data you did not have to run a survey to collect — every row is somebody telling you in their own words what your documentation is missing. Teaching Deacon the answer fixes it for everyone who asks next rather than just the person who asked first, and the list that remains is about the most honest customer insight you will get for free. If a question isn’t worth teaching — a wrong number, someone asking about the weather — dismiss it and it stops asking you.

Nothing about this needs a helpdesk, a ticket queue, or live chat support with somebody watching for a message to land. The questions Deacon can answer never reach you, and the ones it can’t arrive as email, which is a thing you can answer from a phone at a bus stop.

Using Deacon, answered

The snippet takes about five minutes: add a domain, copy one line, paste it before your closing </body> tag. The part that takes longer is deciding what Deacon should know, and that is time you spend choosing which of your existing pages to point it at rather than writing anything new.

Probably not. It is one line pasted before your closing </body> tag, and anywhere that accepts a script tag — Shopify, WordPress, Webflow, Squarespace, a custom app — takes it exactly as it is. If your site is code you would rather not open yourself, hand the snippet to any modern AI coding tool and it will put it in the right place. Everything after that is done in the dashboard, and changing the theme, the knowledge base or the instructions never changes the snippet.

No. Set the launcher to invisible on the Widget page and Deacon paints nothing at all, then open it from your own UI with Deacon.open() — a link in your nav, an item in your help menu, a button at the bottom of an empty state. The API is available as soon as the embed script has run.

Deacon says it does not know rather than guessing, and offers to take the visitor’s email so you can follow up. You get the conversation by email with the visitor on Reply-To, and the same question is waiting in your dashboard marked as unanswered. Answering it there turns it into a curated Q&A, so the next person to ask gets a straight answer.

Deacon answers from the material you give it rather than from the model’s general training. It retrieves the passages most relevant to each question, confines the answer to them, and cites the source so both you and your customer can check it. Where it finds nothing to support an answer, it says so and flags the conversation instead of filling the gap.

Yes — the Playground runs the real agent against your real knowledge base, with nothing installed anywhere. It is the right place to find out that your refund policy is described three different ways across your site, which is the kind of thing you would rather learn from yourself than from a customer.

Try Deacon for free

Add a domain, paste one line, and point Deacon at the help pages you have already written. About five minutes to a working agent, and nothing to draw or configure first.