AddoChat for developers

AddoChat is an add-on of the free AddoBase plugin. AddoBase handles the license and updates; AddoChat only starts its features while the license is active on the site. Export and erase of personal data always work, also without a license.

How a chat runs

1. The page loads a small launcher script. Nothing else loads, and the page HTML holds no nonce or user data, so full-page caching keeps working.
2. On the first click the chat loads in a Shadow DOM, so theme styles do not leak in.
3. Every message goes to POST /wp-json/addochat/v1/chat with a signed conversation token. Origin check and rate limits (30 per conversation, 20 per visitor per hour, 2000 AI answers per site per day, all adjustable) run first.
4. The assistant answers: Webhook (any service, contract in webhook.md), Direct (Claude, ChatGPT, Gemini or an OpenAI compatible service, with tools; pick the model or fill in your own, then press Test connection) or Off (only colleagues).
5. When a colleague takes over, the widget polls for new messages; that poll is answered before WordPress loads plugins and themes.
6. A colleague can edit their own answers afterwards (hover the answer and click the pencil, or press the up arrow in an empty reply field). The visitor sees the new text with "edited" below it; the inbox keeps the earlier text. An administrator can edit the answers of every colleague.
7. The button with the arrow in the head of a chat opens that chat in a small window of its own, without the list and the admin menu. Keep a few chats next to each other or next to an order. Clicking again brings the window to the front. When the visitor writes while the window is behind others, its title blinks and, with desktop notifications allowed, a notification brings it back. With Addofy the window has Addofy's colours and its light or dark mode, without the menu and bars. Without Addofy it is a plain page with only the chat (your site with ?addochat_chat=1#<conversation id>), so it opens quickly. On a phone and in this window the buttons in the head are icons, and the customer details open from the card button.
8. Orders, products, customers and pages the assistant looked up, or that the visitor named ("order #1234", an email address of a customer), show as links: under the answer that used them and in the info block under In this chat. With Addofy a link opens in its drawer. Without the right to edit the object you see the name without a link. The filter addochat_ref_link changes or hides a link.

Where things are

The chats are in the menu Chats; the tab Live now shows every conversation with a message in the last 15 minutes, with the assistant or a colleague. Desktop notifications: without Addofy the button in the inbox; with Addofy its Notifications send them, by the preference in your profile. The settings (with the tabs Widget, Assistant, Live chat, Connections, Limits and privacy, and Network; each tab saves its own fields) are the item AddoChat in the AddoBase section at the bottom of the sidebar when Addofy is active, after AddoBase and Addofy, and under Settings > AddoChat without it.

Rules

Under AddoChat > Rules you set fixed answers without the assistant: conditions (the message contains words, only the first message, the page path, the language, open or closed, logged in or not; pick one from the list and click Add; all must hold or one of them, and a group of conditions can sit inside, up to three levels deep) actions (send a fixed answer, give the assistant an extra instruction for that message, let the assistant answer, offer a colleague; added the same way and carried out in their order). Rules run from top to bottom before the assistant; the first that matches wins. A fixed answer costs no AI call and can have buttons below it. The assistant only answers after an extra instruction or "Let the assistant answer"; offering a colleague always ends the rule. "Test a sentence" shows which rule answers. With Addofy (2.36.0 or later) you drag rules by their grip to change the order; the up and down buttons always work. In the inbox a fixed answer says which rule sent it. Rules go along to linked sites like the other settings. Own conditions: filter addochat_rule_matches.

Products in the cart

With WooCommerce the assistant can put a product in the cart of the visitor (tool "Add to cart" under Assistant > Tools). The setting "Add to cart" chooses how: ask the visitor (a card with an Add to cart button) or add directly (with an Undo button). Products with options to choose, or out of stock, only link to their page. Rules can do the same without AI, with the action "Put products in the cart": by id, SKU or name, where * stands for any text (MUG-* or *coffee*), the first match or all of them (at most 5); or "From the message", which takes what the * of a "contains" condition matched ("add * to my cart"; "add 2 mugs to my cart" puts 2 mugs in). No product found: the assistant answers. "Test a sentence" shows which products a rule finds. The widget adds through the WooCommerce Store API in the browser of the visitor and refreshes the mini cart of the theme; the inbox shows what was offered and whether it went in. Hooks: filter addochat_cart_item, action addochat_added_to_cart, JS event addochat:added-to-cart.

Following visitors

Under Settings > Limits and privacy, "Follow visitors" shows colleagues which pages a visitor viewed. Off, After consent (the default) or Always. A small script (visits.js, only where the chat shows) sends each page view with navigator.sendBeacon() to POST addochat/v1/visit and then a heartbeat every 30 seconds while the tab is visible. With After consent it waits for the WP Consent API (category Statistics, or Marketing) or for your own banner: call AddoChatVisits.consent( true ) on every page where the visitor accepted, false to stop. Without consent nothing is stored until the visitor opens the chat; the route then starts on that page and the key lives in that tab only.

