B Blengi docs

De widget insluiten

Snippet installeren

De widget bestaat uit één enkele <script>-tag. Zet hem op een willekeurige pagina, voer een agent-ID in, en je bent klaar. De bundel is ≤50KB (gzipped), draait in een Shadow DOM zodat je site er geen stijl aan kan toekennen, en blokkeert nooit het laden van de pagina (het is async).

Controleer de installatie

Op de Website-pagina van de AI-medewerker opent Controleer installatie de startpagina van je site en vertelt je meteen: het script is aanwezig; of het is aanwezig met het oude adres /widget/widget.js, dus plak de huidige installatiecode (het oude adres blijft werken totdat je dat doet); of de widget is de afgelopen dag op je site geladen (via een tagmanager of een plug-in); of het is nog niet gevonden, met wat je dan moet doen. De controle noteert ook het platform van je site (WordPress, WooCommerce, Shopify en andere) voor de stappen in de installatiehandleiding en de aanbevolen plaatsen voor het inline blok. Stuur de installatiehandleiding in je eigen huisstijl naar mijn webontwikkelaar.

Het fragment

Plak dit vlak voor </body>:

<script src="https://blengi.com/w/widget.js?v=97e3674e6b4d" data-agent-id="YOUR-AGENT-ID" async></script>

Als je bent ingelogd, is dit je eigen snippet, met je agent-ID en de huidige cache-bust-hash ingevuld. Hetzelfde snippet, met een kopieerknop, staat op het tabblad Website van elke AI-medewerker onder ‘Code installeren’.

Twee optionele attributen

  • data-mount="manual" — laad dit, maar doe niets totdat window.AIAssistant.mount() wordt aangeroepen; hoe een toestemmingsbanner de chat regelt.
  • data-context-global="blengiContext" — de naam van een globale variabele window die je pagina’s vullen met hun eigen context (paginatype, categorie, het product op het scherm).
  • data-launcher="none" — je hebt je eigen chatknop; toon geen zwevende launcher van ons. Open het paneel met window.AIAssistant.open().

Zowel de JavaScript-API (open , send , close , setContext ) als de lijst met wat de widget opslaat, staan op de Widget API -pagina.

Stuur het naar je webontwikkelaar

Wordt de website door iemand anders gebouwd? Onder Website › Code installeren stuurt ‘Stuur naar mijn webontwikkelaar’ de link naar de installatiehandleiding van de AI-medewerker, eventueel met een opmerking; je krijgt een antwoord terug. ‘Link kopiëren’ en ‘Handleiding openen’ geven dezelfde link.

De handleiding bestaat uit één pagina zonder inlog, alleen voor de installatie: het fragment hierboven met een kopieerknop, de stappen voor het platform van de site (WordPress, Shopify, Wix, Squarespace, Webflow, Google Tag Manager of een andere site; het platform wordt automatisch herkend aan de hand van de site waarop de AI-medewerker wordt als eerste geopend), het optionele inline-blok en een vinkje dat aangeeft of de chat in de afgelopen 30 dagen op een van de websites van de AI-medewerker is geladen. Er wordt verder niets geopend: geen dashboard, geen gesprekken. Een klant van een bureau krijgt de handleiding in de naam, met het logo en in de kleuren van het bureau. Een nieuwe link geeft de gids een nieuw adres; de oude link geeft dan aan dat deze niet meer beschikbaar is. Een werkruimte en een persoon sturen elk maximaal 20 gidsen per dag, en de notitie mag geen links bevatten: de gids is de enige link in de e-mail. De naam van je eigen website mag in het bericht staan („Stappsokken.nl“), zolang het maar een van de adressen is waarop je AI- medewerker is geïnstalleerd; de e-mail schrijft het zo dat geen enkel e-mailprogramma er een link van maakt. Een webadres met https:// , een ander domein of een e-mailadres wordt nog steeds geweigerd.

Is er geen gids aangekomen? Kijk dan eerst even in de spamfolder van de ontvanger. Elke e-mail die het platform aan zijn mailserver doorgeeft, wordt geregistreerd met de tijd, het onderwerp en het domein van de ontvanger (nooit het adres), zodat het platformteam het kan volgen in het bezorglogboek van de e-mailprovider.

Laat ons het installeren

