# Fenêtre de conversation

:::warning{title="Préversion"}

La fenêtre fait partie du SDK en préversion (0.x) : son interface peut encore évoluer.

:::

`Twimi.widget` pose dans votre site la **fenêtre de conversation** d'un avatar Twimi. Le visiteur pose sa question par écrit, au micro ou en touchant une suggestion. L'avatar répond à voix haute, avec son visage qui parle, et par écrit. Formules **Avatar Widget** et **Avatar Agent**.

**[Voir la démonstration](https://api-dev.atwimi.com/v1/sdk/demo/widget.html)**, avec Maude et Antoine.

## Installer

```html
<script src="https://api-dev.atwimi.com/v1/sdk/twimi.js"></script>
<script>
  const tw = await Twimi.init({ key: "pk_test_…", avatar: "maude" });
  const w = tw.widget({
    subtitle: "Conseillère · Concession Dupont",
    chips: ["Vos horaires ?", "Réserver un essai"],
  });
</script>
```

Une bulle apparaît en bas à droite de la page. Le visiteur l'ouvre, et la conversation commence.

- Utilisez la **clé publique** (`pk_…`), depuis une page déclarée pour votre déploiement (voir [Clés et jetons](/authentification)).
- `/v1/sdk/twimi.js` est la dernière version 0.x ; `/v1/sdk/0.5.0/twimi.js` est une version figée, qui ne change jamais (conseillé en production).
- Le visage ne se charge qu'à la première ouverture : un visiteur qui n'ouvre pas la bulle ne télécharge rien de plus.

### Sans écrire de JavaScript

```html
<script src="https://api-dev.atwimi.com/v1/sdk/twimi.js"></script>
<twimi-widget key="pk_test_…" avatar="maude"
  subtitle="Conseillère · Concession Dupont"
  chips="Vos horaires ?|Réserver un essai"></twimi-widget>
```

Les suggestions sont séparées par `|`. Ajoutez l'attribut `inline` pour une fenêtre intégrée à la place de la balise, au lieu d'une bulle.

## Options

| Option | Rôle | Par défaut |
| --- | --- | --- |
| `welcome` | message d'accueil | « Bonjour, je suis Maude. Comment puis-je vous aider ? » (avec le nom de l'avatar), dans la langue de la page |
| `chips` | suggestions de questions à l'ouverture (6 au plus) | aucune |
| `subtitle` | ligne sous le nom de l'avatar | aucune |
| `mode` | `"voice"` : l'avatar dit ses réponses ; `"text"` : il répond par écrit. Le visiteur peut changer avec le bouton du haut-parleur. | `"voice"` |
| `position` | `"bottom-right"` ou `"bottom-left"` | `"bottom-right"` |
| `container` | élément (ou sélecteur) où intégrer la fenêtre, toujours ouverte, sans bulle | bulle flottante |
| `color` | couleur principale `#RRGGBB` ; le texte posé dessus reste lisible | couleur de l'avatar |
| `theme` | `"light"`, `"dark"` ou `"auto"` (suit le réglage du visiteur) | `"light"` |
| `open` | ouvrir dès le chargement | fermée |
| `page` | page consultée, envoyée avec chaque question | le chemin de l'adresse |
| `lang` | langue de l'interface : `fr`, `en`, `es` | celle de `Twimi.init`, sinon `<html lang>` |
| `zIndex` | ordre d'empilement de la bulle | très haut |
| `remember` | reprendre la conversation d'une page à l'autre du site | `true` |

L'avatar répond dans la langue de la question, quelle que soit la langue de l'interface.

## Piloter la fenêtre depuis votre site

```js
w.open();                                    // ouvrir
w.close();                                   // fermer (la parole s'arrête)
await w.ask("Puis-je réserver un essai ?");   // poser une question depuis un bouton de votre page
w.setPage("/catalogue/suv");                 // application d'une seule page : la page consultée a changé
w.setMode("text");                           // passer à l'écrit (ou "voice")
w.addAction({                                // un bouton à vous, sous la conversation
  id: "rdv",
  label: "Prendre rendez-vous",
  href: "https://www.exemple.fr/rendez-vous", // ou onClick: () => { … }
  afterFirstQuestion: true,                   // seulement après la première question
});
w.removeAction("rdv");
w.destroy();                                 // retirer la fenêtre et terminer la conversation
```

## Événements

```js
w.on("ready", ({ avatar, version }) => {});
w.on("open", () => {});
w.on("close", () => {});
w.on("question", ({ text, source }) => {});        // source : typed, voice, chip ou site
w.on("answer", ({ text, chips, products }) => {}); // réponse complète
w.on("start", ({ duration }) => {});               // l'avatar commence une phrase
w.on("end", () => {});
w.on("voice_limit", ({ reason }) => {});           // la suite se fait par écrit
w.on("error", ({ code, message }) => {});
```

Sur la balise, les mêmes événements s'appellent `twimi-ready`, `twimi-answer`… et leur contenu est dans `event.detail`. Une erreur dans votre gestionnaire n'arrête jamais la fenêtre.

## Ce que fait la fenêtre pour vous

- **Réponse en flux** : le texte s'écrit au fil de l'eau, et l'avatar commence à parler sans attendre la fin.
- **Choix proposés** : quand l'avatar finit sa réponse par des choix, ils deviennent des boutons. Ils ne sont jamais dits à voix haute.
- **Produits** : les articles cités par l'avatar s'affichent en vignettes cliquables.
- **Micro** : la question est enregistrée (30 secondes au plus), transcrite par l'API, puis posée. Le son n'est pas conservé. Le bouton n'apparaît que si le navigateur sait enregistrer.
- **Passage à l'écrit** : forfait du mois atteint, fusible ou plafond de la conversation. L'API refuse alors la voix ; la fenêtre cache le micro, prévient le visiteur et continue par écrit (événement `voice_limit`). Voir [Voix et décompte](/voix-et-decompte).
- **Sécurité** : rien de la réponse n'est inséré en HTML. Seuls le texte, le gras, les liens `http(s)` et les retours à la ligne sont affichés.
- **Style isolé** : celui de votre site ne touche pas la fenêtre, et inversement.
- **Téléphone** : la fenêtre ouverte prend tout l'écran.
- **D'une page à l'autre** : quand le visiteur change de page sur votre site (même onglet), la fenêtre reprend la conversation, avec ses messages et son état (ouverte ou fermée). L'API la reprend **sans nouveau décompte** tant qu'elle a servi il y a moins de 30 minutes. Un nouvel onglet repart de zéro. Pour repartir de zéro à chaque page : `remember: false`.

## Le son bloqué par le navigateur

Les navigateurs interdisent de jouer un son avant un geste du visiteur. Ouvrir la bulle, toucher une suggestion ou envoyer une question suffit. Si vous appelez `w.ask()` sans clic, la réponse s'écrit, et la voix part au premier geste.

## Limites de la préversion

- Le message d'accueil et les suggestions se donnent dans le code de la page.
- Un déploiement correspond à un avatar : une autre clé pour un autre avatar.