Copy page

Guides

Fenêtre de conversation

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, avec Maude et Antoine.

Installer

Code
<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).
• /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

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

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

Code
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

Code
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.
• 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.