Liever niet zelf het codefragment plakken? Onder Website › Code installeren vraagt ‘Laat ons het installeren’ om de website, het platform waarop deze draait en een contactpersoon (naam, e-mail, een optioneel telefoonnummer en opmerking). Er wordt nooit om een wachtwoord gevraagd: op WordPress maak je een gebruiker voor ons aan, op Shopify accepteer je ons verzoek om samen te werken. Je bevestigt dat met een vinkje.

  • Het verzoek verschijnt onder Mijn rapporten als Installatiehulp; statuswijzigingen en reacties ontvang je via e-mail, en op de Website-pagina zie je hoe ver het is. Eén openstaand verzoek per AI-medewerker.
  • Het is gratis, tenzij je abonnement installatiekosten heeft; dan wordt dat op het formulier vermeld en moet je daar eerst mee akkoord gaan. De factuur volgt zodra het is geïnstalleerd.
  • Een klant van een bureau vraagt het bureau, dat het in eigen naam installeert; de prijs van het platform geldt dan niet.
  • Een AI-medewerker die via een persoonlijke demo is binnengekomen, behoudt zijn eigen 'Installeer het voor mij'-optie met één klik.

Het inline-blok

Naast de zwevende launcher geeft hetzelfde script de agent weer binnen een pagina, waar dit blok ook wordt geplakt — een WordPress Aangepast HTML-blok, een sjabloon, waar dan ook:

<div data-ai-assistant-inline></div>

Er komt verder niets op de site. Tekst, lay-out en kleuren worden beheerd onder Weergave › Inline-blok; het fragment met een kopieerknop staat onder Website › Installatiecode › Inline-blok (optioneel). Details, attributen per blok en de CSS-hooks voor agentschappen: Inline embed.

Implementeren via Google Tag Manager

De widget kan worden toegevoegd als een Aangepaste HTML-tag in Google Tag Manager in plaats van in de sjabloon van de site — een veelvoorkomend verzoek wanneer een marketingbureau eigenaar is van de container en de site zelf moeilijk te bewerken is. Zet in een tagmanager de agent-id in de script-URL, niet in een data--attribuut:

<script src="https://blengi.com/w/widget.js?agent=YOUR-AGENT-ID" async></script>

Gebruik een ‘Alle pagina’s (paginaweergave)’-trigger. Verder hoef je niets in te stellen. Als je bent ingelogd, is de bovenstaande id die van jou; op het tabblad Website van de AI-medewerker staat precies hetzelfde fragment, onder ‘Google Tag Manager’ naast de normale versie.

Waarom de URL-vorm: wanneer GTM een ‘Custom HTML’-tag activeert, voegt het je markup niet in zoals die geschreven is. Het maakt een nieuw scriptelement aan en kopieert alleen de src; elk data--attribuut wordt weggelaten, dus een tag die je plakt met data-agent-id laadt het bestand, voegt niets toe en geeft nergens een foutmelding. De URL is het enige dat overblijft, en de loader leest ?agent= uit zijn eigen src. In je eigen sjabloon werkt beide vormen; een data-agent-id-attribuut krijgt voorrang als beide aanwezig zijn.

  • Toegestane bronnen gelden nog steeds — voeg het domein toe waarop de container draait (nu de test-URL van het bureau, later het productiedomein) onder Toegestane bronnen, anders start de widget wel op maar wordt hij geweigerd bij /init.
  • Toestemmingsmodus. Als de tag is gekoppeld aan toestemming voor analytics of marketing, verschijnt de widget pas nadat de bezoeker toestemming heeft gegeven. De widget stelt één functionele identificatie in (pb_anon_id, om het gesprek voort te zetten) en geen trackingcookies, dus de meeste sites activeren hem als een functionele tag; die classificatie is aan de site-eigenaar.
  • Laad de bundel niet vanuit een inline-script dat deze ophaalt, en verwijder het data-agent-id -attribuut niet — zonder dit attribuut op een scripttag heeft de loader geen agent om mee te communiceren en blijft hij stil.
  • Als GTM op de pagina staat, worden chat- gebeurtenissen direct naar dataLayer gestuurd zodra deze voor de agent is ingeschakeld.

Twee agents op één site, gekozen op basis van het URL-pad

Als verschillende delen van een site met verschillende agents moeten communiceren, houd dan één aangepaste HTML-tag aan en laat een variabele de agent kiezen:

  1. Maak een RegEx-tabelvariabele aan. Invoervariabele: Paginapad. Eén rij per sectie, patroon → agent-id, bijvoorbeeld ^/waterhardheid/ → de id van de agent. Standaardwaarde: none.
  2. Laat "Volledige overeenkomst" uitgeschakeld. Als dit is ingeschakeld, moet het patroon overeenkomen met het volledige pad, dus ^/waterhardheid/ komt overeen met /waterhardheid/ en niets daaronder: elke diepere pagina, zoals /waterhardheid/gulpen-wittem/, valt terug op none, en de widget verschijnt op de indexpagina van het gedeelte en nergens anders. Als je liever ‘Volledige overeenkomst’ ingeschakeld hebt, sluit elk patroon dan af met .*.
  3. Zet in de tag de variabele in de URL: <script src="https://blengi.com/w/widget.js?agent={{Blengi agent}}" async></script>, met een All Pages-trigger en een uitzondering (blokkerende) trigger voor Blengi-agent is gelijk aan none. Geen data-agent-id-attribuut: GTM verwijdert die wanneer het het script invoegt.
  4. Controleer dit in Preview op een diepe pagina van de sectie, niet op de indexpagina. De indexpagina slaat de test ook door met ‘Full Match’ ingeschakeld, en dat is precies hoe deze verkeerde configuratie zich verbergt.

