De Chatwidget insluiten (Gids voor ontwikkelaars)

Handleiding voor het insluiten van de widget

De widget is een Web Component (<web-chat-agent>) die asynchroon laadt en op elke site werkt, zonder framework en zonder buildstap. Het script rendert een zwevende chatknop; bezoekers klikken hierop om het chatvenster te openen.

Insluitcode

Plak dit vlak voor de sluitende </body>-tag:

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
></web-chat-agent>

Vervang YOUR_CHATBOT_ID door je Chatbot-ID. Je vindt de vooraf ingevulde insluitcode onder Dashboard → je assistent → Kanalen → Chatwidget → Installatiedetails tonen. Kopieer deze daar om typefouten te voorkomen.

De widget roept de API aan op dezelfde origin waar deze vandaan is geladen. Laad je het script van webchatagent.com, dan gaan de chatverzoeken automatisch naar webchatagent.com/api/.... Je hoeft dus nooit handmatig een API-URL in te stellen.

Hoe het werkt

1. Het async-script laadt op de achtergrond en blokkeert de weergave van de pagina niet.
2. Het <web-chat-agent>-element rendert een zwevende chatknop.
3. De widget haalt je dashboardinstellingen op (kleuren, teksten, tools, welkomstbericht) en past deze toe. Er zijn geen extra attributen nodig.
4. Een bezoeker klikt op de knop, het chatvenster opent en berichten worden naar je AI-chatbot gestuurd.

HTML-attributen

Elke visuele instelling uit Kanalen → Chatwidget wordt automatisch toegepast. HTML-attributen op het element zijn optionele overschrijvingen. Gebruik ze alleen voor aanpassingen per pagina (zoals een afwijkende positie op een specifieke landingspagina). Attribuutnamen zijn in kebab-case (de widget koppelt theme-color intern aan de prop themeColor).

De onderstaande standaardwaarden zijn de ingebouwde fallbacks van de widget. In de praktijk worden de meeste attributen niet ingesteld en nemen ze de waarde over die je in het dashboard hebt geconfigureerd.

Basisinstellingen

Kleuren

