> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget web

> Intégrez votre assistant sous forme de widget vocal et de chat sur n'importe quel site web

Le widget web installe votre assistant sur votre site : les visiteurs cliquent sur un bouton et **parlent à l'assistant dans le navigateur** (sans téléphone ni application requis), ou tapent dans un **chat** avec ce même assistant. Le widget est disponible lorsqu'il est inclus dans votre forfait.

## Voix + chat, un seul assistant

* **Voice** — un clic déclenche une conversation vocale en direct qui utilise la configuration complète de l'assistant : mode moteur, voix, base de connaissances, outils, garde-fous. Les appels web apparaissent dans l'[Historique](/fr/monitoring/history) avec la direction `web`.
* **Chat** — le même assistant, les mêmes prompts et la même base de connaissances, mais sous forme de texte, pour les visiteurs qui ne peuvent pas ou ne veulent pas parler.

Les deux canaux partageant une seule configuration d'assistant, vous gérez le comportement à un seul endroit.

## Intégration

Créez un widget sous **Settings → Channels → Web Widget**, puis collez un extrait depuis l'éditeur. Choisissez **Display** :

<Tabs>
  <Tab title="Floating">
    Le réglage par défaut — une bulle de lancement dans un coin. Position et Initial state s'appliquent. Privilégiez le chargeur **script** (il définit automatiquement `allow="microphone"` sur l'iframe) :

    ```html theme={null}
    <script
      src="https://YOUR-DOMAIN/widget.js"
      data-famulor-key="wgt_YOUR_PUBLIC_KEY"
      async
    ></script>
    ```
  </Tab>

  <Tab title="Inline">
    Le widget s'intègre dans le flux de votre page (sans lanceur). Privilégiez l'extrait web component ou iframe (dimensionnement portrait inclus pour les cartes avatar) :

    ```html theme={null}
    <famulor-widget
      data-key="wgt_YOUR_PUBLIC_KEY"
      style="display:block;width:100%;max-width:360px;aspect-ratio:9/16;border-radius:20px;overflow:hidden;"
    ></famulor-widget>
    <script src="https://YOUR-DOMAIN/widget.js" async></script>
    ```

    Ou montez-le dans un nœud cible : `data-famulor-target="#famulor-assistant"` sur la balise script.
  </Tab>
</Tabs>

Consultez le panneau d'intégration pour des extraits HTML, React et Markdown prêts à l'emploi. Sur les domaines en marque blanche, le widget est servi depuis **votre domaine de tenant** avec votre image de marque.

## Origines autorisées

Indiquez le ou les sites qui peuvent intégrer le widget (origines exactes comme `https://example.com`, ou jokers de sous-domaine comme `*.example.com`). Localhost est pris en charge pour le développement. Les origines sont **facultatives** à la création ou à l'enregistrement d'un widget.

* Une liste vide ne signifie **pas** « ouvert à tous les sites » : les origines externes sont bloquées. Seul le domaine de la plateforme lui-même reste autorisé, afin que l'aperçu en direct dans l'application continue de fonctionner.
* Ajoutez chaque hôte de site qui chargera l'extrait avant la mise en ligne. Si le widget ne se charge pas sur un site client, vérifiez d'abord Allowed origins.

## Personnalisation

