> For the complete documentation index, see [llms.txt](https://oswaldai.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://oswaldai.gitbook.io/docs/functionele-documentatie/integraties/widget.md).

# Widget

De makkelijkste manier om je Oswald chatbot te integreren in je website (HTML) is via de ingebouwde widget. Je kan deze widget configureren door in de `Instellingen` te kiezen voor de tab `Widget`. Je hebt de vrijheid om deze widget te configureren naar jouw stijl. De parameters zijn gegroepeerd in `Configuratie`, `Kleuren`, `Teksten`, `Iconen en URL's`, `Gedrag`, `Widgetscript` en `Aangepaste stijlen en scripts`.

### Widgetversie

Bij `Configuratie` kies je de `Widgetversie`: `v1` of `v2 (bèta)`. De nieuwe widget (v2) gebruikt minder instellingen dan v1: de vaste teksten in de widget komen bij v2 uit de vertalingen van de widget zelf. De tab `Widget` toont enkel de instellingen die gelden voor de gekozen versie. In de tabel hieronder zie je welke parameters ook voor v2 gelden.

### Parameters

| Naam                                      | Beschrijving                                                                                                                                                                            | v2 |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `Titel`                                   | De titel op de widget.                                                                                                                                                                  | x  |
| `Ondertitel`                              | De ondertitel op de widget.                                                                                                                                                             |    |
| `Bubbeltekst`                             | De tekst op de knop van de widget.                                                                                                                                                      | x  |
| `Hoofdkleur`                              | De primaire kleur van de widget en de kleur van de tekstballonnen van de berichten van de chatbot.                                                                                      | x  |
| `Secundaire kleur`                        | De kleur van de tekstballonnen van de berichten van de gebruiker.                                                                                                                       |    |
| `Overnamekleur`                           | De kleur van de tekstballonnen van de berichten van een customer agent.                                                                                                                 |    |
| `Tekstkleur`                              | De kleur van de tekst van de berichten van de chatbot.                                                                                                                                  |    |
| `Secundaire tekstkleur`                   | De kleur van de tekst van de berichten van de gebruiker.                                                                                                                                |    |
| `Tekstkleur overname`                     | De kleur van de tekst van de berichten van een customer agent.                                                                                                                          |    |
| `Hoekafronding` / `Hoekafronding (groot)` | De afronding van de hoeken van de widget en de tekstballonnen.                                                                                                                          | x  |
| `Plaatshouder (invoerveld)`               | De tekst die op het inputveld van de gebruiker staat.                                                                                                                                   |    |
| `Overnamebericht`                         | De tekst die weergegeven wordt wanneer de gebruiker met een takeover agent aan het praten is.                                                                                           |    |
| `Knoptekst overname`                      | De tekst die weergegeven wordt op de knop waar de gebruiker op kan klikken om terug met de chatbot te praten zonder dat de takeover agent het gesprek heeft beëindigd.                  |    |
| `Verbinding instabiel`                    | De tekst die getoond wordt wanneer de verbinding met de chatbot wegvalt.                                                                                                                |    |
| `Bericht te lang`                         | De waarschuwing wanneer de gebruiker een te lang bericht typt (zie verder).                                                                                                             |    |
| `URL van het widgeticoon`                 | Een url naar een icoontje dat getoond wordt in de widget.                                                                                                                               | x  |
| `URL van het bubbelicoon`                 | Een url naar het icoontje op de knop van de widget.                                                                                                                                     | x  |
| `Sluiticoon` / `Sluiticoon van de bubbel` | Het icoontje om de widget te sluiten: een kruis (×) of een min (–).                                                                                                                     |    |
| `Demo-URL`                                | Een url naar de pagina waarop je de widget wil testen, zonder effectief de widget te integreren. Deze pagina wordt geopend als je op `Widget testen` klikt in het trainingsstatus-menu. | x  |
| `Bestandsupload inschakelen`              | Laat gebruikers bestanden uploaden in de chat.                                                                                                                                          | x  |
| `Max. berichtlengte`                      | Het aantal tekens waarboven de gebruiker gewaarschuwd wordt dat zijn bericht te lang is.                                                                                                |    |
| `Berichtvertraging`                       | Het aantal milliseconden tussen opeenvolgende berichten van de chatbot.                                                                                                                 |    |
| `Sessieduur`                              | Hoelang de gesprekssessie van een bezoeker geldig blijft (zie verder).                                                                                                                  | x  |
| `Widgetscript`                            | Een stukje HTML-code dat je kan plakken in de `<body>` van je webpagina. De widget zal dan in deze configuratie te zien zijn op die specifieke webpagina.                               | x  |

De teksten stel je in per taal. Je wisselt van taal met de taalkeuze rechts in de menubalk.

De widget integreren op je website is zo eenvoudig als de HTML-code plakken in de `body` van je webpagina. In dit stukje HTML-code kan je de sessie bepalen die voor de gebruiker gekozen moet worden. Op deze manier kan je dezelfde gebruiker steeds dezelfde sessie tonen. De gebruiker ziet dan bij opnieuw openen van de widget de recente berichten die hij of zij met de bot heeft uitgewisseld. Dit kan interessant zijn als de gebruiker geregeld van pagina wisselt terwijl hij de bot gebruikt. Je bepaalt de sessie van de gebruiker door ze in het widgetscript toe te voegen in de widgeturl, bijvoorbeeld:`https://api.oswald.ai/api/v1/chats/<API TOKEN IN INSTELLINGEN>/widget?session=<DE SESSION DIE JE KIEST>`

Merk op dat Oswald niet kan voorspellen hoe we je sessie binnenkrijgen of opslaan, daarom kiezen we een willekeurige code als sessie als je niets doorgeeft.

### Stijl van de widget

Je kan het uitzicht en het gedrag van de widget nog verder aanpassen in de sectie `Aangepaste stijlen en scripts` onderaan het configuratiescherm. Hier vul je de code rechtstreeks in, in drie velden: `Widget CSS`, `Host CSS` en `Widget JS`. Bij widget v2 is er geen `Host CSS`.

* De `Host CSS` bevat de stylesheet die op de webpagina die de widget bevat (host) wordt ingeladen. Deze bepaalt de grootte en de plaats van de widget op de pagina.
* De `Widget CSS` bevat de extra stijlregels voor de widget zelf. De widget is immers opgemaakt uit iframes en het uitzicht hiervan kan je niet bepalen vanop de host pagina. Hierin pas je alle eigenschappen binnen de widget aan, bijvoorbeeld vorm en kleur.
* De `Widget JS` geeft je de mogelijkheid om in de iframes van de widget javascript uit te laten voeren die specifiek voor jouw site moet gelden. Zo kan je extra functionaliteit toevoegen. Wees hier voorzichtig mee, nieuwe releases van ons platform kunnen het gedrag van de widget veranderen.

#### Testen

Je kan de widget ook testen door in het trainingsstatus-menu rechts in de menubalk op `Widget testen` te klikken.

{% hint style="warning" %}
Opgelet: je kan de widget enkel testen als de chatbot gepubliceerd is.
{% endhint %}

{% hint style="warning" %}
**Opgelet: als je website beveiligd is om in een HTML iframe ingeladen te worden, kan je de `Demo-URL` niet gebruiken en zal je een lege webpagina te zien krijgen. De widget zal wel werken.**
{% endhint %}

<figure><img src="https://1621246471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-L_IHdvfaXCVi1CBgkrB-887967055%2Fuploads%2FK1qr4AZRtWGLbaWeJoL3%2FScreenshot%202026-10-22%20at%2011.02.28.png?alt=media&amp;token=e1fe2ad8-db34-4f76-a6d3-a33c3713a7dc" alt=""><figcaption></figcaption></figure>

Wanneer je klikt op `Widget testen` krijg je een scherm dat toont hoe je widget er uit zou zien en hoe hij zich zou gedragen:

<figure><img src="https://1621246471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-L_IHdvfaXCVi1CBgkrB-887967055%2Fuploads%2FdnhDvnYSzP4Pq7Z9rzBr%2FScreenshot%202026-10-22%20at%2011.04.17.png?alt=media&amp;token=22a4fb68-da73-4418-bf83-f55e57cc1623" alt=""><figcaption></figcaption></figure>

Je kan hier ook een aantal parameters configureren voor de script tag:

* **Open on load:** of de widget automatisch moet openen wanneer je de pagina laadt
* **Feedback:** of je feedback wil toelaten in de widget. Dan kunnen gebruikers aangeven of ze een antwoord goed of slecht vinden (zie [Feedback toelaten](#feedback-toelaten)).
* **Production:** of je de productieversie van je chatbot wil gebruiken of de testversie. Ook de instellingen voor je widget komen uit de overeenkomstige versie.
* **Refresh button** (enkel v2): toont een knop waarmee de gebruiker het gesprek opnieuw kan starten. Staat standaard uit.
* **Resize button** (enkel v2): toont een knop om de widget groter of kleiner te maken. Staat standaard aan.
* **Start Command:** het tekstje dat de widget naar de bot stuurt om het gesprek te beginnen. Zo kan je dit tekstje laten verschillen per pagina.
* **Locale:** de taal die de widget moet gebruiken. Normaal neemt de widget de taal van de gebruiker over, op basis van zijn browser.
* **Session:** de sessie om te gebruiken. Dit kan je laten afhangen van de ingelogde gebruiker op je pagina bijvoorbeeld. De widget zal de recente berichten van deze gebruiker ook opnieuw tonen.

Met **Update widget** herlaad je de pagina en activeer je de parameters die je ingeeft. Bij widget v1 heb je daarnaast nog twee knoppen:

* **Show Script Tag:** toont de aangepaste script tag die je kan gebruiken, waar deze parameters al zijn ingevuld.
* **Copy Takeover Link:** deze knop zet een link naar het gesprek in de Oswald takeover interface op je klembord. Zo kan je die in je browser plakken om snel het gesprek over te nemen.

Bij widget v2 kan je in de widget-URL nog deze parameters meegeven: `noClose` (de widget kan niet gesloten worden), `startCommandOnLoad` (stuur het startcommando meteen bij het laden), `forceStartCommand` (stuur het startcommando ook als er al berichten in de sessie zijn) en `debug`.

### Feedback toelaten

{% hint style="warning" %}
Dit is nog onder constructie in de v2 widget en admin paneel &#x20;
{% endhint %}

Je kan er voor kiezen om feedback toe te laten voor je chatbot, met de parameter `feedback` in de widget-URL (of **Feedback** op de demopagina). Gebruikers krijgen dan de mogelijkheid om antwoorden van de chatbot te beoordelen.

![](https://1621246471-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L_IHdvfaXCVi1CBgkrB%2F-LzlF5byQSzC4lztjQw_%2F-LzlFNvuo92wbf1yvgJI%2Fimage.png?alt=media\&token=725da36c-cd29-4e7c-abdd-3a1871666fee)

Bij widget v2 verschijnen er onder het laatste bericht van de chatbot een duim omhoog en een duim omlaag. De keuze van de gebruiker wordt als feedback bij dat bericht bewaard. Bij widget v1 verschijnt er een droevige smiley wanneer de gebruiker over een bericht van de chatbot hovert. Als de gebruiker daar op klikt wordt het bericht aangegeven als een mogelijk probleem en wordt de sessie getagged met de tag 'flagged\_by\_user'.

In de takeover interface kan je dan filteren op die tag en vind je ook de berichten terug die als probleem zijn gemarkeerd:

![](https://1621246471-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L_IHdvfaXCVi1CBgkrB%2F-LzlF5byQSzC4lztjQw_%2F-LzlG3DhqZlbvYQGfbX1%2Fimage.png?alt=media\&token=6a53dfb5-ae67-4b23-8045-fb71459df3f7)

### Sessieduur

Om de conversatie te bewaren wanneer de gebruiker wisselt van pagina kan je instellen hoe lang de sessie bewaard blijft, met de instelling `Sessieduur` onder `Gedrag`. Bij widget v1 gebeurt dit met een session cookie met de naam oswaldSession.

![](https://1621246471-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L_IHdvfaXCVi1CBgkrB%2F-MTK1op8k5T1UcTr28I3%2F-MTK2FcJKExx7Jzt71-e%2Fimage.png?alt=media\&token=769c5498-f99d-4b45-892b-fbb22d5891c7)

{% hint style="warning" %}
📸 Nieuwe screenshot nodig: de instelling `Sessieduur` onder `Gedrag`.
{% endhint %}

Je kan kiezen uit:

* `Eindigt bij verversen of navigeren`: de sessie wordt niet bewaard. Een eventueel bestaande cookie wordt verwijderd wanneer de gebruiker de pagina opent.
* `Eindigt bij sluiten browser`: de sessie wordt bijgehouden tot de gebruiker de browser sluit.
* `Na een aantal seconden`: de sessie wordt zoveel seconden bijgehouden in de browser van de gebruiker.

{% hint style="info" %}
**Opgelet:** geef je een session id mee aan de widget url, dan wordt deze instelling genegeerd.
{% endhint %}

### Waarschuw gebruiker bij ingeven van een lang bericht

Bij widget v1 kan je de gebruiker waarschuwen dat het bericht dat hij/zij aan het invoeren is waarschijnlijk te lang is om begrepen te worden door een chatbot. In de tab `Widget` vul je hiervoor de tekst `Bericht te lang` in (onder `Teksten`) en de limiet bij `Max. berichtlengte` (onder `Gedrag`).

![](https://1621246471-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L_IHdvfaXCVi1CBgkrB%2F-MMoGUS4nTP4qi0ZSfZg%2F-MMoGsdUWUCCgiImdILz%2Fimage.png?alt=media\&token=8b1e86db-2cba-4372-87d4-c9dda4108a83)

{% hint style="warning" %}
📸 Nieuwe screenshot nodig: de velden `Bericht te lang` en `Max. berichtlengte`.
{% endhint %}

Wanneer je bij deze instelling een tekst ingeeft, en de gebruiker een bericht ingeeft dat langer is dan de limiet, zal de widget het bericht tonen aan de gebruiker. Op die manier kan je de gebruiker vragen zijn berichten kort en to the point te houden.
