# SDK JavaScript : piloter le widget de chat depuis votre page

> Ouvrez et fermez la bulle de chat intoCHAT depuis votre propre code, identifiez les visiteurs connectés, changez la langue du widget et écoutez les événements du chat avec window.IntoChat.

Le script d'intégration ajoute `window.IntoChat` à votre page. Grâce à lui, votre propre JavaScript peut ouvrir et fermer la bulle de chat, indiquer à l'agent qui est le visiteur connecté, changer la langue du widget et réagir à ce qui se passe dans le chat.

## Avant de commencer

Le SDK est fourni avec la [balise script](/fr/docs/script-tag). Il n'y a rien d'autre à installer :

```html
<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>
<script>
  window.IntoChat.on("reply", function (event) {
    console.log("The agent replied:", event.text);
  });
</script>
```

`window.IntoChat` existe dès que le script s'est exécuté, avant même le chargement de la fenêtre de chat. Les appels faits tôt attendent que la bulle et la fenêtre de chat soient prêtes : vous pouvez donc appeler n'importe quelle méthode juste après le snippet.

Le SDK ne fonctionne qu'avec la bulle de chat ajoutée par le script. Une [iframe dans la page ou un lien direct](/fr/docs/iframe-and-link) n'a aucun script sur la page avec lequel communiquer.

## Méthodes

| Méthode | Effet |
| --- | --- |
| `IntoChat.open()` | Ouvre la fenêtre de chat |
| `IntoChat.close()` | La ferme |
| `IntoChat.toggle()` | L'ouvre si elle est fermée, la ferme si elle est ouverte |
| `IntoChat.identify(user)` | Indique à l'agent qui est le visiteur connecté ; voir [identify](#identify) |
| `IntoChat.reset()` | Oublie l'identité du visiteur et démarre un nouveau chat |
| `IntoChat.setLanguage(code)` | Change la langue du widget |
| `IntoChat.on(event, callback)` | Appelle `callback` quand `event` se produit |
| `IntoChat.off(event, callback)` | Cesse de l'appeler |

### open, close et toggle

```html
<button type="button" onclick="IntoChat.open()">Chat with us</button>
```

Ouvrir le chat de cette façon compte comme une utilisation du chat par le visiteur : les messages d'accueil au-dessus de la bulle et l'ouverture automatique ne s'affichent donc plus ensuite pendant cette visite.