Laat ?v= weg uit de URL in een tagmanager: een versie die in een GTM-constante is vastgezet, raakt verouderd, en de bundel wordt toch in de huidige versie geleverd. ?agent= is de enige query die de URL nodig heeft.

De agent moet toegestaan zijn op je domein

Het widgetscript is openbaar, dus een agent draait alleen op de domeinen die je vermeldt onder Website → Websites waar hij mag verschijnen. Een lege lijst staat niets toe: het script wordt geladen, het eerste verzoek wordt geweigerd, en de pagina toont simpelweg geen chat zonder foutmelding op het scherm.

Je hoeft dit zelden handmatig te doen. De eerste webpagina die je toevoegt als kennisbron stelt de oorsprong voor je in, en de onboarding-wizard doet hetzelfde. Als een agent wordt gepubliceerd met een lege lijst, staat dat op de overzichtspagina vermeld en wordt er direct naar het veld gelinkt. Eén vermelding per site is genoeg, want https, www en non-www komen allemaal overeen.

Wat staat er in de URL

  • src — verwijst naar /w/widget.js op je Blengi-installatie. Het achtervoegsel ?v=<hash> is de inhoudshash van de bundel; deze verandert telkens wanneer de widget opnieuw wordt opgebouwd, zodat klanten niet vast komen te zitten op verouderde versies die door een CDN in de cache zijn opgeslagen.
  • data-agent-id — de ID van de agent (een UUID). De loader van de widget leest dit attribuut en gebruikt het bij elke /v1/widget/init-aanroep. Een tag zonder dit attribuut werkt nog steeds voor een website die ons team op verzoek van de eigenaar heeft gekoppeld aan zijn AI-medewerker, wanneer die AI-medewerker is gepubliceerd en de website toestaat (met of zonder www): /v1/widget/init start het dan. Alleen een link die ons team maakt, telt — een ander account dat dezelfde website vermeldt, neemt deze nooit over — en een niet-gekoppelde website toont niets. Geef de id op wanneer je maar kunt.
  • async — niet-blokkerend. De widget verschijnt zodra het pakket is gedownload; de laadtijden van je pagina worden hierdoor niet beïnvloed.
  • data-locale (optioneel) — de taal van de widget forceren (bijv. data-locale="nl"). Laat je dit weg, dan volgt de widget automatisch de taal van je pagina <html lang>. Zie Taal hieronder.

Taal

De widget geeft zijn gebruikersinterface weer — het label van de launcher, de starterchips, knoppen en systeemberichten — in de taal van de bezoeker, bepaald bij init in deze volgorde:

  1. data-locale in de script-tag, indien ingesteld — een expliciete overschrijving (bijv. data-locale="de").
  2. De <html lang> van de hostpagina — zodat de widget overeenkomt met de taal waarin je site op dat moment wordt weergegeven. Op onze eigen marketingsite zorgt dit ervoor dat de demo de taalkeuze volgt.
  3. De standaardtaal van de agent (Persoonlijkheid › Taal) als de pagina geen taal aangeeft.
  4. De Accept-Language van de browser, daarna Engels.

Regionale tags werken soepel terug: en-GB → en, pt-BR blijft pt-BR wanneer dat bestand wordt geleverd. De paginataal heeft voorrang op de standaardtaal van de agent, dus een enkele agent die is ingebed op een meertalige site spreekt de taal van elke pagina. Vertaal het label van de launcher en de starterchips per taal in Vertalingen; alles zonder vertaling valt terug op de originele tekst.

Wat er wordt ingevoegd

