How to use Deacon, step by step

Deacon is an AI customer support agent for founders who handle support themselves. It answers your customers in seconds from your own docs, tells them when it doesn’t know, and shows you what they’re stuck on and what they want next. This guide walks through every step with the exact page and button names, from adding one script tag to answering the questions Deacon missed. The install takes a few minutes, and every step works on the free plan, which needs no card.

Last updated 1 November 2026

Put Deacon on your site in a few minutes

You add one script tag to your site, once. Everything after that, from colours to what Deacon knows, is set in the dashboard and reaches your site on its own. The same tag also counts your visitors, sources and goals on Analytics › Website, so there’s no second script to add.

  1. Sign up free

    Use your email or Google. The free plan needs no card and has no end date. Deacon then asks for your website, and that one address sets everything up. It starts learning from your pages, gives your widget your company’s name and colour, and gets your snippet ready. In about a minute you can try it out, before you install anything.

  2. Check your domains

    Press Install at the top of the dashboard. The site you gave when you signed up is already under Your sites, so your snippet is ready. It covers your subdomains too, such as docs.yoursite.com and your www address. Add any other address Deacon should run on, such as your site builder’s staging address, with no need for https://. If you signed up without a website, add your domain here, and localhost works if you want to try it on your own machine first.

  3. Paste one line before </body>

    Copy your snippet from the Install page and paste it just before the closing </body> tag on every page you want Deacon on. It loads in the background without holding up your page. Any site that takes HTML takes it, such as Shopify’s theme.liquid, a header-and-footer plugin on WordPress, or the custom code settings in Webflow and Framer. Install opens on the steps for your site builder when it can tell which one you use, such as Webflow or Shopify. If your site is your own code, press Copy the prompt instead and paste it into Claude Code, Cursor, Codex or ChatGPT. An agent adds the tag and checks it’s live, and a chat tells you where it goes. The snippet below has a placeholder key, so copy yours rather than this one.

    <script src="https://heydeacon.com/widget/v1/loader.js" data-key="pk_your_widget_key" async></script>

  4. Watch it go live

    The Install page keeps checking by itself and says Live, with your domain, once a page on your site has loaded it. A test on localhost or a .test address never counts, so live always means your real site.

Steps for your framework

If your site is your own code and built with one of these, its page says where the tag goes and how to check it before you publish.

If Deacon doesn’t appear on your site

Open your browser’s console first, because Deacon leaves one line there saying what’s wrong. On a domain that isn’t in your list, it stays hidden and names the domain it won’t run on, and the Install page names it too, so the fix is usually an address you haven’t added yet. An unknown key means the snippet isn’t your own, so copy it again from the Install page. The console also says when your site’s Content-Security-Policy blocks the chat, and gives the error when Deacon couldn’t start at all.

Try Deacon for free

Install Deacon

Make Deacon look like part of your site

Open Appearance under Your agent. Its three tabs, Copy, Style and Placement, sit beside a live preview you can switch between scenes such as First open, Conversation and Can’t answer, so you see every state before a visitor does. Your changes stay a draft, even through a refresh, until you press Publish, and then reach your site on their own. Revert to live throws a draft away.

The Copy tab

Every word a visitor reads that isn’t an answer, and the preview follows each one as you type.

Company name
The name Deacon gives you in its greeting, as in Acme’s AI assistant. Left blank, it uses your workspace name.
Greeting
The first thing Deacon says, up to 300 characters. Left blank, Deacon uses its default, which names your company and says it’s an AI.
Button label
The word on the button in the corner of your site, up to 24 characters. It says Help, in the language the chat opens in, until you change it to something like Ask us.
Support email
Adds an “or email you@yoursite.com directly” line under the offer to follow up, for visitors who’d rather write to you.

The Style tab

Pick each colour against the preview. If a pair gets hard to read, a note under it gives the contrast ratio and what to aim for.