`IntoChat.open()` fonctionne aussi pour les visiteurs qui ne voient pas la bulle à cause de [Afficher le chat à une partie des visiteurs](/fr/docs/appearance#afficher-le-chat-a-une-partie-des-visiteurs). Ce déploiement progressif ne masque que la bulle et ses invitations : un bouton « Discutez avec nous » sur votre page ouvre donc toujours le chat pour tout le monde. Pour ces visiteurs, la fenêtre de chat se charge à sa première ouverture. Avec [Center Stage](/fr/docs/appearance#comment-le-chat-s-ouvre), `open()` ouvre la fenêtre centrée, et `close()` la ferme comme la touche Échap.

### identify

```js
IntoChat.identify({
  userId: "4711",                  // required: the user's id on your site
  userHash: "9f2c…",               // required: computed on your server
  name: "Ada Lovelace",            // optional
  email: "ada@example.com",        // optional
  metadata: { plan: "pro", seats: 3 } // optional
});
```

`identify` est le mécanisme de la [vérification d'identité](/fr/docs/identity-verification). `userHash` est le HMAC-SHA256 de `userId`, avec le secret d'identité de votre agent comme clé, calculé sur votre serveur : personne ne peut donc se faire passer pour un autre utilisateur. Sans `userHash` valide, le visiteur reste simplement non vérifié.

| Champ | Règles |
| --- | --- |
| `userId` | Obligatoire. Du texte (un nombre est converti en texte), jusqu'à 200 caractères. Signez exactement cette valeur. |
| `userHash` | Obligatoire. 64 caractères hexadécimaux. |
| `name` | Facultatif. Jusqu'à 100 caractères. |
| `email` | Facultatif. Une adresse e-mail valide, jusqu'à 254 caractères. |
| `metadata` | Facultatif. Un objet plat de 20 clés au maximum. Les clés utilisent des lettres, des chiffres et des tirets bas (jusqu'à 40 caractères) ; les valeurs sont du texte (jusqu'à 500 caractères), des nombres ou `true`/`false`. 2 Ko au maximum au total. |

`identify` renvoie `true` quand les données respectent ces règles, et `false` (avec un avertissement dans la console du navigateur) dans le cas contraire. La validité de la signature n'est vérifiée que par le serveur d'intoCHAT, quand le visiteur envoie un message.

Appelez `identify` à chaque chargement de page tant que le visiteur est connecté. Identifier un autre utilisateur que le dernier sur ce navigateur démarre automatiquement un nouveau chat : une personne ne voit donc jamais la conversation d'une autre. Un visiteur qui a discuté avant de se connecter garde ce chat.

### reset

```js
IntoChat.reset();
```

Appelez-la quand le visiteur se déconnecte. Elle oublie l'identité et démarre un nouveau chat vide. La liste des chats précédents sur ce navigateur est aussi vidée ; les conversations elles-mêmes restent dans votre tableau de bord.

### setLanguage

```js
IntoChat.setLanguage("de");
```

Affiche les textes propres au widget (boutons, libellés, avis) en anglais (`en`), allemand (`de`), français (`fr`), italien (`it`) ou espagnol (`es`). Un code régional comme `de-CH` compte comme `de`. Tout autre code renvoie `false`. Elle remplace l'attribut `lang` de votre page : elle n'a donc aucun effet si vous avez choisi une langue de widget fixe dans l'onglet [Appearance](/fr/docs/appearance). Elle ne change ni vos messages d'accueil ni la langue dans laquelle l'agent répond.

### on et off

```js
function onReply(event) {
  analytics.track("chat_reply", { agent: event.chatbotId });
}

IntoChat.on("reply", onReply);
// later
IntoChat.off("reply", onReply);
```

`on` renvoie aussi une fonction qui retire l'écouteur. Un écouteur qui lève une erreur n'empêche pas les autres de s'exécuter ; l'erreur est consignée dans la console.

## Événements

Chaque callback reçoit un objet. Il contient toujours `chatbotId`, l'agent d'où vient l'événement.

| Événement | Quand | Champs supplémentaires |
| --- | --- | --- |
| `open` | La fenêtre de chat s'est ouverte : par le visiteur, par votre code ou par l'ouverture automatique | aucun |
| `close` | La fenêtre de chat s'est fermée | aucun |
| `message` | Le visiteur a envoyé un message | `text` |
| `reply` | L'agent a terminé une réponse | `text` : la réponse sans les fiches produits, boutons, formulaires ou sources affichés en dessous |
| `lead` | Le visiteur a envoyé le [formulaire de contact](/fr/docs/lead-collection) | aucun |
| `booking` | Le visiteur a réservé un créneau avec la [réservation](/fr/docs/booking) | aucun |
| `live_chat` | Le statut du [chat en direct](/fr/docs/live-chat) a changé pendant que la page était ouverte | `status` : `requested`, `active`, `ended` ou `null` |

```js
IntoChat.on("live_chat", function (event) {
  if (event.status === "active") document.title = "A team member is chatting with you";
});
```

Les événements `lead` et `booking` ne se déclenchent pas dans un chat temporaire, car ces fonctions n'y sont pas proposées. Des coordonnées que le visiteur saisit dans le chat, au lieu d'utiliser le formulaire, ne déclenchent pas `lead`.

## Appeler le SDK avant le chargement du script

Si votre code peut s'exécuter avant le snippet, ajoutez les appels à `window.IntoChatQueue`. Chaque entrée est le nom de la méthode suivi de ses arguments :

```html
<script>
  window.IntoChatQueue = window.IntoChatQueue || [];
  window.IntoChatQueue.push(["identify", { userId: "4711", userHash: "9f2c…" }]);
  window.IntoChatQueue.push(["on", "lead", function () { console.log("New lead"); }]);
</script>
<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>
```

Le script applique la file à son chargement. Les ajouts ultérieurs s'exécutent immédiatement.

## Plusieurs agents sur une même page

Avec les snippets de plusieurs agents sur une même page, chaque appel s'applique à toutes leurs bulles, et le `chatbotId` de chaque événement indique de quel agent il vient. Chaque agent a son propre secret d'identité : un `userHash` ne vérifie donc le visiteur que pour l'agent dont le secret l'a signé.

## Lien avec IntoChatActions

`window.IntoChatActions` est distinct et fonctionne exactement comme avant : il exécute les [actions côté client](/fr/docs/client-actions) quand l'agent les appelle. `IntoChat` sert à votre propre code pour piloter le widget. Les deux peuvent être utilisés ensemble. Quand le visiteur est vérifié, un gestionnaire d'action côté client le reçoit aussi dans `context.user` :

```js
IntoChatActions.register("Get_cart", async function (args, context) {
  // context.user: { id, name, email, metadata }, only for a verified visitor
  return { items: window.myStore.cart.items };
});
```

## Sécurité

La fenêtre de chat s'exécute sur le domaine d'intoCHAT. Le script de votre page n'échange des messages qu'avec sa propre fenêtre de chat, et seulement tant que cette fenêtre affiche intoCHAT : les autres frames de votre page ne peuvent ni recevoir l'identité du visiteur, ni envoyer de faux événements, ni déclencher d'actions. Les événements transportent ce que le visiteur a saisi et les réponses de l'agent : traitez-les comme toute autre donnée de visiteur sur votre page.