# API JavaScript: apri l'agente Nodale dal tuo codice

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

I comandi nodale() che una pagina può chiamare: apri l'agente da un tuo pulsante o form, passa email e contesto, segnala il consenso del visitatore.

Una volta [installato il tag](https://nodale.ai/it/docs), la tua pagina può inviargli comandi tramite una sola funzione, `nodale()`. I comandi sono due: `open` e `consent`. Il tag non espone nessun altro metodo e non invia nessun evento alla tua pagina.

## La coda dei comandi

Il tag definisce `window.nodale` quando viene eseguito. Per chiamare un comando prima che il tag sia caricato, incolla questo stub sopra di lui. I comandi aspettano in una coda finché il tag non è pronto:

```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>
```

Mantieni il `||`. Uno script che in seguito assegna `window.nodale` senza di esso rimuove il comando del tag, e le chiamate successive vanno a vuoto.

## `nodale('open')`

Apre l'agente dal tuo codice, per esempio da un tuo pulsante o dopo l'invio di un tuo form.

```js
nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Contatti al mese': '1500' }
})
```

La chiamata avvia una conversazione scritta nella finestra di dialogo dell'agente. Il microfono non viene richiesto: aspetta il visitatore.

### Opzioni

| Opzione | Tipo | Cosa fa |
|---|---|---|
| `email` | string | L'email del visitatore, quando la tua pagina la conosce già. Il visitatore è identificato prima del saluto dell'agente. |
| `context` | object | Ciò che il visitatore ti ha già detto, in coppie etichetta e risposta. L'agente lo riceve all'avvio della conversazione. Viene registrato sulla conversazione e mai mostrato al visitatore. |

Entrambe sono facoltative. Il tag controlla l'argomento prima che qualcosa lasci la pagina:

- **L'argomento** è assente, oppure è un oggetto semplice senza chiavi diverse da `email` e `context`. In ogni altro caso non si apre nulla.
- **`email`** è una stringa da 1 a 254 caratteri, tolti gli spazi iniziali e finali. Altrimenti viene scartata, e l'agente si apre comunque. Il tag non giudica l'indirizzo: è il server a decidere se accettarlo.
- **`context`** contiene 20 risposte al massimo. Un'etichetta ha da 1 a 60 caratteri, una risposta è una stringa di 300 caratteri al massimo, e un'etichetta si usa una volta sola. A etichette e risposte vengono tolti gli spazi iniziali e finali, e una risposta vuota viene saltata. Se una regola è violata l'intero contesto viene scartato, mai tagliato, e l'agente si apre comunque senza.

`nodale('open')` non lancia mai eccezioni e restituisce `undefined`.

### Dove funziona

- **Solo con la barra e con la visualizzazione `hidden`.** Con la visualizzazione a pulsante, con un `<div data-nodale-agent>` inline, e in una pagina in cui l'agente non viene mostrato (una regola di pagina, o una quota di visitatori), la chiamata non fa nulla. Se usi `open`, tieni disattivata la quota di visitatori, altrimenti per alcuni visitatori la chiamata non fa nulla.
- **Prima che il tag sia caricato**, tramite lo stub qui sopra. Solo l'ultimo `open` in coda viene rieseguito, una volta.
- **Una sola conversazione.** Il widget avvia una conversazione al massimo e conserva la prima email e il primo contesto ricevuti. Un `open` durante una conversazione, o dopo che una è terminata, mostra soltanto la finestra di dialogo.
- **Quando l'agente chiede prima l'email**, la chiamata mostra quel passaggio, e la tua email e il tuo contesto vengono inviati quando il visitatore lo conferma.

### Da un pulsante

```html
<button type="button" onclick="nodale('open')">Fai una domanda</button>
```

### Dopo un tuo form

```js
form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Dimensione aziendale': form.elements.size.value,
      'Cosa vuole fare': form.elements.message.value
    }
  })
})
```

## La visualizzazione hidden

`hidden` è una visualizzazione del workspace, accanto alla barra e al pulsante. Con questa, non si vede nulla finché la tua pagina non chiama `nodale('open')`.

- **La pagina resta del tutto utilizzabile.** Il frame dell'agente è montato ma invisibile, e non intercetta nessun clic.
- **Una volta aperta, è la barra.** Chiudere la finestra di dialogo riporta alla barra e conserva la conversazione. La barra resta poi per il resto della scheda del browser.
- **La scheda del browser se lo ricorda.** Una pagina successiva del tuo sito nella stessa scheda mostra subito la barra, così il visitatore ritrova la conversazione. Il tag lo conserva in `sessionStorage`, in una chiave che non contiene nessun identificativo. Una nuova scheda parte nascosta.
- **Testata solo nei browser Chromium.** Safari e Firefox non sono ancora coperti dai nostri test su browser: un browser che rallenta i frame invisibili può rispondere a `open` più tardi.

## `nodale('consent')`

Dice al tag se il visitatore ha accettato il tracciamento delle visite. Usalo quando il tuo sito non ha un banner dei cookie che il tag sa leggere, o quando gestisci tu il consenso.

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

- **Conta solo quando il tracciamento delle visite è attivo** nel tuo workspace. Il tracciamento è disattivato per impostazione predefinita, e l'agente viene montato in entrambi i casi.
- **Il tracciamento parte negato.** Nulla viene richiesto e nessun cookie viene scritto prima di un consenso. Con `revoked`, il tag si ferma ed elimina il suo cookie.
- **Prevale su ogni banner.** Una volta che la tua pagina l'ha chiamato, il tag segue la tua chiamata e ignora ciò che dice un banner.
- **Global Privacy Control vince su tutto.** Un browser che lo invia resta negato per tutta la visita, qualunque cosa chiami la tua pagina.

Senza la chiamata, il tag legge la risposta dallo strumento di consenso della pagina: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, il banner di HubSpot, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP e Google Consent Mode v2. Alcuni richiedono che Nodale sia dichiarato come fornitore o come servizio: la guida al tracciamento delle visite nell'app dà la configurazione per ciascuno.

## Debug

Il tag non lancia mai eccezioni nella tua pagina. Si spiega su `console.debug`, in righe che iniziano con `nodale tag:`. Attiva il livello verbose della console del tuo browser per vederle.

| Riga | Cosa è successo |
|---|---|
| `open refused` | L'argomento non è un oggetto semplice, oppure contiene una chiave diversa da `email` e `context`. |
| `open email dropped` | `email` non è una stringa da 1 a 254 caratteri. |
| `open context dropped` | `context` viola una delle sue regole. |
| `open needs the floating or hidden display` | Il workspace usa la visualizzazione a pulsante, oppure la pagina monta l'agente inline. |
| `open: agent not on this page` | Una regola di pagina o la quota di visitatori tiene l'agente fuori da questa pagina. |
| `open not acknowledged` | Il widget non ha risposto entro 30 secondi. |

## Docs

- [Installa l'agente Nodale sul tuo sito web](https://nodale.ai/it/docs): Un solo tag script porta l'agente Nodale sul tuo sito. Dove incollarlo, cosa deve consentire il sito e come verificare che funzioni. (Markdown: https://nodale.ai/it/docs.md)
- [Server MCP: gestisci il tuo workspace Nodale da Claude Code](https://nodale.ai/it/docs/mcp): Collega Claude Code al server MCP di Nodale, poi leggi e modifica il workspace: knowledge, asset demo, impostazioni dell'agente, siti, deployment. (Markdown: https://nodale.ai/it/docs/mcp.md)
