---
title: API & eventi
description: L'API JavaScript del widget Audin — i metodi e gli eventi di AudinChat (popup) e AudinEmbed (embedded), con le differenze tra le due modalità.
---

Una volta caricato lo script, il widget espone un oggetto globale su `window`
che puoi usare per inizializzarlo, controllarlo e reagire agli eventi:

- **Popup** → `window.AudinChat`
- **Embedded** → `window.AudinEmbed`

I due oggetti condividono il modello (`init`, `on`, `destroy`), ma **non hanno la
stessa superficie**: il popup, avendo una bolla che si apre e si chiude, espone in
più `open()`/`close()` e i relativi eventi. L'embedded è sempre inline, quindi non
ha né `open`/`close` né quegli eventi.

## Metodi per modalità

| Metodo | `AudinChat` (popup) | `AudinEmbed` (embedded) |
|---|:---:|:---:|
| `init(options?)` | ✓ | ✓ |
| `on(event, cb)` | ✓ | ✓ |
| `destroy()` | ✓ | ✓ |
| `open()` | ✓ | — |
| `close()` | ✓ | — |

### `init(options?)`

Inizializza il widget: inietta l'iframe della chat e avvia la connessione. Va
chiamato **una sola volta** — chiamate successive sono ignorate (no-op).

L'unico argomento è l'oggetto opzioni, con un solo campo documentato:

```ts
init(options?: {
  user?: {
    email?: string;
    phone?: string;
    fullName?: string;
    customData?: Record<string, unknown>;
  };
}): void
```

Tipicamente è già richiamato dallo snippet di installazione nell'handler `onload`
del loader. Vedi [Dati utente & lead matching](/docs/widget/dati-utente) per il
dettaglio dei campi `user`.

### `open()` / `close()` — solo popup

Apre o chiude la bolla della chat **a livello di codice**, senza che l'utente clicchi.
Esistono solo su `AudinChat`:

```js
// Apri la chat da un tuo bottone
document.querySelector("#aiuto").addEventListener("click", () => {
  AudinChat.open();
});

// Chiudila programmaticamente
AudinChat.close();
```

L'embedded è sempre visibile inline, quindi non espone questi metodi.

### `on(event, cb)`

Sottoscrive una callback a un evento del widget (vedi [Eventi](#eventi)). Disponibile
su entrambe le modalità (cambiano gli eventi emessi):

```js
AudinChat.on("message", (data) => {
  console.log("Nuovo messaggio nella chat", data);
});
```

### `destroy()`

Smonta il widget: rimuove l'iframe dalla pagina e chiude la connessione.
Disponibile su entrambe le modalità. Utile nelle **single-page application**
quando devi rimuovere completamente il widget (vedi
[Configurazione & comportamento](/docs/widget/configurazione-e-comportamento)).

## Eventi

Ti iscrivi agli eventi con `on(event, cb)`. Anche gli **eventi disponibili dipendono
dalla modalità**: solo il popup ha apertura/chiusura, quindi solo lui emette `open`
e `close`. Entrambe le modalità emettono `message`.

| Evento | `AudinChat` (popup) | `AudinEmbed` (embedded) | Quando |
|---|:---:|:---:|---|
| `message` | ✓ | ✓ | È arrivato un messaggio nella chat. La callback riceve il `data` del messaggio. |
| `open` | ✓ | — | La bolla della chat si apre. |
| `close` | ✓ | — | La bolla della chat si chiude. |

<Callout type="info">
  L'embedded emette **solo** `message`: essendo sempre inline non ha uno stato
  aperto/chiuso e quindi non genera `open`/`close`. Iscriversi a `open`/`close` su
  `AudinEmbed` non produce errori, ma le callback non verranno mai chiamate.
</Callout>

### Esempio — popup

```js
AudinChat.on("open", () => {
  // es. tracking: la chat è stata aperta
});

AudinChat.on("close", () => {
  // es. tracking: la chat è stata chiusa
});

AudinChat.on("message", (data) => {
  // un messaggio è arrivato nella conversazione
});
```

### Esempio — embedded

```js
AudinEmbed.on("message", (data) => {
  // un messaggio è arrivato nella conversazione inline
});
```

<Callout type="info">
  Il payload dell'evento `message` (`data`) rappresenta il messaggio ricevuto nella
  chat. Trattalo come un valore opaco per integrazioni semplici (es. logging,
  tracking dell'attività): la sua struttura interna non fa parte della superficie
  pubblica e può cambiare.
</Callout>

## Prossimi passi

<Cards>
  <Card href="/docs/widget/configurazione-e-comportamento" title="Configurazione & comportamento" description="Cosa si configura nel dashboard vs lato codice, SPA, init/destroy e coesistenza popup + embedded." />
  <Card href="/docs/widget/dati-utente" title="Dati utente & lead matching" description="I campi user passati a init() e come collegano la chat a un lead." />
</Cards>