# JavaScript API: open de Nodale-agent vanuit je code

<https://nodale.ai/nl/docs/api>

De nodale()-commando's voor je pagina: open de agent vanuit je eigen knop of formulier, geef e-mailadres en context mee, meld de toestemming van de bezoeker.

Zodra de [tag is geïnstalleerd](https://nodale.ai/nl/docs), kan je pagina er commando's naartoe sturen via één functie, `nodale()`. Er zijn twee commando's: `open` en `consent`. De tag biedt geen andere methode en stuurt geen event naar je pagina.

## De commandowachtrij

De tag definieert `window.nodale` wanneer hij draait. Wil je een commando aanroepen voordat de tag geladen is, plak dan deze stub erboven. Commando's wachten in een wachtrij totdat de tag klaar is:

```html
<script>
  window.nodale = window.nodale || function(){(window.nodale.q = window.nodale.q || []).push(arguments)}
</script>
<script src="https://tag.nodale.app/v1/tag.js" data-workspace="YOUR_WORKSPACE_ID" async></script>
```

Laat de `||` staan. Een script dat later `window.nodale` toewijst zonder `||`, verwijdert het commando van de tag, en latere aanroepen komen nergens aan.

## `nodale('open')`

Opent de agent vanuit je eigen code, bijvoorbeeld vanuit je eigen knop of zodra je eigen formulier is verzonden.

```js
nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Contacten per maand': '1500' }
})
```

De aanroep start een geschreven gesprek in het dialoogvenster van de agent. De microfoon wordt niet aangevraagd: die wacht op de bezoeker.

### Opties

| Optie | Type | Wat het doet |
|---|---|---|
| `email` | string | Het e-mailadres van de bezoeker, als je pagina het al kent. De bezoeker wordt geïdentificeerd vóór de begroeting van de agent. |
| `context` | object | Wat de bezoeker je al heeft verteld, als paren van label en antwoord. De agent ontvangt het wanneer het gesprek start. Het wordt bij het gesprek vastgelegd en nooit aan de bezoeker getoond. |

Beide zijn optioneel. De tag controleert het argument voordat er iets de pagina verlaat:

- **Het argument** is niets, of een plain object zonder andere key dan `email` en `context`. Bij al het andere opent er niets.
- **`email`** is een string van 1 tot 254 tekens na trimmen. Anders vervalt het, en de agent opent toch. De tag beoordeelt het adres niet: de server beslist of het wordt geaccepteerd.
- **`context`** bevat maximaal 20 antwoorden. Een label telt 1 tot 60 tekens, een antwoord is een string van maximaal 300 tekens, en een label wordt één keer gebruikt. Labels en antwoorden worden getrimd, en een leeg antwoord wordt overgeslagen. Als één regel wordt geschonden, vervalt de hele context, nooit een deel ervan, en de agent opent toch, zonder context.

`nodale('open')` gooit nooit een fout en geeft `undefined` terug.

### Waar het werkt

- **Alleen op de balk en op de weergave `hidden`.** Met de knopweergave, met een inline `<div data-nodale-agent>`, en op een pagina waar de agent niet wordt getoond (een paginaregel, of een aandeel bezoekers), doet de aanroep niets. Gebruik je `open`, laat het aandeel bezoekers dan uit, anders doet de aanroep voor sommige bezoekers niets.
- **Voordat de tag geladen is**, via de stub hierboven. Alleen de laatste `open` in de wachtrij wordt opnieuw afgespeeld, één keer.
- **Eén gesprek.** De widget start maximaal één gesprek en bewaart het eerste e-mailadres en de eerste context die hij heeft ontvangen. Een `open` tijdens een gesprek, of nadat er een is afgelopen, toont alleen het dialoogvenster.
- **Als de agent eerst om het e-mailadres vraagt**, toont de aanroep die stap, en je e-mailadres en context worden verstuurd wanneer de bezoeker die stap verzendt.

### Vanuit een knop

```html
<button type="button" onclick="nodale('open')">Stel een vraag</button>
```

### Na je eigen formulier

```js
form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Bedrijfsgrootte': form.elements.size.value,
      'Wat ze willen doen': form.elements.message.value
    }
  })
})
```

## De weergave hidden

`hidden` is een weergave van de workspace, naast de balk en de knop. Hiermee is er niets te zien totdat je pagina `nodale('open')` aanroept.

- **De pagina blijft volledig bruikbaar.** Het frame van de agent is gemount maar onzichtbaar, en het vangt geen enkele klik op.
- **Eenmaal geopend is het de balk.** Het dialoogvenster sluiten brengt je terug naar de balk en bewaart het gesprek. De balk blijft daarna staan voor de rest van het tabblad.
- **Het tabblad onthoudt het.** Een latere pagina van je site in hetzelfde tabblad toont de balk meteen, zodat de bezoeker het gesprek terugvindt. De tag bewaart dit in `sessionStorage`, in een key die geen identifier bevat. Een nieuw tabblad start verborgen.
- **Alleen getest in Chromium-browsers.** Safari en Firefox vallen nog niet onder onze browsertests: een browser die onzichtbare frames vertraagt, kan later op `open` antwoorden.

## `nodale('consent')`

Vertelt de tag of de bezoeker akkoord is gegaan met bezoektracking. Gebruik het wanneer je site geen cookiebanner heeft die de tag kan lezen, of wanneer je toestemming zelf beheert.

```js
nodale('consent', 'granted')
nodale('consent', 'revoked')
```

- **Het telt alleen als bezoektracking aanstaat** in je workspace. Tracking staat standaard uit, en de agent wordt in beide gevallen gemount.
- **Tracking start als geweigerd.** Er wordt niets opgevraagd en er wordt geen cookie geschreven vóór een toestemming. Bij `revoked` stopt de tag en verwijdert hij zijn cookie.
- **Het gaat boven elke banner.** Zodra je pagina het heeft aangeroepen, volgt de tag jouw aanroep en negeert hij wat een banner zegt.
- **Global Privacy Control wint van alles.** Een browser die het meestuurt, blijft geweigerd voor het hele bezoek, wat je pagina ook aanroept.

Zonder de aanroep leest de tag het antwoord uit de toestemmingstool van de pagina: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, de HubSpot-banner, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP en Google Consent Mode v2. Bij sommige moet Nodale als vendor of als dienst worden aangemeld: de gids voor bezoektracking in de app geeft de setup voor elk ervan.

## Debuggen

De tag gooit nooit een fout in je pagina. Hij legt zichzelf uit op `console.debug`, in regels die beginnen met `nodale tag:`. Zet het verbose-niveau van je browserconsole aan om ze te zien.

| Regel | Wat er gebeurde |
|---|---|
| `open refused` | Het argument is geen plain object, of het bevat een andere key dan `email` en `context`. |
| `open email dropped` | `email` is geen string van 1 tot 254 tekens. |
| `open context dropped` | `context` schendt een van zijn regels. |
| `open needs the floating or hidden display` | De workspace gebruikt de knopweergave, of de pagina mount de agent inline. |
| `open: agent not on this page` | Een paginaregel of het aandeel bezoekers houdt de agent van deze pagina. |
| `open not acknowledged` | De widget heeft niet binnen 30 seconden geantwoord. |

## Docs

- [De Nodale-agent op je website installeren](https://nodale.ai/nl/docs): Eén scripttag zet de Nodale-agent op je site. Waar je hem plakt, wat je site moet toestaan en hoe je controleert dat hij draait. (Markdown: https://nodale.ai/nl/docs.md)
- [MCP-server: beheer je Nodale-workspace vanuit Claude Code](https://nodale.ai/nl/docs/mcp): Verbind Claude Code met de MCP-server van Nodale en lees en wijzig je workspace: kennis, demo-assets, agentinstellingen, sites, deployment. (Markdown: https://nodale.ai/nl/docs/mcp.md)
