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 September 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 give your company or site name. That name is what Deacon calls you in its opening greeting until you set a different company name on the Appearance page, 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 in the background, so it never blocks your own page.
<script src="https://heydeacon.com/widget/v1/loader.js" data-key="pk_your_widget_key" async></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 DeaconStyle it
The Appearance page puts three rooms, Copy, Style and Placement, beside a live preview that steps through the journey your visitors take, from the button to the chat window, the conversation, and the message they get when there is no answer. Nothing changes on your site until you press Publish, and a published change reaches your live widget on its own. The aim is something that reads as part of your product, in your colors, with your corner and 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 you find out before your visitors do.
- Button 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.
- Greeting
- Optional, up to 300 characters. It is the first thing Deacon says and also the AI disclosure, so there is always one. Leave it blank and Deacon uses its default line, which names you and says plainly that it is an AI.
- 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 32px 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 two voices are easy to tell apart.
- 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, and you will find the gaps before a visitor does.
Brief it
What Deacon knows is its knowledge sources. What it may say is the Instructions page, which holds 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 five 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; and Deacon.setContext({ plan: 'Team' }) tells Deacon what your page has learned about the visitor since it loaded — a sign-in, an upgrade — so the next answer is the one for them. It merges over the window.deaconContext your embed declared, naming only what changed.
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 or a button under an empty state all work, and the widget becomes a thing your product opens.
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
- The same question is waiting in your dashboard, marked unanswered and not in your docs
- Reply from there and a visitor who left their email gets your answer by email, and their reply comes back to you
- 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 Deacon writes from. 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. 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 wait in your dashboard for you to answer from your phone.
Using Deacon, answered
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.
See what Deacon does, read the plans and prices, or compare it with Zendesk.