* **Display** — **Floating** (lanceur d'angle) ou **Inline** (intégration dans la page). Position et Initial state ne s'appliquent qu'au mode Floating.
* **Colors and branding** — couleur du lanceur, accent du panneau, logo ; l'image de marque du tenant s'applique automatiquement sur les domaines en marque blanche.
* **Position** — emplacement en coin du lanceur flottant (masqué en Inline).
* **Modes** — voix uniquement, chat uniquement, ou les deux.
* **Voice presence** — visualiseur audio classique, ou un **virtual AI avatar** (voir ci-dessous).
* **Launcher icon** — Milian, Chat bubbles, Question mark, Smiley face, Team, ou Hand wave. S'applique aux modes chat uniquement, voix uniquement et aux deux.
* **Launcher label** — préréglages (**No text** par défaut ; Help, Ask anything, Assistance, Support, Live Chat, Need help?) traduits selon la langue du navigateur du visiteur. En avatar seul, un texte de lanceur personnalisé reste possible pour le CTA en verre.
* **Texts** — message de bienvenue, mention IA, mention de confidentialité.
* **Pre-chat form** — formulaire facultatif avant le démarrage du chat ou de la conversation vocale (voir ci-dessous).

## Avatar IA virtuel

Les avatars virtuels nécessitent la fonctionnalité Avatar IA. Dans l'éditeur du widget, réglez **Voice presence** sur **AI avatar** et choisissez un avatar.

* **Layouts**
  * **Avatar only (full-bleed)** — carte compacte centrée sur le visage. Les widgets flottants peuvent démarrer **Expanded** ou **Minimized** ; en Inline, la carte s'affiche toujours directement en place.
  * **Avatar + chat** — présence avatar avec l'habillage classique du panneau chat/voix.
* **Billing** — les sessions vocales sont facturées au tarif normal de la minute de conversation, plus le supplément **Web widget virtual avatar** par minute tant qu'un avatar virtuel est actif ; les messages de chat texte simple envoyés et reçus facturent des crédits par message au tarif **Web chat (sent)** / **Web chat (received)** de l'espace de travail. Les tarifs actuels figurent sur la [page Usage](https://app.famulor.io/usage) ; voir aussi [Comment l'utilisation est facturée](/fr/billing/minutes).
* Sans accès à l'Avatar IA, l'éditeur affiche une option de mise à niveau et l'API refuse d'activer la présence avatar.

## Formulaire de pré-chat

Ouvrez le widget dans l'éditeur, repérez **Pre-chat form**, et activez **Enable**. Les visiteurs renseignent alors les champs avant le début de la session.

* Les **Suggestions** proviennent des champs de contact (nom, e-mail, téléphone), des variables d'entrée de l'assistant sélectionné et des attributs Audience de l'espace de travail. Vous pouvez aussi ajouter des clés personnalisées.
* Les valeurs soumises deviennent des **input variables** d'appel (`{{variable_key}}`), mettent à jour le lead Audience lorsque des champs d'identité sont renseignés, et apparaissent dans **History**, sous Pre-chat form / Input variables.
* Les champs obligatoires sont validés avant qu'un visiteur puisse démarrer une session.

## À vérifier avant la mise en ligne

<Steps>
  <Step title="Ajoutez au moins une origine autorisée">
    Listez chaque site qui intégrera le widget. Sans origines, les hôtes tiers ne peuvent ni charger la configuration ni émettre de jetons.
  </Step>

  <Step title="Testez d'abord l'assistant avec des appels dans le navigateur">
    Le widget utilise le même circuit d'appel web que l'appel de test de l'éditeur d'assistant : si celui-ci fonctionne bien, le widget fonctionnera aussi.
  </Step>

  <Step title="Attention aux autorisations du microphone">
    Les navigateurs exigent HTTPS pour l'accès au microphone. La page hôte ne doit pas bloquer le microphone via `Permissions-Policy`. Les intégrations script/web component définissent `allow="microphone"` automatiquement sur l'iframe.
  </Step>

  <Step title="Mettez à jour votre politique de confidentialité">
    Les conversations vocales sont traitées comme des appels (transcriptions, enregistrement facultatif avec parcours de consentement). Mentionnez le widget dans votre politique de confidentialité.
  </Step>
</Steps>

## Dépannage

<AccordionGroup>
  <Accordion title="Le widget n'apparaît pas du tout">
    Vérifiez que l'extrait d'intégration se trouve bien avant la balise de fermeture `</body>`, forcez un rechargement complet (ou testez dans une fenêtre privée) pour écarter un HTML mis en cache, vérifiez que votre forfait inclut le widget web, et recherchez des erreurs JavaScript dans la console du navigateur. Recopiez l'extrait depuis l'éditeur du widget si vous avez changé la clé du connecteur depuis.
  </Accordion>

  <Accordion title="Le widget se charge ailleurs mais pas sur ce site">
    Vérifiez d'abord **Allowed origins**. Une liste vide bloque volontairement tout hôte externe, par conception ; ajoutez l'origine exacte (ou un joker `*.example.com`) sur laquelle le widget est intégré.
  </Accordion>

  <Accordion title="La voix ne démarre pas">
    La voix nécessite HTTPS. Vérifiez que la page est servie en HTTPS, que le navigateur a accordé l'autorisation du microphone, que le microphone fonctionne dans d'autres applications, et qu'aucun VPN ni pare-feu ne bloque WebRTC. Les intégrations script et web component définissent `allow="microphone"` automatiquement — une intégration iframe brute nécessite l'ajout manuel de cet attribut.
  </Accordion>

  <Accordion title="Le chat ne répond pas">
    Recherchez des erreurs dans la console du navigateur, vérifiez que l'assistant fonctionne depuis un appel/chat de test dans l'éditeur d'assistant, et rechargez la page pour démarrer une nouvelle session de widget.
  </Accordion>

  <Accordion title="Les réponses du formulaire de pré-chat n'atteignent pas l'assistant">
    Les réponses arrivent sous la clé de chaque champ ; choisissez donc la suggestion (ou définissez la clé personnalisée) qui correspond à la variable lue par votre assistant, puis enregistrez le widget avant de retester.
  </Accordion>

  <Accordion title="Les modifications de l'éditeur ne s'affichent pas">
    Assurez-vous d'avoir enregistré les réglages du widget, puis forcez un rechargement complet ou testez dans une fenêtre privée ; un ancien extrait d'intégration mis en cache peut aussi masquer un changement de configuration récent.
  </Accordion>

  <Accordion title="Intégration dans WordPress ou un autre CMS">
    Utilisez un bloc HTML personnalisé, gardez l'extrait avant la balise de fermeture `</body>`, et videz le cache de tout plugin de cache après l'enregistrement. Les plugins de sécurité/pare-feu bloquent parfois le script du widget — désactivez-les un par un pour isoler la cause.
  </Accordion>
</AccordionGroup>

Toujours bloqué ? Testez dans une fenêtre de navigation privée et un second navigateur pour écarter les extensions et l'état en cache, puis contactez le support avec une capture d'écran et le contenu de la console du navigateur.

## API & MCP

Gérez les widgets par programmation via l'API REST publique (`/api/v1/widget-connectors`) et les outils MCP (`create_widget_connector`, `update_widget_connector`, …). `allowed_origins` est facultatif ; vide ou omis bloque les hôtes tiers. Portée : `assistants:write`. L'accès au widget et à l'Avatar IA dépend de votre forfait.

Les nouveaux widgets réutilisent d'abord le portrait de l'assistant sélectionné comme logo d'en-tête, s'il est disponible. Vous pouvez ensuite le remplacer ou le supprimer.