Snelstart

Widget Overzicht

De widget-app is gehost op widget.companin.tech en biedt een gemakkelijke manier om een Klantenservice AI Agent in uw website te embedden. Om te beginnen, moet u een agent en een OAuth-toepassing maken.

De widget is een lichte, zelfstandige applicatie die draait in een geïsoleerd iframe op je website. Deze architectuur zorgt ervoor dat de widget niet in conflict komt met je bestaande CSS of JavaScript, terwijl het uitstekende prestaties en beveiliging behoudt.

1. Maak een Agent

Maak eerst een Klantenservice AI Agent in uw dashboard:

Je agent is de AI-hersenen achter de widget. Het verwerkt gebruikersberichten, behoudt de gesprekscontext en genereert intelligente antwoorden. Elke agent kan worden aangepast met specifieke instructies, persoonlijkheidskenmerken en kennisbases om aan je gebruiksgeval te voldoen.

1. Ga naar uw dashboard en navigeer naar de pagina "Gegevensbronnen"
2. Klik op de knop "Toevoegen" in de sectie Agents
3. Vul de agentdetails in (naam, beschrijving, toon, enz.)
4. Sla de agent op en noteer zijn ID

Tip: Geef je agent duidelijke, specifieke instructies over zijn rol en beperkingen. Bijvoorbeeld: "Je bent een behulpzame klantenservicemedewerker voor een SaaS-product. Je kunt vragen beantwoorden over functies, prijzen en accountbeheer. Voor technische problemen, verwijs gebruikers naar het aanmaken van een ondersteuningsverzoek."

2. Maak een OAuth-toepassing

Maak een OAuth-toepassing om uw widget te authenticeren:

1. Ga naar de pagina "OAuth" in uw dashboard
2. Klik op "Toepassing maken"
3. Vul de naam en beschrijving van de toepassing in
4. Kopieer de client_id van de gemaakte toepassing

3. Embed de Widget via Iframe

De eenvoudigste manier om de widget te integreren is door deze rechtstreeks te embedden met een iframe. Deze methode vereist geen JavaScript-initialisatie en werkt direct. Voor meerdere iframes op één pagina, houd elke embed beperkt tot zijn eigen container en parameters.

<iframe src="https://widget.companin.tech/embed/session?key=YOUR_WIDGET_KEY&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Agent Widget"></iframe>

Vervang YOUR_WIDGET_KEY door de installatiesleutel van je widget (de wgt_…-waarde — kopieer deze van de Widget- of Installatiepagina in het dashboard). De locale parameter kan worden ingesteld om overeen te komen met de taal van je site.

Geavanceerd: JavaScript-initialisatie

De aanbevolen integratiemethode is het gebruik van onze JavaScript-widgetloader, die automatische sizing, configuratiebeheer en responsief gedrag biedt.

Scriptintegratie

Voeg de volgende script-tag toe aan je HTML-pagina:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-instance-id="support-widget"  data-locale="en"  async></script>

Scriptattributen

Elk attribuut heeft een specifiek doel bij het configureren van je widget:

• data-widget-key: De Widget-ID van uw widget - De enige waarde die de meeste installaties nodig hebben. Het lost uw client, agent en configuratieserver aan de serverzijde op, zodat u ze niet afzonderlijk hoeft te plakken.

De drie attributen hieronder zijn een geavanceerd alternatief voor data-widget-key - gebruik ze voor multi-instance setups waarbij je expliciet een specifieke klant, agent of configuratie moet targeten:

• data-client-id: Je OAuth-client-ID - Dit authenticates je applicatie met onze API. Beschouw het als het wachtwoord van je app.
• data-agent-id: De UUID van je agent - Dit identificeert welke Klantenservice AI Agent de gesprekken afhandelt.
• data-config-id: De UUID van je widgetconfiguratie - Dit bepaalt hoe je widget eruitziet en zich gedraagt (kleuren, grootte, positie, enz.).
• data-instance-id: Uniek per-widget instantie ID - Vereist bij het insluiten van meerdere widgets op dezelfde pagina om botsingen te voorkomen en per-instantie API-targeting mogelijk te maken.
• data-custom-css: Verouderd. Het instellen van dit attribuut logt een consolewaarschuwing en heeft geen effect. Stel custom_css in op je widgetconfiguratie in het dashboard in plaats daarvan — het wordt geladen vanuit de configuratie en automatisch in het iframe geïnjecteerd.
• data-locale: Taalcode (bijv. "en", "es", "fr") - Stelt de weergavetaal van de widget in. De agent zal nog steeds reageren in elke taal die gebruikers schrijven.
• data-dev: Stel in op "true" voor ontwikkelingsmodus (localhost) - Gebruik dit bij lokaal testen. Verwijder of stel in op "false" voor productie.

De widget zal automatisch:

• De configuratie ophalen van de configuratie-ID
• Zichzelf dimensioneren volgens de widgetafmetingen in de configuratie
• De ingeklapte knop positioneren op basis van de configuratie-instellingen
• Start open of gesloten op basis van de instelling start_open van de configuratie

Notities

• De widget beheert automatisch zijn eigen sizing op basis van je configuratie-instellingen
• De positie van de ingeklapte knop kan worden aangepast via de widgetconfiguratie
• De widget respecteert de instelling start_open van je configuratie
• Alle styling (kleuren, lettertypen, afmetingen) wordt beheerd via de widgetconfiguratie
• De widget gebruikt postMessage-communicatie voor responsief gedrag
• De ontwikkelingsmodus kan worden ingeschakeld met data-dev="true" voor localhost-testen
• Voor server-side tokenuitwisseling, gebruik /api/v1/auth/widget-token en houd de clientsecret alleen op je server.
• Zorg ervoor dat je hostoorsprong (bijvoorbeeld http://localhost:3000) is opgenomen in de toegestane_origins van OAuth wanneer je de widget in een iframe insluit.