Accent and send button
One colour for buttons, links and focus rings. The send button follows it unless you set it apart.
Help button
Its background and text. The hover and press shades are worked out from your background, so they always match it.
Window
The surface and border, and a corner radius from 0 to 32 pixels, with Square, Soft, Default and Round presets. Default is 20 pixels.
Conversation, follow-up card and ask box
The ink for Deacon’s words, your visitor’s words, your own replies, and captions and sources, plus the email box border and the ask box’s text and placeholder. Replies sit on the window as plain text, not in bubbles.

The Placement tab

The button keeps to the bottom edge of the page. On a screen narrower than 640 pixels, the chat opens as a full-width sheet wherever you put it.

Visibility
Visible pill, or Invisible, so Deacon opens only from your own button. There’s more on that below.
Files
On, so visitors can add screenshots and documents to a message. Deacon reads pictures, PDFs, Word and text files. Turn it off and the ask box has no paperclip.
Position
Bottom left, bottom middle or bottom right.
Side and bottom offset
Up to 64 pixels each, enough to clear a cookie bar or a floating button of your own.

Teach Deacon your product from what you’ve already written

Deacon answers only from what you give it, so this step decides how good its answers are. Open Knowledge Sources under Your agent. Add website, Add file and Add text bring in pages, files and pasted text, and the answers you write live in your help document, which has its own Add section. Start with your help pages or docs, and add the rest as gaps show up.

Add website

Paste one page’s address and Deacon learns from it straight away. Paste your site’s address and it asks whether to read the site or just add that page. On the free plan, reading the site takes your home page and the pages visitors ask about first, like pricing and help. On a paid plan it crawls the whole website and lists its pages unticked, so you tick the pages or folders that matter, press Save and then Retrain agent. It never takes sign-in, cart, checkout or account pages, each crawl stops at 100 pages, and you re-fetch a page by hand when it changes.

Add file

PDF, Word (.docx), text, Markdown, CSV or HTML, up to 10 MB each. It’s the home for the handbook, price list or onboarding guide that never became a web page, and a scanned PDF works too. Upload a file with the same name to update it, and Deacon keeps answering from the old version until you press Retrain agent.

Add text

A title and whatever you paste under it. It’s the quickest way in for an FAQ that lives in your notes, or a policy you never published. Pasting under the same title again updates that source, and Deacon keeps answering from the old text until you press Retrain agent.

Add section

Your help document holds the answers you write, each section a title and the answer. Open it from its row in Knowledge Sources and press Add section to cover something before anyone asks, like your refund window or what your free plan includes. You can edit, reorder or delete sections, put back an earlier version and download the whole document as Markdown. Deacon searches it like any other source and doesn’t put it first, so keep your pages saying the same thing.

A file, pasted text, a single page or a help document section starts answering as soon as Deacon has read it. The first read of your site needs no Retrain agent either, because Deacon chooses its pages and learns from them itself. Pages you tick after a later read wait for Retrain agent, and so does an edit to a source that’s already trained, with the old version answering in the meantime.

Each plan holds a set amount of knowledge and reads a set number of pages a month from your website, and the pricing page has the figures.

Then open Playground and ask it what your customers ask most. It’s the real widget answering from your real knowledge, with nothing installed and nothing counted against your answers. Fill in a visitor’s details, such as their plan, to see the answer they’d get. Anything it can’t answer there is a gap you can fill before a customer finds it.

Keeping Deacon up to date

Deacon doesn’t re-read your site on its own, so when you change a page, tell it. Open Knowledge Sources, find the page and choose Re-fetch from the ⋯ menu on its row. Re-fetching is free. It doesn’t count toward your monthly page limit, and it works even when that limit is used up. Each page can be re-fetched once every 24 hours, and its row says when you can do it again. Your release script can also re-fetch the pages it changed through the API, so nobody has to remember.

If the page changed, Deacon learns the new version as soon as it has read it, with nothing to press. Its row says Reading… until then, and Deacon answers from the old version meanwhile. Re-fetch several pages and Deacon reads a few a minute, so you can leave the page while it works through them. Once a page is read, its row says Up to date. If a page comes back under half its old size, Deacon waits for you instead, because a cookie wall may have taken its place. The row says the page changed. Open it to read the new version, with the live one a click away, then press Use new version or Keep live version.

