Intégrer le Widget de chat (Guide développeur)

Guide d'intégration du widget

Le widget est un Web Component (<web-chat-agent>) qui se charge de manière asynchrone et s'exécute sur n'importe quel site, sans framework ni étape de build. Le script affiche un bouton de chat flottant ; les visiteurs cliquent dessus pour ouvrir la fenêtre de chat.

Code d'intégration

Collez ceci juste avant la balise fermante </body> :

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
></web-chat-agent>

Remplacez YOUR_CHATBOT_ID par votre Identifiant du chatbot. Retrouvez le code d'intégration pré-rempli sous Tableau de bord → votre assistant → Canaux → Widget de chat → Afficher les détails d’installation et copiez-le depuis cet emplacement pour éviter les fautes de frappe.

Le widget appelle l'API sur la même origine que celle depuis laquelle il a été chargé. Chargez le script depuis webchatagent.com et les requêtes de chat sont automatiquement envoyées vers webchatagent.com/api/..., sans jamais avoir à configurer une URL d'API manuellement.

Comment ça marche

1. Le script async se charge en arrière-plan et ne bloque pas le rendu de la page.
2. L'élément <web-chat-agent> affiche un bouton de chat flottant.
3. Le widget récupère vos paramètres du tableau de bord (couleurs, textes, outils, message de bienvenue) et les applique. Aucun attribut supplémentaire n'est nécessaire.
4. Un visiteur clique sur le bouton, la fenêtre de chat s'ouvre et les messages sont envoyés à votre chatbot IA.

Attributs HTML

Chaque paramètre visuel défini dans Canaux → Widget de chat est appliqué automatiquement. Les attributs HTML sur l'élément sont des valeurs de remplacement facultatives, à n'utiliser que pour des ajustements par page (par exemple une position différente sur une landing page spécifique). Les noms d'attributs sont en kebab-case (le widget associe en interne theme-color à la propriété themeColor).

Les valeurs par défaut ci-dessous correspondent aux solutions de repli intégrées du widget. En pratique, la plupart des attributs ne sont pas définis et héritent de la valeur configurée dans le tableau de bord.

Paramètres de base

Couleurs

Tous les attributs de couleur acceptent n'importe quelle couleur CSS valide (hexadécimal comme #2563eb, rgb(), hsl()). Lorsqu'il n'est pas défini, le widget utilise la valeur de votre tableau de bord ou sa valeur de repli intégrée (la couleur par défaut de la marque est le bleu, #2563eb).

Images

Positionnement

Contenu et comportement

Mettre à jour le consentement au moment de l'exécution

window.dispatchEvent(
  new CustomEvent('webchatagent:consent', {
    detail: { tracking: 'granted' }
  })
)

Transmettez denied lorsque le consentement est rejeté ou révoqué. Les déclencheurs locaux anonymes restent disponibles. Consultez le guide sur le consentement aux cookies pour la matrice des déclencheurs et les adaptateurs CMP.

Boutons de suggestion

Boutons d'action rapide affichés sous la liste des messages. Chaque bouton a un title visible et une action (le texte envoyé comme message de l'utilisateur lors du clic). Transmettez un tableau JSON comme valeur d'attribut :

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  prompt-buttons='[{"title":"Talk to support","action":"I need help with my order"},{"title":"Pricing","action":"What does it cost?"}]'
></web-chat-agent>

Session Context Data

Lorsque le widget s'exécute au sein d'un système qui connaît déjà le visiteur, comme un CRM, un portail client ou un espace connecté, la page intégratrice peut transmettre ces informations au chatbot. L'IA accède à ces valeurs, y fait référence dans ses réponses et les utilise pour renseigner les arguments correspondants des connecteurs API et des appels d'outils MCP. Un visiteur dont le numéro de dossier figure déjà à l'écran ne devrait jamais avoir à le saisir de nouveau.

Les données de contexte sont transmises à chaque requête de chat de la session, sont injectées dans le prompt de l'IA pour cette seule requête et ne sont pas enregistrées en tant qu'entrée dédiée.

Transmettre le contexte via l'attribut HTML

Deux formats sont acceptés. Le format simple ne nécessite aucune connaissance de JSON, il s'agit de paires Clé=Valeur séparées par des points-virgules :

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data="Customer=Jane Doe;Company=Acme GmbH;OrderID=A-1023"
></web-chat-agent>

Seul le premier = de chaque paire sépare la clé et la valeur, de sorte que les valeurs contenant des = (par exemple des jetons base64) restent intactes. Une valeur ne peut pas contenir de point-virgule dans ce format, utilisez JSON pour ce cas :

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data='{"Customer":"Jane Doe","Note":"VIP; priority support","OrderID":"A-1023"}'
></web-chat-agent>

Avec JSON, entourez la valeur de l'attribut de guillemets simples afin de préserver les guillemets doubles internes.

Transmettre le contexte via JavaScript

Si vous préférez JavaScript à l'attribut (ou si vous devez l'utiliser, par exemple sur WordPress), définissez la variable globale window.webchatagentContext. Elle peut être définie en toute sécurité avant le chargement du script du widget. Le widget la récupère lors de son initialisation, l'ordre de chargement des scripts n'a donc pas d'importance :

<script>
  window.webchatagentContext = {
    Customer: 'Jane Doe',
    OrderID: 'A-1023',
    userToken: 'opaque-token-validated-by-your-backend'
  }
</script>
<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>

Mettre à jour le contexte à l'exécution

Lorsque les données changent pendant que le widget est déjà actif (connexion, passage à un autre dossier), déclenchez l'événement webchatagent:context avec un objet simple :

