Démarrage Rapide

Embarquez le widget et obtenez un jeton de widget depuis le serveur.

L'application widget est hébergée sur widget.companin.tech et offre un moyen simple d'intégrer un assistant IA dans votre site web. Pour commencer, vous devez créer un assistant et une application OAuth.

Le widget est une application légère et autonome qui s'exécute dans une iframe isolée sur votre site Web. Cette architecture garantit que le widget n'entrera pas en conflit avec votre CSS ou JavaScript existant, tout en conservant d'excellentes performances et sécurité.

⚡ Déploiement rapide

La plupart des développeurs exécutent le widget sur leur site dans un délai de 10 minutes. Le processus de configuration ne comporte que trois étapes : création d'informations d'identification, configuration de l'apparence et ajout d'une seule balise de script à votre code HTML.

1. Créer un Assistant

Tout d'abord, créez un assistant IA dans votre tableau de bord :

Votre assistant est le cerveau de l'IA derrière le widget. Il traite les messages des utilisateurs, maintient le contexte de la conversation et génère des réponses intelligentes. Chaque assistant peut être personnalisé avec des instructions spécifiques, des traits de personnalité et des bases de connaissances pour correspondre à votre cas d'utilisation.

Allez dans votre tableau de bord et naviguez vers la page "Data Sources"
Cliquez le bouton "Add" dans la section Assistants
Remplissez les détails de l'assistant (nom, description, ton, etc.)
Enregistrez l'assistant et notez son ID

Conseil: Donnez à votre assistant des instructions claires et précises sur son rôle et ses limites. Par exemple : "Vous êtes un assistant de support client utile pour un produit SaaS. Vous pouvez répondre aux questions sur les fonctionnalités, les prix et la gestion des comptes. En cas de problèmes techniques, demandez aux utilisateurs de créer un ticket d'assistance."

2. Créer une Application OAuth

Créez une application OAuth pour authentifier votre widget :

Allez à la page "OAuth" dans votre tableau de bord
Cliquez "Create Application"
Remplissez le nom et la description de l'application
Copiez le client_id de l'application créée

3. Intégrer le Widget via Iframe

La manière la plus simple d’intégrer le widget est de l’intégrer directement via un iframe. Cette méthode ne nécessite aucune initialisation JavaScript et fonctionne immédiatement. Si vous utilisez plusieurs iframes sur une page, gardez chaque intégration isolée avec son propre conteneur et ses propres paramètres.

<iframe src="https://widget.companin.tech/embed/session?clientId=YOUR_CLIENT_ID&assistantId=YOUR_ASSISTANT_ID&configId=YOUR_CONFIG_ID&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Assistant Widget"></iframe>

Remplacez YOUR_CLIENT_ID et YOUR_ASSISTANT_ID par vos valeurs réelles. Le paramètre locale peut être défini pour correspondre à la langue de votre site.

Avancé : Initialisation JavaScript

La méthode d'intégration recommandée utilise notre chargeur de widget JavaScript, qui fournit un dimensionnement automatique, une gestion de la configuration et un comportement réactif.

Intégration de scripts

Ajoutez la balise de script suivante à votre page HTML :

<script  src="https://widget.companin.tech/widget.js"  data-client-id="YOUR_CLIENT_ID"  data-assistant-id="YOUR_ASSISTANT_ID"  data-config-id="YOUR_CONFIG_ID"  data-instance-id="support-widget"  data-locale="en"  data-dev="false"></script>

Attributs du script

Chaque attribut sert un objectif spécifique dans la configuration de votre widget :

data-client-id : votre identifiant client OAuth - Cela authentifie votre application avec notre API. Considérez-le comme le mot de passe de votre application.
data-assistant-id : l'UUID de votre assistant – ceci identifie quel assistant IA du support client gère les conversations.
data-config-id : L'UUID de la configuration de votre widget - Ceci détermine l'apparence et le comportement de votre widget (couleurs, taille, position, etc.).
data-instance-id : ID d'instance unique par widget - Requis lors de l'intégration de plusieurs widgets sur la même page pour éviter les collisions et activer le ciblage d'API par instance.
data-custom-css : (facultatif) règles CSS en ligne qui seront injectées dans le <head> de l'iframe avant le rendu de l'application. Utilisez-le pour remplacer les styles sans modifier votre configuration. L'encodage des URL est géré automatiquement.
data-locale : Code de langue (par exemple, "en", "es", "fr") - Définit la langue d'affichage du widget. L'assistant répondra toujours dans la langue dans laquelle les utilisateurs écrivent.
data-dev : défini sur "true" pour le mode développement (localhost) - Utilisez-le lors des tests locaux. Supprimer ou définir sur "false" pour la production.

Le widget va automatiquement :

Récupérer la configuration à partir de l'ID de configuration
Se dimensionner en fonction des dimensions du widget dans la configuration
Positionnez le bouton réduit en fonction des paramètres de configuration
Démarrer ouvert ou fermé en fonction du paramètre start_open de la configuration

Remarques

Le widget gère automatiquement son propre dimensionnement en fonction de vos paramètres de configuration
La position du bouton réduit peut être personnalisée via la configuration du widget
Le widget respecte le paramètre start_open de votre configuration
Tous les styles (couleurs, polices, dimensions) sont contrôlés via la configuration du widget
Le widget utilise la communication postMessage pour un comportement réactif
Le mode développement peut être activé avec data-dev="true" pour les tests localhost
Pour l'échange de jetons côté serveur, utilisez /api/v1/auth/widget-token et conservez le secret client sur votre serveur uniquement.
Assurez-vous que l'origine de votre hôte (par exemple http://localhost:3000) est incluse dans OAuth Allowed_origins lors de l'intégration du widget dans une iframe.

← Retour Suivant : Référence API →