A re-fetch never costs you a page Deacon already answers from. If your site’s security check turns Deacon away, or sends a “verify you are human” screen in place of the page, Deacon tries once more and never learns from the check. The page keeps answering from the version it has, and its row says Deacon couldn’t read it this time. That still counts as the page’s re-fetch for the next 24 hours, and the row says when you can try again.

Pages Deacon reads for the first time use your monthly page limit. That’s a page you add as a link, the pages Add website reads, and the page a draft of your Instructions comes from. The limit resets each billing month, and once it’s used up, adding a page tells you the day it resets. The pricing page has each plan’s limit.

Pasted text, uploaded files and the answers you write don’t use the limit, so you can always add those. If you need a new page before the limit resets, copy its text into Add text, and Deacon answers from it as soon as it’s read.

Tell Deacon how to talk and when to hand over

Knowledge Sources decides what Deacon knows. Instructions, under Your agent, decides how it behaves. Write a few plain sentences about what your product does and who it’s for, the tone to take, and what to leave for you, such as billing or account problems. Deacon still answers only from your knowledge, so instructions shape how it helps, not what it knows.

You don’t have to start from a blank box. The website you signed up with is already under Start from your website. Press Write a draft, and Deacon reads that page and writes a first draft into the box. Reading it uses one page of your monthly page limit. Nothing is saved until you’ve read it, fixed what it got wrong and pressed Save. Deacon follows them from its next answer.

Open Deacon from your own button

As soon as the script has run, your page has a small Deacon object, so any button or link can open the chat.

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

Deacon.open(), Deacon.close() and Deacon.toggle() do what they say. Deacon.preload() loads the chat without showing it, so calling it on hover makes the click feel instant. To react when the chat opens or closes, listen for the deacon:open and deacon:close events on window. They fire however it happened, including a visitor pressing Escape. When the team has replied and the visitor hasn’t read it yet, deacon:unread carries the number in event.detail.count, and 0 once they open the chat, so your own button can show it and clear it.

To use only your own button, choose Invisible on the Placement tab of Appearance. Deacon then puts nothing on your page until your code opens it, from your nav, your help menu or an empty state. While the button is hidden, the Install page opens with the button code showing, so you don’t forget it.

If people log in to your app, it can pass Deacon who’s logged in. Set window.deaconUser above the snippet to their id, email and name, from the session your app already has. If your app only learns who’s logged in after the page loads, set it then and pass the same three to Deacon.identify(). On log-out, set it to null and call Deacon.identify(null). Conversations then shows their name, and when Deacon can’t answer, their email is already in the box, so asking for a reply takes one tap. On their own, the details come from their browser, so they only label that browser’s chats, and they never reach the AI. The “Do your users log in?” card on the Install page has a prompt your AI tool can follow to make the change, and the code for HTML, Laravel, Next.js and Rails.

Your server can also sign who’s logged in, so Deacon can verify it. An owner makes a secret on the Install page, and you set it on your server as DEACON_SECRET. Add a route, POST /deacon/token, that answers with a token signed with it for whoever is logged in, and give window.deaconUser a token function that calls the route and throws when it fails, so Install can say what went wrong. Conversations then marks the person with a tick, a reply reaches their email without them typing it, their chats follow them across their devices on your real site, and an owner can delete everything Deacon holds from one person. A staging or preview site needs a Deacon team of its own. The prompt on the Install card covers this step too, and Prove who is signed in in the install guide has the route. So do the Laravel and Next.js guides.

Details such as the visitor’s plan or role are separate. Set window.deaconContext above the snippet, and Deacon takes them into account when it answers and shows them beside the conversation. After an upgrade, call Deacon.setContext({ plan: 'Team' }), which changes only what you name. It takes up to 12 details, and they come from the visitor’s browser, so never send a password, a token or an internal id.

The same object sends goals to Analytics › Website. Call Deacon.track('Sign up') when someone signs up, or add data-deacon-goal="Sign up" to the button, and you’ll see which sources bring the visitors who do. Deacon claims no keyboard shortcut, so it never clashes with one of yours, and it never throws an error onto your page.

