De widget insluiten
Snippet installeren
YOUR-AGENT-ID.
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 totdatwindow.AIAssistant.mount()wordt aangeroepen; hoe een toestemmingsbanner de chat regelt.data-context-global="blengiContext"— de naam van een globale variabelewindowdie 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 metwindow.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
dataLayergestuurd 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:
- Maak een RegEx-tabelvariabele aan. Invoervariabele:
Paginapad. Eén rij per sectie, patroon → agent-id,
bijvoorbeeld
^/waterhardheid/→ de id van de agent. Standaardwaarde:none. - 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 opnone, 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.*. - 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. Geendata-agent-id-attribuut: GTM verwijdert die wanneer het het script invoegt. - 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.jsop 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 zonderwww):/v1/widget/initstart 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:
data-localein de script-tag, indien ingesteld — een expliciete overschrijving (bijv.data-locale="de").- 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. - De standaardtaal van de agent (Persoonlijkheid › Taal) als de pagina geen taal aangeeft.
- De
Accept-Languagevan 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:
- Maakt een
<div>onderaan<body>en koppelt er een Shadow DOM aan. - De launcher (kleine knop) wordt weergegeven binnen de shadow root.
POST /v1/widget/initaanroepen om een agentconfiguratie + JWT + recente geschiedenis op te halen.- Start de triggers van de agent (exit-intentie, inactiviteit, scrollen, tijd op de pagina, terugkerende bezoeker, campagne, verlaten winkelwagentje) — zie Gedragsregels & triggers.
- 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, enpitchbar_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 vandata-agent-id.page_url— de huidigelocation.href, gebruikt om de "huidige pagina" sneller op te halen.anon_id— de permanente ID van de bezoeker uitlocalStorage, 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().