> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/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 pour **parler à l'assistant directement dans le navigateur** (WebRTC — sans téléphone, sans application) ou pour écrire dans un **chat** avec ce même assistant. La disponibilité dépend de votre plan (`web_widget`).

## Voix + chat, un seul assistant

* **Voix** — 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 votre historique d'appels 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 **Paramètres → Canaux → Widget web**, puis choisissez **Affichage** :

* **Flottant** (défaut) — bulle dans un coin ; Position et État initial s’appliquent. Préférez le chargeur script (`allow="microphone"`) :

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

* **Inline** — widget dans le flux de la page (sans lanceur). Préférez le web component ou l’iframe :

```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 script avec cible : `data-famulor-target="#famulor-assistant"`. Le panneau d’intégration propose des extraits HTML, React et Markdown.

## Origines autorisées

Listez le(s) site(s) 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 et à l'enregistrement.

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

## Personnalisation

* **Affichage** — **Flottant** (lanceur d’angle) ou **Inline** (intégration dans le flux). Position et État initial ne s’appliquent qu’au mode Flottant.
* **Couleurs et image de marque** — couleur du lanceur, accent du panneau, logo ; l'image de marque du locataire s'applique automatiquement sur les domaines en marque blanche.
* **Position** — emplacement du lanceur flottant (masqué en Inline).
* **Modes** — voix uniquement, chat uniquement, ou les deux.
* **Présence vocale** — visualiseur audio classique, ou un **avatar IA virtuel** (voir ci-dessous).
* **Textes** — libellé du lanceur, message de bienvenue, mention IA, mention de confidentialité.
* **Formulaire de pré-chat** — formulaire facultatif avant le démarrage du chat ou de la conversation vocale (voir ci-dessous).

## Avatar IA virtuel

Fonctionnalité séparée liée au plan (`ai_avatar`). Dans l'éditeur du widget, réglez **Présence vocale** sur **AI avatar** et choisissez un avatar.

* **Mises en page**
  * **Avatar only (full-bleed)** — carte compacte centrée sur le visage (style Anam). Flottant : **Développé** ou **Réduit** ; Inline affiche la carte directement dans la page.
  * **Avatar + chat** — présence avatar avec le panneau chat/voix classique.
* **Facturation** — les minutes vocales avec avatar facturent le tarif minute de conversation **plus un supplément avatar** (actuellement **+80 crédits/min**). Voir [Comment les minutes sont facturées](/billing/minutes) et Usage dans l'application.
* Sans `ai_avatar` sur le plan, l'éditeur affiche une invitation à mettre à niveau et l'API refuse d'activer la présence avatar.

## Formulaire de pré-chat

Dans **Widgets →**, ouvrez un connecteur, puis activez **Formulaire de pré-chat**. Les visiteurs renseignent 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 **variables d'entrée** de l'appel (`{{variable_key}}`), mettent à jour le lead Audience lorsque des champs d'identité sont renseignés, et apparaissent dans l'**Historique**, sous Formulaire de pré-chat / Variables d'entrée.
* La configuration est stockée sur le connecteur du widget (`theme.preform`) et exposée dans la configuration publique du widget ; le point de terminaison du jeton valide les champs obligatoires.

## À 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 accéder 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"` sur l'iframe automatiquement.
  </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>

## API & MCP

Gérez les widgets via l'API REST publique (`/api/v1/widget-connectors`) et les outils MCP (`create_widget_connector`, `update_widget_connector`, …). `allowed_origins` est facultatif (vide/omis bloque les hôtes tiers). Portée : `assistants:write`. Plan : `web_widget` (présence avatar : aussi `ai_avatar`).