window.dispatchEvent(
  new CustomEvent('webchatagent:context', {
    detail: {
      Topic: 'billing',
      OrderID: 'A-1023'
    }
  })
)

Chaque événement remplace l'ensemble du contexte ; detail: null ou {} l'efface. Ordre de priorité au chargement : l'attribut context-data est appliqué en premier, puis window.webchatagentContext (s'il est défini), puis les événements éventuels. Le contexte réside dans la page, il convient de le définir à nouveau après un rechargement.

Déploiements en marque blanche : les alias neutres window.chatWidgetContext (global) et chat-widget:context (événement) fonctionnent à l'identique, de sorte que les pages intégratrices n'ont jamais besoin de faire référence au nom de la plateforme.

Limites

Au maximum 20 clés, noms de clés jusqu'à 64 caractères, valeurs jusqu'à 500 caractères (les nombres et les booléens sont convertis en chaînes), 4 000 caractères au total. Les sauts de ligne et les caractères < > sont supprimés des clés et des valeurs. Les réponses aux requêtes transportant des données de contexte ne sont jamais servies depuis le cache de réponses.

Sécurité : les données de contexte ne constituent pas une authentification

Les valeurs proviennent du navigateur du visiteur. Tout utilisateur peut ouvrir les outils de développement et envoyer un contexte arbitraire, l'IA a donc pour consigne de traiter ces éléments comme des informations contextuelles non vérifiées. Ne basez jamais votre logique d'autorisation sur ces données.

Deux règles pour la production :

1. Restreignez allowedDomains pour votre chatbot dans le tableau de bord. Sans cela, n'importe quelle page peut intégrer votre bot et lui injecter du contexte.
2. Pour la consultation de données personnelles, transmettez un jeton opaque au lieu de l'identité en clair. Générez côté serveur un jeton à courte durée de vie pour l'utilisateur connecté, passez-le en tant que valeur de contexte (par exemple userToken=...), et laissez le point de terminaison de votre connecteur API valider le jeton avant de renvoyer les données utilisateur. L'IA transmet le jeton dans l'appel API, et votre backend détermine ce qu'il déverrouille. Un jeton falsifié ne renverra alors rien.

WordPress

L'extension WordPress (dès sa prochaine version) prend en charge les données de contexte côté serveur : le filtre webchatagent_context_data les fournit pour le widget flottant (et par défaut pour les intégrations inline), et le shortcode inline accepte un attribut context-data :

add_filter('webchatagent_context_data', function () {
    $user = wp_get_current_user();
    return $user->exists() ? 'Customer=' . $user->display_name : '';
});

[webchatagent_inline context-data="Topic=Support;OrderID=A-1023"]

Sur les versions antérieures de l'extension, définissez window.webchatagentContext ou déclenchez l'événement webchatagent:context, les deux approches fonctionnant sur n'importe quelle plateforme.

Exemple : personnalisation complète

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="abc-123-def"
  theme="modern"
  title="Support Chat"
  theme-color="#4f46e5"
  theme-text-color="#ffffff"
  user-message-color="#4f46e5"
  bubble-color="#4f46e5"
  font-family="Inter"
  initially-open="false"
  offset-x="30"
  offset-y="30"
></web-chat-agent>

Tableau de bord vs Attributs HTML

Les paramètres du tableau de bord sont stockés côté serveur et chargés lors de l'initialisation du widget. Les attributs HTML les remplacent pour cette page uniquement.

Recommandation : Effectuez toute la personnalisation visuelle dans le tableau de bord. N'utilisez les attributs HTML que lorsqu'une page nécessite une configuration spécifique : un positionnement différent, un thème forcé ou des boutons de suggestion propres à la page.

CSS personnalisé

Pour les modifications qui vont au-delà des attributs ci-dessus, ciblez les éléments internes du widget avec votre propre CSS. Chaque élément personnalisable porte une classe .wca-* stable (par exemple .wca-header, .wca-message, .wca-bubble), ce qui permet à vos sélecteurs de continuer à fonctionner au fil des mises à jour du widget sans avoir besoin de !important. Vous ajoutez le CSS dans le tableau de bord, et il est injecté dans le Shadow DOM du widget. Consultez CSS personnalisé.

Chat intégré

Pour afficher le chat directement dans la mise en page de votre site plutôt que sous la forme d'un bouton flottant, utilisez la variante inline. Elle charge un script distinct et un élément différent (<web-chat-agent-inline>) :

<script src="https://webchatagent.com/widget/chat-widget-inline.js" async></script>
<web-chat-agent-inline chatbot-id="YOUR_CHATBOT_ID"></web-chat-agent-inline>

L'élément inline accepte chatbot-id, un container-height facultatif, ainsi que tracking-consent et context-data (voir Session Context Data, l'attribut et l'événement d'exécution fonctionnent ici de manière identique) ; tous les autres paramètres proviennent de Canaux → Chat intégré. Placez l'élément là où vous souhaitez faire apparaître le chat et ajustez ses dimensions grâce au conteneur parent. Consultez Chat intégré pour plus de détails.

WordPress

Sur WordPress, utilisez l'extension officielle WebChatAgent WordPress Plugin plutôt que de coller le script manuellement. Elle gère l'intégration et les mises à jour pour vous. Consultez WordPress Plugin.

Applications monopages (SPA)

Le widget fonctionne directement avec React, Vue, Angular et d'autres SPA. Ajoutez la balise de script à index.html et placez l'élément <web-chat-agent> dans la structure de base de votre application (par exemple le layout racine). Le widget persiste lors des changements de route côté client, vous n'avez pas besoin de le réinstancier lors des navigations.