When Deacon can’t answer, and how it gets better

Every question goes one of three ways. Deacon answers it in seconds, asks one question back when it’s too vague to answer, or says it doesn’t know. Here’s what your customer sees, and what you do about the questions it couldn’t answer.

When your content has the answer

  • The visitor opens Deacon from the button in the corner or your own, and sees your greeting above a box that reads Ask AI, with up to three questions Deacon wrote from your pages during setup, each asked in one tap
  • Deacon answers in seconds, from the passages it finds in your content, in the language they wrote in
  • They can add a screenshot or a document with the paperclip, or paste or drop one in, and Deacon reads pictures, PDFs, Word and text files to see what they’re asking about
  • An answer taken from a page on your site usually links to that page, so they can read more
  • A question too vague to answer, like “it’s broken”, gets one question back instead of a guess
  • The conversation follows them from page to page and survives a reload. New chat starts over, and Recent chats keeps their chats from the last 30 days in that browser

When it doesn’t

  • Deacon says it doesn’t know, in its own words, instead of making something up
  • Under its reply it asks “Want the team to follow up?” with a box for their email, and your support email if you’ve set one
  • When they leave an address, the conversation shows as unread and you get an email three minutes later, unless someone on your team has opened it or has the dashboard open. Asking for a person emails you too
  • You reply from Conversations, with files if you need them. If their chat is still open, your reply appears there under your name and Deacon steps back. If they’ve gone, a red count on the chat button tells them, and they’ll see your reply next time they open the chat in that browser. If they left an address in that conversation and haven’t read it in the chat, it’s emailed to them too
  • Hand back to Deacon lets it answer again, and a question your content didn’t cover waits for you with an Answer this button

This is Answer once, and it’s how Deacon gets better. Filter Conversations by Unanswered to see the questions your content missed, in your customers’ own words. Press Answer this on one of them, or Improve answer under a reply you’d word differently. The panel shows the question, Deacon’s reply and the source it answered from. Write your fix the way you’d reply to the visitor, or as rough notes, and press Save. Every answer you write becomes part of what Deacon knows, so it can answer the next person who asks, and the more you answer, the less it needs you.

Deacon decides where your fix belongs and writes it up as help content. It goes into the section of your help document on that topic, or a new section named from what it says, or your Instructions when it’s about how Deacon should behave. There’s no preview to confirm. The panel shows where it went and how it now reads, with Move to put it somewhere else and Undo to put everything back as it was.

Once your fix is live, Deacon asks the visitor’s question again, with the conversation before it, and shows the reply under “Deacon now says”. If it still can’t answer, it tells you. After a fix goes into your help document, Deacon also re-asks the most similar open questions and lists the ones your fix answers too, each linking to its conversation, and those leave the Unanswered list. A question that isn’t worth answering, like a wrong number, can be dismissed.

The same questions show you what to fix and what to build. Open Analytics › Widget and start with What needs you. Its first line names your first job, such as replying to the people waiting. Below that are the bug reports visitors sent, beside the JavaScript errors your pages threw, then the account and billing questions that usually need you, then the questions Deacon didn’t know. Open a bug and press Copy this bug report for your coding agent, and Claude Code or Cursor gets it in your visitors’ own words.

Further down, Topics group similar questions, count how many people asked and label most of them as a how-to, a feature ask, a bug report or a pricing question. What they ask you to build lists what visitors ask for in their own words, a one-off ask included, so you hear from everyone who asked, not just the few who email. The page’s first card says how many questions Deacon answered and how many conversations it handled without you.

None of this needs a helpdesk, a ticket queue or someone watching the chat at night. Deacon answers what your content covers, and the rest waits for you in Conversations.

Connect Deacon to your own code and tools

All of this is under Integrations in the sidebar, on every plan. Only an owner can make a key or add a webhook, and the API docs have the detail.

Connect your coding agent over MCP and ask it what broke this week. Press Connect your agent, run the line or press the button, and approve it in your browser. It can fix your code and mark the topic done. It can also suggest a better answer for Deacon, which waits in Conversations until you save it.

