AcornReply API

Add live chat to your site

Paste this snippet and a chat bubble appears in the bottom-right of every page. Visitors start a conversation, the messages land in your AcornReply inbox, and the replies your team sends show up in the widget in real time — even after the visitor closes and reopens it.

Copy it — with your workspace's key already filled in — from Settings → Channels → Live chat in the app. That's the whole drop-in. To control the widget from JavaScript — your own button, or identifying visitors — add one small line to this snippet, shown in the next two sections.

A floating bubble opens a chat card; on phones it becomes a full-screen sheet.

Replies arrive over a live connection, an unread badge sits on the bubble, and the widget follows the visitor's light/dark system theme.

One conversation per visitor, resumed across page loads — closing the card never drops the thread.

Styling is no-code. The bubble icon, its light and dark colors, the chat header logo, and the greeting and first message are all set under Settings → Appearance in the app — you don't edit them here. This page covers only the code-level integration: where the snippet goes and how to drive the widget from your own UI.

<script src="https://acornreply.com/embed/YOUR_KEY.chat.js" async></script>

Hide the chat bubble

Prefer to launch chat from your own "Contact us" button, a nav link, or an existing component instead of the default bubble? Hide the built-in bubble and drive the widget yourself with a small browser-side API. This is all client-side JavaScript; it does not touch the REST API.

The examples below add one line above the script tag — a tiny stub that defines window.AcornReply up front so your calls are safe to make the moment the page loads, before the widget has finished loading.

Hide the bubble and wire your own element

Add data-hide-button to the script tag to suppress the built-in floating bubble. The chat card and the control API still load, so any element on your page — an existing button, a menu item, your own React or Vue component — can open it. Listen for the acorn:chat-state event to keep your trigger in sync when the visitor closes the card from inside it or presses Escape.

<script>
  window.AcornReply = window.AcornReply || function () { (window.AcornReply.q = window.AcornReply.q || []).push(arguments) }
</script>
<!-- data-hide-button hides the default bubble; the card + API still load -->
<script src="https://acornreply.com/embed/YOUR_KEY.chat.js" data-hide-button async></script>

<button id="help" type="button" aria-expanded="false">Need help?</button>
<script>
  const help = document.getElementById("help")
  help.addEventListener("click", () => AcornReply("toggle"))

  // detail.open is true when the card is open, false when it closes —
  // including closes the visitor triggers from inside the chat or via Escape.
  window.addEventListener("acorn:chat-state", (e) => {
    help.setAttribute("aria-expanded", String(e.detail.open))
  })
</script>

Control the widget (JS API)

The control API

The public entry point is a single global function, window.AcornReply(command):

There's one more command, AcornReply("identify", traits), for telling AcornReply who the visitor is — see Identify your visitors below.

When do you need destroy? If you drop the script tag on your site once, never — the widget is meant to live for the whole page. Reach for it only when your own code injected the script and now has to take it back out, namely:

a single-page app (React, Vue, etc.) that mounts the embed on some routes and removes it on others — call destroy in your component's unmount/cleanup;

pulling the widget after the visitor withdraws cookie or chat consent.

It's needed because the script installs once and ignores a second injection while it's live, so removing the <script> tag alone leaves the widget on the page; destroy clears the DOM, the listeners, and window.AcornReply itself. It does not end the conversation — the visitor's chat resumes if you load the widget again later.

Pin the color scheme

Pin the color scheme

The bubble and card colors come from your workspace appearance settings, but the light/dark scheme follows the visitor's system theme by default. To lock it to one scheme, add ?theme=light or ?theme=dark to the script URL, or set data-theme on the tag.

<!-- Always dark, regardless of the visitor's system setting -->
<script src="https://acornreply.com/embed/YOUR_KEY.chat.js?theme=dark" async></script>

<!-- Equivalent, as an attribute -->
<script src="https://acornreply.com/embed/YOUR_KEY.chat.js" data-theme="dark" async></script>

Let AI write the setup

Prefer to let AI write it?

Not a developer? Paste the prompt below into ChatGPT, Claude, or any AI assistant, fill in the one blank describing what you want, and it will write the exact snippet to add to your site. The prompt already contains everything the assistant needs to know about the widget's API, so you don't have to explain it.

