Live chat API
A live chat API lets your own code read your chats and reply to them. Deacon is the AI support chat on your site, and its API also keeps what Deacon knows up to date, so your release script can teach it what you just shipped.
On every plan, including the free one.
$ ./deploy.sh
✓ Shipped: export reports to PDF
{ "state": "reading" }
Can I export a report to PDF?
Yes. Open the report, press Export and choose PDF.
acme.co/docs/reports
Sped up. Acme and its docs are made up for this example.
Support shows up where you already work
Deacon stops falling behind your product
Every release can update what it knows, with nobody having to remember.
You see support in your own tools
Put it in your admin panel or your team’s channel.
You can answer from anywhere
A reply from your code lands in the customer’s chat under your name.
At a glance
| What it reads | Your chats, what Deacon knows, the questions waiting for you, topics, your site’s JavaScript errors and the last 30 days of events. |
|---|---|
| What it changes | Add text or a page, re-fetch a page, change your help document, reply to a customer and hand a chat back. |
| What it won’t do | Take a question and give you Deacon’s answer, change your Instructions, or read visits, goals and funnels. |
| Where you start | Make a key on Integrations. Only an owner can. |
Thirteen jobs your code can take off you
Each one is a few lines of code.
Stay current
Re-read your docs on every release
Your deploy script re-fetches the pages you changed. They go live once read and spend none of the month’s pages. Once a day per page.
POST /knowledge/{id}/refetchTeach Deacon each new feature
Your release script adds a section to the help document, and it’s live once read, with no retraining.
POST /help-document/sectionsKeep policy answers in your repo
When your refund policy changes in code, your build updates the section Deacon answers from.
PUT /help-document/sections/{id}Hear when a page can’t be read
A nightly script re-fetches each page, then checks for a problem and tells you. It spends none of the month’s pages.
POST /knowledge/{id}/refetchGET /knowledge
Your own tools
Send yourself a Monday digest
Deacon has no digest email, so a scheduled script sends What needs you and your top topics to your team.
GET /needs-youGET /topicsShow a customer’s chats on their account page
Your admin looks them up by email, so you know what they asked before you answer their invoice query.
GET /conversationsPut support numbers on your own dashboard
How many asked and how many are still unanswered, topic by topic.
GET /topicsCatch up after downtime
Your tool reads what it missed from the last 30 days, the same events a webhook would have sent.
GET /events
Reply anywhere
Tell people it’s fixed
When you ship, a script replies to everyone who reported it. It appears in their chat under your name, and if they left an email, it reaches their inbox too.
POST /conversations/{id}/repliesAnswer from your own tool
A Slack bot or admin page can send your reply, then hand the chat back to Deacon.
POST /conversations/{id}/repliesPOST /conversations/{id}/hand-back
On your own pages
No key needed. These run in the browser, in your site’s own code.
Open the chat from your own Help button
Hide Deacon’s button and call Deacon.open() from yours. Deacon.close() and Deacon.toggle() work too.
Deacon.open()Pass the name and email of whoever’s logged in
Set their id, email and name, so you see who’s asking and their email is already filled in when they need you.
window.deaconUserPass their plan
Send details such as their plan or role, and Deacon takes them into account when it answers.
Deacon.setContext
Make a key and make your first call
Make a key
On Integrations, choose what it can do.
Read the docs
The API docs have every route, with examples.
Call it
Here’s a release script re-reading one page.
curl -X POST https://heydeacon.com/api/v1/knowledge/t7dkqm3p/refetch \
-H "Authorization: Bearer $DEACON_API_KEY"Pair it with webhooks, your agent or a CSV
Webhooks
Hear as soon as something happens, instead of asking every few minutes.
visitor.left_emailMCP server
Your coding agent reads the same chats from your terminal.
search_conversationsChat transcripts
Need a copy without writing code? Export a CSV from Conversations.
Chat ID, Time, From, Message, Page
Make a key and try it
Add Deacon to your site, make a key on Integrations and call the API from your terminal. You get 50 answers a month on the free plan, and it needs no card.
What to look for in a live chat API
These hold whichever chat tool you’re looking at.
Reading is the easy part
Most APIs let you list chats. Check whether yours can also add to what the bot knows, since that’s what keeps its answers right.
A reply should do what your own reply does
If a reply from your code doesn’t take the chat over or reach the customer the same way, you’ve got two kinds of reply to explain.
Failed calls should say why
A refusal you can read and branch on saves you an afternoon. Try one with a bad id before you commit.
FAQ
Questions about the live chat API
No. The API works with your chats and what Deacon knows, and Deacon only answers in the chat on your site. If you’re building your own chatbot, this isn’t the tool for that.
Yes, as whoever made the key. It takes the chat over, as a reply from the dashboard does, until you hand it back.
Yes. A change made through the API does what the dashboard does, with the same plan limits.
Your team’s keys can make 300 calls a minute between them, and a key made for a coding agent up to 60. We add new things as we go. If anything ever has to be renamed or removed, the old version keeps working for at least six months, and every owner gets an email first.
A Read key can see the email they left and look chats up by email. So keep that key out of anything public.
Let your scripts do the remembering
It takes about five minutes to install. The free plan is 50 answers a month, for as long as you like.