Webhooks tell your code when something happens in a chat, so it can open a ticket when a visitor reports a bug or add them to your CRM when they leave their email. You can open any of them to see exactly what was sent, and Deacon keeps trying if your server misses one.

The API lets your own code pull bug reports into your tracker, add each release note to what Deacon knows or reply to visitors from your admin panel. Make a Read key to read, or a Read and write key to add and reply.

To keep your own copy of your chats, filter Conversations if you like and press Export. It saves the list as a CSV, with a row for each message. The button isn’t on phones.

FAQ

Questions about using Deacon

About a minute to your first answer, and a few minutes to install. When you sign up, Deacon asks for your website and starts learning from it straight away, home page first, so you can try it out while its main pages, like pricing and help, are still being read. Then copy one line from the Install page and paste it before </body>. A file, pasted text, a single page or a section of your help document answers as soon as Deacon has read it. There are no flows or decision trees to build first.

No. If your site builder takes HTML, as Shopify, WordPress, Webflow and Framer do, you paste the tag in yourself. If your site is code, press Copy the prompt on the Install page and paste it into Claude Code, Cursor, Codex or ChatGPT. An agent adds the tag, sets up any extras you want and checks that Deacon is live. Everything after that happens in the dashboard, and nothing you change there touches the snippet.

Yes. When you sign up, you try it out on a preview of your own site as soon as it can answer. After that, Playground is the real widget answering from your real knowledge, with nothing installed anywhere. You can also add localhost to your domains and try the install on your own machine. None of these chats count against your plan’s answers.

Re-fetch it. Re-fetching a page Deacon already has never counts toward the limit, so open Knowledge Sources, choose Re-fetch from the ⋯ menu on the page’s row, and Deacon answers from the new version as soon as it’s read. Each page can be re-fetched once every 24 hours. For a page Deacon doesn’t have yet, paste its text with Add text, which doesn’t use the limit either, or wait for the limit to reset on the day Deacon names.

It’s built not to. For each question it finds the passages in your own knowledge that bear on it, and answers only from those. When they don’t cover the question, it says it doesn’t know and asks for the visitor’s email instead of guessing. It always turns down questions about a visitor’s own account, invoice or data.

It replies in the language each visitor writes in, whatever language your docs are in, with nothing to set up. The widget’s own words, such as the Ask AI box, come in English and 40 other languages, and so do its fixed replies, such as the one sent when your plan’s answers have run out, and the email a visitor gets with your reply. The widget opens in your page’s language when it’s one of those other than English, or else in the visitor’s browser’s language, and switches once Deacon replies in another one. A greeting or button label you write yourself stays as you wrote it. In the dashboard you can translate any conversation into your own language.

In Conversations. Every conversation is saved word for word, with the page the visitor was on and the source each answer named. Search it by what visitors asked, or filter it by Unanswered to find the next questions to answer, and press Export to save the list as a CSV. Topics on Analytics › Widget group similar questions and count how many people asked each, so you can see what to fix and what to build next.

Nothing is charged past your plan, and no plan upgrades itself. Visitors get a short reply saying Deacon can’t look into it right now and are asked for their email, unless they’ve already left it. You can still read and reply to every conversation.

Yes. As soon as the script loads, it sets a cookie called deacon_visitor_id and keeps the same id in local storage, so Deacon can tell a returning visitor from a new one. It lasts up to 90 days, and Safari cuts it to about 7. Page views are counted without it, from a hash that changes every day. Once the chat has been opened, the widget keeps deacon_chats in local storage, ending 30 days after the last open. If your site tells Deacon who’s logged in, it adds deacon_signed_in with their id or email, so a shared computer starts the next person fresh. For the life of a tab, deacon_language and deacon_panel sit in session storage.

Try Deacon for free

Sign up with your website, paste one line, and Deacon answers your customers from the pages you’ve already written. It answers in seconds and shows you what they need, and the free plan needs no card.

See every feature, compare the plans and prices, or read what to do after you launch.

READ NEXT