AddoChat voor ontwikkelaars

AddoChat is een add-on van de gratis plugin AddoBase. AddoBase regelt de licentie en de updates; AddoChat start zijn functies alleen zolang de licentie op de site actief is. Persoonsgegevens exporteren en wissen werkt altijd, ook zonder licentie.

Hoe een chat loopt

1. De pagina laadt een klein launcher-script. Verder laadt er niets, en de HTML bevat geen nonce of gebruikersgegevens, dus full-page caching blijft werken.
2. Bij de eerste klik laadt de chat in een Shadow DOM, zodat thema-stijlen er niet in lekken.
3. Elk bericht gaat naar POST /wp-json/addochat/v1/chat met een ondertekend gesprekstoken. Eerst lopen de origin-check en de limieten (30 per gesprek, 20 per bezoeker per uur, 2000 AI-antwoorden per site per dag, allemaal aan te passen).
4. De assistent antwoordt: Webhook (elke dienst, contract in webhook.md), Direct (Claude, ChatGPT, Gemini of een OpenAI-compatibele dienst, met tools; kies het model of vul je eigen model in en klik op Verbinding testen) of Uit (alleen collega's).
5. Neemt een collega over, dan vraagt de widget nieuwe berichten op; die vraag wordt beantwoord voordat WordPress plugins en thema laadt.
6. Een collega kan eigen antwoorden achteraf aanpassen (beweeg over het antwoord en klik op het potlood, of druk op pijl omhoog in een leeg antwoordveld). De bezoeker ziet de nieuwe tekst met "bewerkt" eronder; de inbox bewaart de vorige tekst. Een beheerder kan de antwoorden van elke collega aanpassen.
7. De knop met het pijltje in de kop van een chat opent die chat in een eigen klein venster, zonder de lijst en het beheermenu. Zo houd je een paar chats naast elkaar of naast een bestelling. Nog een keer klikken haalt het venster naar voren. Schrijft de bezoeker terwijl het venster achter andere vensters staat, dan knippert de titel en brengt een bureaubladmelding (als die mag) het venster terug. Met Addofy heeft het venster de kleuren van Addofy en de lichte of donkere modus, zonder menu en balken. Zonder Addofy is het een kale pagina met alleen de chat (je site met ?addochat_chat=1#<gespreks-id>), zodat hij snel opent. Op een telefoon en in dit venster zijn de knoppen in de kop iconen en open je de klantgegevens met de kaartknop.
8. Bestellingen, producten, klanten en pagina's die de assistent opzocht, of die de bezoeker noemde ("bestelling #1234", een e-mailadres van een klant), staan als link: onder het antwoord dat ze gebruikte en in het infoblok onder In deze chat. Met Addofy opent een link in het drawer. Zonder het recht om het object te bewerken zie je de naam zonder link. Met het filter addochat_ref_link pas je een link aan of verberg je hem.

Waar alles staat

De chats staan in het menu Chats; het tabblad Nu actief toont elk gesprek met een bericht in de laatste 15 minuten, bij de assistent of bij een collega. Desktopmeldingen: zonder Addofy de knop in de inbox; met Addofy versturen de Meldingen van Addofy ze, volgens de voorkeur in je profiel. De instellingen (met de tabbladen Widget, Assistent, Live chat, Koppelingen, Limieten en privacy, en Netwerk; elk tabblad bewaart zijn eigen velden) zijn het item AddoChat in de AddoBase-sectie onderaan het menu als Addofy actief is, na AddoBase en Addofy, en anders Instellingen > AddoChat.

Regels

Onder AddoChat > Regels stel je vaste antwoorden in zonder de assistent: voorwaarden (het bericht bevat woorden, alleen het eerste bericht, het pad van de pagina, de taal, open of gesloten, ingelogd of niet; kies er een uit de lijst en klik op Toevoegen; alles moet kloppen of een ervan, en er kan een groep voorwaarden in, tot drie niveaus diep) acties (stuur een vast antwoord, geef de assistent een extra instructie voor dat bericht, laat de assistent antwoorden, bied een collega aan; net zo toe te voegen en uitgevoerd in hun volgorde). Regels lopen van boven naar beneden, vóór de assistent; de eerste die past wint. Een vast antwoord kost geen AI-aanroep en kan knoppen eronder hebben. De assistent antwoordt alleen na een extra instructie of "Laat de assistent antwoorden"; een collega aanbieden sluit de regel altijd af. Met "Zin testen" zie je welke regel antwoordt. Met Addofy (2.36.0 of later) sleep je regels aan hun greep naar een andere plek; de knoppen omhoog en omlaag werken altijd. In de inbox staat bij een vast antwoord welke regel het stuurde. Regels gaan mee naar gekoppelde sites, net als de andere instellingen. Eigen voorwaarden: filter addochat_rule_matches.

Producten in de winkelwagen

Met WooCommerce kan de assistent een product in de winkelwagen van de bezoeker doen (tool "Add to cart" onder Assistent > Tools). De instelling "Add to cart" kiest hoe: de bezoeker vragen (een kaartje met een knop In winkelwagen) of meteen toevoegen (met een knop Ongedaan maken). Producten met opties om te kiezen, of die uitverkocht zijn, linken alleen naar hun pagina. Regels doen hetzelfde zonder AI, met de actie "Producten in de winkelwagen": op id, SKU of naam, waarbij * voor elke tekst staat (MOK-* of *koffie*), de eerste die past of allemaal (maximaal 5); of "Uit het bericht", dat neemt wat de * van een voorwaarde "bevat" vond ("voeg * toe"; "voeg 2 mokken toe" doet er 2 mokken in). Geen product gevonden: de assistent antwoordt. Met "Zin testen" zie je welke producten een regel vindt. De widget voegt toe via de WooCommerce Store API in de browser van de bezoeker en ververst de mini-winkelwagen van het thema; de inbox toont wat er werd aangeboden en of het erin ging. Hooks: filter addochat_cart_item, action addochat_added_to_cart, JS-event addochat:added-to-cart.

Bezoekers volgen

Onder Instellingen > Limieten en privacy toont "Bezoekers volgen" collega's welke pagina's een bezoeker bekeek. Uit, Na toestemming (standaard) of Altijd. Een klein script (visits.js, alleen waar de chat staat) stuurt elk paginabezoek met navigator.sendBeacon() naar POST addochat/v1/visit en daarna elke 30 seconden een hartslag zolang de tab zichtbaar is. Met Na toestemming wacht het op de WP Consent API (categorie Statistieken, of Marketing) of op je eigen banner: roep AddoChatVisits.consent( true ) aan op elke pagina waar de bezoeker akkoord gaf, false om te stoppen. Zonder toestemming wordt niets opgeslagen tot de bezoeker de chat opent; de route begint dan op die pagina en de sleutel leeft alleen in die tab.

Als de chat opent, krijgt het gesprek een notitie met de pagina's ervoor en de minuten op de site; elke volgende pagina voegt "Ging naar" toe. Notities komen nooit in de widget. De kop van het gesprek toont "Nu op" met een groene stip zolang de laatste hartslag jonger is dan een minuut. Het tabblad Live bezoekers toont iedereen die de laatste vijf minuten op deze site was, met pagina, aantal pagina's, minuten, de klant als die ingelogd is, en Open chat als er een chat is.

Opgeslagen per paginabezoek: een willekeurige sleutel uit de browser (localStorage addochat_vk), een willekeurig bezoek-id, het adres zonder fragment en zonder key, token, utm_* en vergelijkbare argumenten, de titel, de verwijzer zonder query, en de tijden. Geen IP-adres, geen user agent. Bezoeken zonder chat blijven het aantal dagen van Privacy > Routes bewaren staan (standaard 30); bezoeken van een chat gaan mee met de chat. Een gekoppelde site bewaart zijn eigen bezoeken en stuurt de routenotities naar de centrale site. Hooks: addochat_tracking_allowed, addochat_visit_url, addochat_visit_recorded.

Chats op je telefoon

Onder Instellingen > Live chat geeft "Chats op telefoon en tablet" de inbox een eigen adres (standaard uit; addochat-app tenzij je een ander kiest). In het scherm Chats toont "Op je telefoon" het adres en de toestellen die je toevoegde. Open het op de telefoon of tablet en log één keer in ("Onthoud mij" staat al aangevinkt).

• iPhone en iPad (iOS 16.4 of later): open het in Safari, tik op Deel, kies Zet op beginscherm en open Chats vanaf het beginscherm. Apple stuurt alleen meldingen naar een app op het beginscherm.
• Android: open het in Chrome en tik op Installeren (meldingen werken ook zonder installeren).

In de app zet Meldingen ze aan voor dat toestel. Per toestel: een chat wacht op een collega, een bezoeker schrijft in mijn chat, alleen als ik online sta, en de tekst van het bericht (standaard uit, dan toont het vergrendelscherm alleen "Nieuw bericht van een bezoeker"). Een tik opent dat gesprek; het app-icoon toont het aantal wachtende en ongelezen chats. Zolang de app in beeld is, krijgt het toestel geen melding. Een collega die online staat en een toestel heeft voor wachtende chats, telt voor bezoekers als online, ook zonder open scherm. Push werkt alleen op een site met een geldig HTTPS-certificaat.

Het adres wordt nooit geïndexeerd: noindex in de header en de pagina, een regel Disallow in robots.txt, in geen enkele sitemap, en zonder inloggen is er alleen het inlogscherm. De app uitzetten haalt het adres en alle toegevoegde toestellen weg. Hooks: filter addochat_push_payload, action addochat_push_sent, filter addochat_app_url.

Laag

De chatknop ligt op z-index 9999, onder de meeste cookiebanners (Cookiebot, Complianz, CookieYes), zodat een bezoeker de banner altijd eerst kan beantwoorden. Ligt je banner lager, of iets anders van je thema? Zet de laag met de CSS-variabele --addochat-z, bijvoorbeeld html { --addochat-z: 500; }.

De chat opent, sluit en toont berichten met korte animaties (onder 300 ms, alleen doorzichtigheid en verplaatsing). Staat "minder beweging" aan in het besturingssysteem, dan blijven alleen korte fades over.

Zit de bezoeker in een andere tab als er een antwoord binnenkomt, dan staat in de paginatitel "(1) Nieuw bericht". Terug in de tab is de titel weer gewoon. Uitzetten kan onder Weergave, "Nieuw bericht in de tabtitel". Je thema kan luisteren naar het event addochat:unread op window (event.detail.count) om het op een eigen manier te tonen. De inbox doet hetzelfde voor collega's: het getal in de titel telt wachtende chats en, vanuit een andere tab, nieuwe berichten in chats die je hebt overgenomen.

Wat het opslaat

• Gesprekken en berichten in {prefix}addochat_conversations en {prefix}addochat_messages.
• Paginabezoeken (als bezoekers volgen aan staat) in {prefix}addochat_visits.
• Toestellen van de mobiele app in {prefix}addochat_push; het sleutelpaar voor push in addochat_push_keys (niet autoloaded).
• Instellingen in addochat_settings; de samengevoegde instellingen die de widget leest in addochat_effective (autoload, nooit met geheimen).
• Geheimen (webhook-secret, API-sleutel, Missive-token) kunnen ook uit een constante of omgevingsvariabele ADDOCHAT_<KEY> komen.

Er wordt niets verwijderd als een licentie afloopt. Bewaartermijn en export staan in privacy.

Agents en tools

De tools search_products, get_product, lookup_order, get_my_account, get_current_page en request_human zijn beschikbaar via MCP op /wp-json/addochat/v1/mcp en als gewone REST. Sleutels maak je onder AddoChat > Koppelingen. Een n8n-workflow om mee te beginnen zit bij de plugin: examples/n8n-workflow.json in de pluginmap (importeren in n8n). Zie mcp.md en webhook.md.

Wat de assistent van een pagina leest

Met de tool get_current_page (Pagina van de bezoeker) leest de assistent de pagina waar de bezoeker op is als die ernaar vraagt: "wat moet ik bij stap 3 doen?" op een docs-pagina. Hij leest alleen gepubliceerde pagina's zonder wachtwoord, van de typen onder AI > Pagina's die de assistent mag lezen (standaard elk openbaar type behalve producten en media), maximaal 6000 tekens. Producten gaan via get_product. Collega's zien dezelfde tekst in de inbox onder Pagina-inhoud. Inhoud toevoegen of weglaten kan met het filter addochat_page_context.

Bijwerken vanaf 0.1.0: de tool staat uit tot je hem aanvinkt onder AI > Tools.

Een eigen tool voeg je toe met de filter addochat_tools; met addochat_order_by_number vindt lookup_order bestellingen op een eigen bestelnummer.

Meerdere sites

Eén centrale site heeft de instellingen en de inbox; gekoppelde sites sturen hun chats daarheen. Zie network.md.

Met Addofy

Met Addofy actief gebruikt AddoChat alleen de publieke API: chats in de zoekfunctie van het command palette (adba_search_providers), commando's (adba_commands), de chats van een bestelling in de snelle acties (adba_order_quick_actions), recente chats bij de klant (adba_customer_detail_side), wachtende chats in Vandaag en in de meldingen, uitleg op de schermen, en stijlen op de --adba-*-tokens. Gereedschap > Content exporteert en importeert de regels, de gesprekken en de bezoekersroutes onder Andere onderdelen (adba_transfer_register_sources): met een voorbeeld, een keuze per item en ongedaan maken. Gesprekken en routes zijn persoonsgegevens, dus een andere site kan ze niet met een sleutel ophalen, en een geïmporteerd gesprek komt gesloten binnen. Zonder Addofy werken het menu Chats en Instellingen > AddoChat precies zo.

Zie ook

• Hookreferentie