I use AcornReply's live chat widget on my website. I install it with this snippet:
<script>
  window.AcornReply = window.AcornReply || function () { (window.AcornReply.q = window.AcornReply.q || []).push(arguments) }
</script>
<script src="https://acornreply.com/embed/MY_KEY.chat.js" async></script>

This JavaScript API is available on the page via the global function
window.AcornReply(command, payload). The install snippet defines it up front, so
it is safe to call any time — even on page load — without waiting for anything:
- AcornReply("open")    -> open the chat
- AcornReply("close")   -> close the chat (the conversation keeps running)
- AcornReply("toggle")  -> open if closed, close if open
- AcornReply("destroy") -> remove the widget entirely
- AcornReply("identify", { email, name, externalId, plan }) -> tell AcornReply who the visitor is
- Add the attribute  data-hide-button  to the second <script> tag to hide the
  default chat bubble so I can trigger the chat from my own button instead.
- Listen for the  "acorn:chat-state"  event on window; event.detail.open is true/false
  and tells me whether the chat is currently open.
- Add  ?theme=light  or  ?theme=dark  to the script URL to lock the color scheme.

What I want: ______________________________________________
(for example: "open the chat when someone clicks my 'Contact us' button",
 or "open the chat automatically 20 seconds after someone lands on my pricing page")

Give me the complete HTML and JavaScript to paste into my site, and tell me exactly
where on the page each piece goes.

Identify your visitors

If you already know who a visitor is, tell AcornReply with one call so the chat skips the email prompt and your agents see them — email, name, and any attributes you send — in the sidebar. Call AcornReply("identify", ...) as soon as you know who they are — on page load or later, after a client-side login. The same call covers both: it's safe any time. Identity is applied when the visitor opens the chat and isn't stored between page loads, so include the call on each page.

Reserved keys: email, name, and externalId (also accepted as external_id) become identity fields. Any other key with a primitive value (string, number, boolean) becomes sidebar metadata. These values come from the browser and are unverified — treat them with the same trust as an email the visitor types themselves.

<script>
  window.AcornReply = window.AcornReply || function () { (window.AcornReply.q = window.AcornReply.q || []).push(arguments) }
</script>
<script src="https://acornreply.com/embed/YOUR_KEY.chat.js" async></script>

<script>
  // Call as soon as you know who the visitor is — on page load or after login.
  AcornReply("identify", {
    email: "[email protected]",
    name: "Ada Lovelace",
    externalId: "u_123",
    plan: "Pro",
  })
</script>

Connect an AI agent (MCP)

The knowledge base API is also available as a remote MCP server at https://mcp.acornreply.com — the same entries and search tools as the REST API, including set_published to publish or unpublish an entry, plus full category management (list_categories, create_category, update_category, delete_category, reorder_categories) and images (upload_image, create_image_upload, finalize_image_upload) for hosting images, exposed to any MCP client. It works with any MCP client that supports remote servers with a custom auth header: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, and more.

Authenticate the same way as the REST API: a workspace API key as a Bearer token in the Authorization header. The fastest way to connect is the Claude Code CLI:

claude mcp add --transport http acorn-reply \
  https://mcp.acornreply.com \
  --header "Authorization: Bearer ak_YOUR_KEY"

Connect any other MCP client

Clients that read a JSON config instead of a CLI (Claude Desktop, Cursor, Windsurf, VS Code, and others) use the same URL and header — add this to the client's mcpServers configuration:

{
  "mcpServers": {
    "acorn-reply": {
      "url": "https://mcp.acornreply.com",
      "headers": { "Authorization": "Bearer ak_YOUR_KEY" }
    }
  }
}

Tools

The MCP server exposes the same knowledge base operations as the REST API, grouped into tool families that map onto the resources below: search (search_kb), entries (create/list/get/update/delete, plus set_published to publish or unpublish), categories (create/list/update/delete/reorder), images (upload_image, create_image_upload, finalize_image_upload), format (get_format_guide) for the content-format contract, and analytics (article_stats) for per-article help-center view stats.