When the chat opens, the conversation gets a note with the pages before and the minutes on the site; every next page adds "Went to". Notes never reach the widget. The conversation header shows "Now on" with a green dot while the last heartbeat is younger than a minute. The tab Live visitors lists everyone on this site in the last five minutes, with page, pages, minutes, the customer when logged in, and Open chat when there is a chat.

Stored per page view: a random key from the browser (localStorage addochat_vk), a random view id, the address without fragment and without key, token, utm_* and similar arguments, the title, the referrer without query, and the times. No IP address, no user agent. Views without a chat are kept for the days of Privacy > Keep routes (30 by default); views of a chat go with the chat. A linked site keeps its own views and sends the route notes to the central site. Hooks: addochat_tracking_allowed, addochat_visit_url, addochat_visit_recorded.

Chats on your phone

Under Settings > Live chat, "Chats on phone and tablet" gives the inbox an address of its own (off by default; addochat-app unless you choose another). On the Chats screen, "On your phone" shows the address and the devices you added. Open it on the phone or tablet and log in once ("Remember me" is ticked for you).

• iPhone and iPad (iOS 16.4 or later): open it in Safari, tap Share, choose Add to Home Screen and open Chats from the home screen. Apple only sends notifications to an app on the home screen.
• Android: open it in Chrome and tap Install (notifications also work without installing).

In the app, Notifications turns them on for that device. Per device: a chat waits for a colleague, a visitor writes in my chat, only while I am online, and the message text (off by default, so the lock screen shows only "New message from a visitor"). A tap opens that conversation; the app icon shows the number of waiting and unread chats. While the app is in view the device gets no notification. A colleague who is switched online and has a device for waiting chats counts as online for visitors, also without a screen open. Push only works on a site with a valid HTTPS certificate.

The address is never indexed: noindex in the header and the page, a Disallow line in robots.txt, not in any sitemap, and without a login there is only the login screen. Switching the app off removes the address and every added device. Hooks: filter addochat_push_payload, action addochat_push_sent, filter addochat_app_url.

Layering

The chat button sits at z-index 9999, below most cookie banners (Cookiebot, Complianz, CookieYes), so visitors can always answer the banner first. Is your banner lower, or something else of your theme? Set the layer with the CSS variable --addochat-z, for example html { --addochat-z: 500; }.

The chat opens, closes and adds messages with short animations (under 300 ms, only opacity and transform). With "reduce motion" on in the operating system only short fades remain.

Is the visitor in another tab when an answer comes in, the page title shows "(1) New message". Back in the tab, the title is normal again. Turn it off under Display, "New message in the tab title". Your theme can listen to the addochat:unread event on window (event.detail.count) to show it its own way. The inbox does the same for colleagues: the number in its title counts waiting chats and, from another tab, new messages in chats you took over.

What it stores

• Conversations and messages in {prefix}addochat_conversations and {prefix}addochat_messages.
• Page views (when following visitors is on) in {prefix}addochat_visits.
• Devices of the mobile app in {prefix}addochat_push; the key pair for push in addochat_push_keys (not autoloaded).
• Settings in addochat_settings; the merged settings the widget reads in addochat_effective (autoloaded, never with secrets).
• Secrets (webhook secret, API key, Missive token) can come from a constant or environment variable ADDOCHAT_<KEY> instead.

Nothing is deleted when a license ends. Retention and export are in privacy.

Agents and tools

The tools search_products, get_product, lookup_order, get_my_account, get_current_page and request_human are offered over MCP at /wp-json/addochat/v1/mcp and as plain REST. Keys are made under AddoChat > Connections. An n8n workflow to start from ships with the plugin: examples/n8n-workflow.json in the plugin folder (import it in n8n). See mcp.md and webhook.md.

What the assistant reads of a page

With the tool get_current_page (Page of the visitor) the assistant reads the page the visitor is on when they ask about it: "what do I do at step 3?" on a docs page. It reads only published pages without a password, of the types under AI > Pages the assistant may read (default every public type except products and media), at most 6000 characters. Products go through get_product. Colleagues see the same text in the inbox under Page content. Add or leave out content with the filter addochat_page_context.

Updating from 0.1.0: the tool is off until you tick it under AI > Tools.

Add your own tool with the filter addochat_tools; let lookup_order find orders by a custom order number with addochat_order_by_number.

Several sites

One central site holds the settings and the inbox; linked sites send their chats there. See network.md.

With Addofy

When Addofy is active, AddoChat uses its public API only: chats in the command palette search (adba_search_providers), commands (adba_commands), the chats of an order in the quick actions (adba_order_quick_actions), recent chats on the customer screen (adba_customer_detail_side), waiting chats in Today and in the alerts, guides, and styles on the --adba-* tokens. Tools > Content exports and imports the rules, the conversations and the visitor routes under Other items (adba_transfer_register_sources): with a preview, a choice per item and undo. Conversations and routes are personal data, so another site cannot fetch them with a key, and an imported conversation arrives closed. Without Addofy the menu Chats and Settings > AddoChat work the same.

Related

• Hook reference