Bij het opstarten doet de loader het volgende:

  1. Maakt een <div> onderaan <body> en koppelt er een Shadow DOM aan.
  2. De launcher (kleine knop) wordt weergegeven binnen de shadow root.
  3. POST /v1/widget/init aanroepen om een agentconfiguratie + JWT + recente geschiedenis op te halen.
  4. Start de triggers van de agent (exit-intentie, inactiviteit, scrollen, tijd op de pagina, terugkerende bezoeker, campagne, verlaten winkelwagentje) — zie Gedragsregels & triggers.
  5. Stelt twee first-party cookies in: pb_anon_id (één jaar), zodat dezelfde browser als dezelfde bezoeker wordt herkend en de conversatie behouden blijft bij het herladen van de pagina, en pitchbar_conv_id (één dag), de conversatie-ID voor winkelplugins. Alles wat hierin wordt opgeslagen, staat vermeld op de Widget API-pagina.

De launcher aanpassen

Het thema is volledig agent-gestuurd — zie Persona, thema & prompts. De widget leest theme.position, theme.primary, theme.accent, theme.radius en theme.launcher_label uit het init-antwoord en geeft dit daarop aan.

Er is geen aanpassing per pagina — de launcher haalt altijd gegevens op uit de agent. Als je op verschillende pagina’s een andere look wilt, sluit dan twee verschillende agents in.

Programmatische besturing

De widget stelt één globale variabele beschikbaar, window.AIAssistant (of de naam in de data-global van de scripttag; de oudere window.Pitchbar werkt nog steeds), samen met mount(), unmount(), open(), close(), isOpen(), send() en setContext(). De loader roept mount() voor je aan, dus je roept deze zelden rechtstreeks aan.

// Mount the widget into a custom host element (rare).
window.AIAssistant.mount(document.getElementById('chat-host'));

Elke methode, de bijbehorende argumenten en data-mount="manual" worden beschreven op de Widget API-pagina. Er is geen on()-methode. Voor conversieanalyses zet je ‘Geavanceerd › Gebeurtenissen bijhouden’ aan: de widget gebeurtenissen zoals lead_form_submitted (met jouw voorvoegsel) door naar dataLayer van Tag Manager, naar gtag en als CustomEvent op window (zie Gebeurtenissen voor GA4 & Tag Manager). Aan de serverzijde activeert elke vastgelegde lead de lead.captured-webhook (zie Uitgaande webhooks).

Single-page apps

De widget wordt één keer per paginalaadbeurt geladen, maar het gesprek blijft behouden bij navigatie binnen de app, zolang de scripttag in de DOM blijft staan. Je hoeft hem niet opnieuw te laden als je router van route verandert — de Shadow DOM en JWT blijven behouden.

Als je SPA bij routewijzigingen volledig opnieuw wordt geladen (bijv. als je de body verwijdert), wordt de widget opnieuw geïnitialiseerd en wordt het gesprek met de bezoeker hervat vanaf de geschiedenis van de afgelopen 24 uur.

Wat er bij elke initialisatie wordt verzonden

Een POST /v1/widget/init bevat:

  • agent_id — de waarde van data-agent-id.
  • page_url — de huidige location.href, gebruikt om de "huidige pagina" sneller op te halen.
  • anon_id — de permanente ID van de bezoeker uit localStorage, gegenereerd bij het eerste bezoek.
  • locale — de taal van de hostpagina (data-locale, anders <html lang>), zodat de widget-UI de pagina volgt. Wordt weggelaten als geen van beide aanwezig is.

De server leest ook de headers Origin, Referer en Accept-Language — Origin voor de allowed-origin-controle, Accept-Language voor het detecteren van de standaardtaal.

Versiebeheer & caching

Het padonderdeel /w/widget.js blijft stabiel bij elke implementatie. Een snippet met de oudere /widget/widget.js blijft werken: het reageert met een permanente omleiding naar /w/widget.js, waarbij de query intact blijft. Klanten plakken het fragment één keer en hoeven er nooit meer iets aan te doen — bundelupdates worden transparant doorgevoerd. De ?v=<hash>-query verandert bij elke build, waardoor de browsercache op bestaande pagina’s wordt geleegd zonder dat de URL verandert die de klant op zijn site heeft geplakt.

Intern wordt /w/widget.js geleverd door WidgetBundleController, dat de nieuwste gehasht bundel streamt die in public/widget/manifest.json wordt genoemd, samen met Cache-Control: no-cache, must-revalidate en een sterke ETag. Het gehasht bestand (widget.<hash>.js) is het artefact op de schijf; de stabiele URL is de publieke afspraak.

Vóór de fix (29-05-2026) gaf het insluitfragment de gehashte bestandsnaam direct weer (bijv. widget.abc123.js); bij elke nieuwe build veranderde de URL en gaven de door klanten geplakte <script>-tags een 404-fout. De fix is doorgevoerd in AgentController::widgetUrl() en OnboardingController::buildWidgetSrc().