Alle kleurattributen accepteren elke geldige CSS-kleur (hex zoals #2563eb, rgb(), hsl()). Indien niet ingesteld, gebruikt de widget de waarde uit je dashboard of de ingebouwde fallback (de standaard merkkleur is blauw, #2563eb).

Afbeeldingen

Positionering

Inhoud & gedrag

Toestemming bijwerken tijdens runtime

window.dispatchEvent(
  new CustomEvent('webchatagent:consent', {
    detail: { tracking: 'granted' }
  })
)

Verzend denied wanneer toestemming wordt geweigerd of ingetrokken. Anonieme lokale triggers blijven beschikbaar. Raadpleeg de handleiding voor cookietoestemming voor de triggermatrix en CMP-adapters.

Promptknoppen

Snelle actieknoppen die onder de berichtenlijst worden getoond. Elke knop heeft een zichtbare title en een action (de tekst die als bericht van de gebruiker wordt verzonden wanneer erop wordt geklikt). Geef een JSON-array op als attribuutwaarde:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  prompt-buttons='[{"title":"Talk to support","action":"I need help with my order"},{"title":"Pricing","action":"What does it cost?"}]'
></web-chat-agent>

Sessiecontextgegevens

Wanneer de widget draait binnen een systeem dat de bezoeker al kent, zoals een CRM, een klantenportaal of een ingelogde omgeving, kan de insluitende pagina die kennis doorgeven aan de chatbot. De AI ziet de waarden, verwijst ernaar in zijn antwoorden en gebruikt ze om overeenkomende argumenten van API-connector- en MCP-tool-aanroepen in te vullen. Een bezoeker van wie het dossiernummer al op het scherm staat, hoeft dit nooit meer opnieuw in te voeren.

Contextgegevens worden meegestuurd met elk chatverzoek van de sessie, worden uitsluitend voor dat verzoek in de AI-prompt geïnjecteerd en worden niet als een eigen record opgeslagen.

Context doorgeven via het HTML-attribuut

Er worden twee formaten ondersteund. Het eenvoudige formaat vereist geen JSON-kennis, maar gebruikt door puntkomma's gescheiden Key=Value-paren:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data="Customer=Jane Doe;Company=Acme GmbH;OrderID=A-1023"
></web-chat-agent>

Alleen de eerste = in elk paar scheidt de sleutel en de waarde, waardoor waarden die een = bevatten (zoals base64-tokens) intact blijven. Een waarde kan in dit formaat geen puntkomma bevatten, gebruik daarvoor JSON:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data='{"Customer":"Jane Doe","Note":"VIP; priority support","OrderID":"A-1023"}'
></web-chat-agent>

Plaats bij JSON de attribuutwaarde tussen enkele aanhalingstekens, zodat de dubbele aanhalingstekens daarbinnen behouden blijven.

Context doorgeven via JavaScript

Als u de voorkeur geeft aan JavaScript boven het attribuut (of dit nodig hebt, bijvoorbeeld in WordPress), stelt u de globale variabele window.webchatagentContext in. Het is veilig om deze in te stellen voordat het widgetscript is geladen. De widget pikt dit op zodra deze initialiseert, dus de laadvolgorde van het script maakt niet uit:

<script>
  window.webchatagentContext = {
    Customer: 'Jane Doe',
    OrderID: 'A-1023',
    userToken: 'opaque-token-validated-by-your-backend'
  }
</script>
<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>

Context bijwerken tijdens runtime

Wanneer de gegevens veranderen terwijl de widget al actief is (inloggen, wisselen naar een ander dossier), verzendt u het webchatagent:context-event met een standaard object:

window.dispatchEvent(
  new CustomEvent('webchatagent:context', {
    detail: {
      Topic: 'billing',
      OrderID: 'A-1023'
    }
  })
)

Elk event vervangt de volledige context; detail: null of {} wist deze. Voorrangsvolgorde bij het laden: het context-data-attribuut wordt als eerste toegepast, daarna window.webchatagentContext (indien ingesteld) en vervolgens eventuele events. De context bevindt zich in de pagina, stel deze na het herladen opnieuw in.

White-label-implementaties: de merkneutrale aliassen window.chatWidgetContext (globaal) en chat-widget:context (event) werken identiek, zodat insluitende pagina's nooit naar de platformnaam hoeven te verwijzen.

Limieten

Maximaal 20 sleutels, sleutelnamen tot 64 tekens, waarden tot 500 tekens (nummers en booleans worden geconverteerd naar strings), 4.000 tekens totaal. Regeleinden en de tekens < > worden verwijderd uit sleutels en waarden. Antwoorden op verzoeken die contextgegevens bevatten, worden nooit vanuit de antwoordcache geleverd.

Beveiliging: contextgegevens zijn geen authenticatie

De waarden zijn afkomstig uit de browser van de bezoeker. Iedereen kan DevTools openen en willekeurige context verzenden, daarom is de AI geïnstrueerd om dit te behandelen als ongeverifieerde achtergrondgegevens. Bouw hier nooit autorisatie op.

Twee regels voor productiegebruik:

1. Beperk allowedDomains voor uw chatbot in het dashboard. Zonder deze beperking kan elke pagina uw bot insluiten en van context voorzien.
2. Geef voor het opzoeken van persoonlijke gegevens een ondoorzichtig token door in plaats van een directe identiteit. Genereer aan de serverzijde een kortlevend token voor de ingelogde gebruiker, geef dit door als contextwaarde (bijvoorbeeld userToken=...) en laat het eindpunt van uw API-connector het token valideren voordat gebruikersgegevens worden geretourneerd. De AI stuurt het token door in de API-aanroep; uw backend bepaalt wat daarmee wordt ontgrendeld. Een vervalst token levert dan niets op.

WordPress

De WordPress-plugin ondersteunt (vanaf de volgende release) contextgegevens aan de serverzijde: het webchatagent_context_data-filter levert deze voor de zwevende widget (en als standaard voor inline insluitingen), en de inline shortcode accepteert een context-data-attribuut:

add_filter('webchatagent_context_data', function () {
    $user = wp_get_current_user();
    return $user->exists() ? 'Customer=' . $user->display_name : '';
});

[webchatagent_inline context-data="Topic=Support;OrderID=A-1023"]

Stel bij oudere pluginversies in plaats daarvan window.webchatagentContext in of verzend het webchatagent:context-event, beide werken op elk platform.

Voorbeeld: Volledige aanpassing

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="abc-123-def"
  theme="modern"
  title="Support Chat"
  theme-color="#4f46e5"
  theme-text-color="#ffffff"
  user-message-color="#4f46e5"
  bubble-color="#4f46e5"
  font-family="Inter"
  initially-open="false"
  offset-x="30"
  offset-y="30"
></web-chat-agent>

Dashboard versus HTML-attributen

Dashboard-instellingen worden aan de serverzijde opgeslagen en geladen wanneer de widget initialiseert. HTML-attributen overschrijven deze alleen voor die specifieke pagina.

Aanbeveling: Voer alle visuele aanpassingen uit in het dashboard. Gebruik HTML-attributen alleen wanneer één pagina moet afwijken, zoals bij een andere positionering, een geforceerd thema of paginaspecifieke promptknoppen.

Eigen CSS

Richt u voor wijzigingen die verder gaan dan de bovenstaande attributen met uw eigen CSS op de interne elementen van de widget. Elk stijlbare element bevat een stabiele .wca-*-klasse (bijvoorbeeld .wca-header, .wca-message, .wca-bubble), zodat uw selectors blijven werken na updates van de widget en geen !important nodig hebben. U voegt de CSS toe in het dashboard, waarna deze in de shadow DOM van de widget wordt geïnjecteerd. Zie Eigen CSS.

Inlinechat

Gebruik de inline-variant om de chat binnen uw paginalay-out weer te geven in plaats van als een zwevende knop. Deze laadt een ander script en een ander element (<web-chat-agent-inline>):

<script src="https://webchatagent.com/widget/chat-widget-inline.js" async></script>
<web-chat-agent-inline chatbot-id="YOUR_CHATBOT_ID"></web-chat-agent-inline>

Het inline-element accepteert chatbot-id, een optionele container-height, plus tracking-consent en context-data (zie Sessiecontextgegevens, attribuut en runtime-event werken hier identiek); alle andere instellingen zijn afkomstig uit Kanalen → Inlinechat. Plaats het element waar u de chat wilt laten verschijnen en bepaal de grootte via de omsluitende container. Zie Inlinechat voor details.

WordPress

Gebruik op WordPress de officiële WebChatAgent WordPress Plugin in plaats van het script handmatig te plakken. Deze regelt het insluiten en de updates voor u. Zie WordPress Plugin.

Single Page Applications (SPA)

De widget werkt standaard met React, Vue, Angular en andere SPA's. Voeg de scripttag toe aan index.html en plaats het <web-chat-agent>-element in uw app-shell (bijvoorbeeld de root-layout). De widget blijft behouden tijdens routewisselingen aan de clientzijde, u hoeft deze niet opnieuw te mounten bij navigatie.