01
Installation
Le SDK est disponible sous deux formes : un bundle ES Module pour les projets avec bundler (Vite, Webpack…) et un bundle IIFE pour un chargement direct via <script>.
Via npm
npm install @aichat/web-sdk
Via CDN / balise script (IIFE global)
<script src="dist/index.global.js"></script>
// La variable globale AiChatWeb est alors disponible
Import ES Module
import { AiChatWebClient, AiChatChatbot } from '@aichat/web-sdk';
02
Démarrage rapide
En moins de 10 lignes, un widget de chat complet est monté dans votre page, Shadow DOM isolé, bouton flottant inclus.
// 1. Créer le client HTTP
const client = new AiChatWeb.AiChatWebClient({
baseUrl: "https://www.aichat.olasoft.net",
apiKey: "sk_live_...",
});
// 2. Monter le widget
new AiChatWeb.AiChatChatbot({
client,
agentId: "votre-agent-uuid",
mount: "#chatbot",
title: "Assistant IA",
position: "bottom-right",
});
Le widget utilise le Shadow DOM : aucun conflit CSS possible avec votre application existante.
03
AiChatWebClient
Le client HTTP encapsule la communication avec l'API REST. Il gère l'authentification Bearer et peut être utilisé indépendamment du widget visuel.
Constructeur
new AiChatWebClient(options: RequestOptions)
| Option | Type | Description |
|---|---|---|
| baseUrl | string | URL de base de votre instance AiChat (ex: https://votre-domaine.com) |
| apiKey | string | Clé API Bearer générée dans le tableau de bord |
| timeout | number? | Délai d'expiration en ms (optionnel) |
Méthode sendMessage
const response = await client.sendMessage({
agent_id: "votre-agent-uuid",
message: "Bonjour, j'ai besoin d'aide",
conversation_id: "uuid-optionnel", // omettre pour démarrer
});
// response : { conversationId, message, role, metadata }
04
AiChatChatbot
Le widget visuel complet. Il compose automatiquement un header, une liste de messages, une zone de saisie et un bouton launcher flottant — le tout dans un Shadow DOM isolé.
Fonctionnalités intégrées
- ▸ Shadow DOM — isolation CSS totale, pas de conflits avec votre application
- ▸ Rendu Markdown — gras, italique, code inline, blocs de code, listes, blockquotes, liens
- ▸ Launcher flottant — bouton circulaire avec badge de messages non lus, positions bottom-right / bottom-left
- ▸ Indicateur de frappe — trois points animés pendant la génération de la réponse
- ▸ Textarea auto-redimensionnable — s'agrandit jusqu'à 120px, Enter pour envoyer, Shift+Enter pour un saut de ligne
- ▸ Human-in-the-loop — carte d'approbation intégrée pour les outils IA nécessitant validation
- ▸ Horodatages optionnels — affichés sur chaque bulle de message
Positions disponibles
position: "inline" // Widget intégré dans le flux de la page
position: "bottom-right" // Bouton flottant en bas à droite (défaut)
position: "bottom-left" // Bouton flottant en bas à gauche
05
Options complètes
Référence complète de toutes les options acceptées par AiChatChatbot.
| Option | Type | Description |
|---|---|---|
| client | AiChatWebClient | Instance du client HTTP (requis) |
| agentId | string | UUID de l'agent à utiliser (requis) |
| mount | string | Element | Sélecteur CSS ou élément DOM cible (requis) |
| title | string? | Titre affiché dans le header |
| subtitle | string? | Sous-titre affiché sous le titre |
| welcomeMessage | string? | Message initial de l'assistant (Markdown supporté) |
| position | string? | inline | bottom-right | bottom-left |
| showTimestamps | boolean? | Afficher l'heure sur chaque message |
| theme | ChatbotTheme? | Overrides des design tokens CSS (voir section Thèmes) |
| onApprove | function? | Callback HITL — appelé quand l'utilisateur approuve un outil |
| onReject | function? | Callback HITL — appelé quand l'utilisateur rejette un outil |
Exemple complet
new AiChatChatbot({
client,
agentId: "b9586f4a-2b31-4fe9-b892-aa4407be6948",
mount: "#chatbot",
title: "Assistant IA",
subtitle: "Propulsé par AiChat",
welcomeMessage: "Bonjour ! Comment puis-je vous aider ?",
position: "bottom-right",
showTimestamps: true,
theme: { primaryColor: "#4f46e5", borderRadius: "20px" },
onApprove: (toolId, toolName, args) => console.log('Approuvé:', toolName, args),
onReject: (toolId, toolName) => console.log('Rejeté:', toolName),
});
06
Thèmes
Le widget est entièrement personnalisable via l'objet theme. Chaque propriété correspond à un token CSS --ac-* injecté dans le Shadow DOM.
Thèmes prédéfinis
Midnight
primaryColor: #1a1a2e
accentColor: #c9a84c
accentColor: #c9a84c
Indigo
primaryColor: #4f46e5
accentColor: #a5b4fc
accentColor: #a5b4fc
Forest
primaryColor: #14532d
accentColor: #86efac
accentColor: #86efac
Rose
primaryColor: #881337
accentColor: #fda4af
accentColor: #fda4af
Propriétés du thème (ChatbotTheme)
| Propriété | Type | Description |
|---|---|---|
| primaryColor | string? | Couleur principale (header, bulles utilisateur, launcher) |
| accentColor | string? | Couleur d'accentuation (boutons, focus) |
| headerBackground | string? | Fond du header |
| headerTextColor | string? | Texte du header |
| userBubbleBackground | string? | Fond des bulles utilisateur |
| userBubbleTextColor | string? | Texte des bulles utilisateur |
| assistantBubbleBackground | string? | Fond des bulles assistant |
| assistantBubbleTextColor | string? | Texte des bulles assistant |
| widgetBackground | string? | Fond général du widget |
| widgetBorderColor | string? | Couleur de bordure du widget |
| borderRadius | string? | Rayon des coins (ex: 16px, 20px) |
| shadowIntensity | string? | none | low | medium | high |
Exemple — thème Indigo
theme: {
primaryColor: "#4f46e5",
accentColor: "#a5b4fc",
headerBackground: "#4f46e5",
headerTextColor: "#ffffff",
userBubbleBackground: "#4f46e5",
userBubbleTextColor: "#ffffff",
assistantBubbleBackground: "#eef2ff",
assistantBubbleTextColor: "#312e81",
borderRadius: "20px",
shadowIntensity: "medium",
}
07
Human-in-the-loop (HITL)
Lorsque l'agent IA souhaite exécuter un outil nécessitant une validation humaine, le SDK affiche automatiquement une carte d'approbation dans le chat. L'utilisateur peut approuver ou rejeter l'action sans quitter l'interface.
Le flux HITL est déclenché automatiquement quand la réponse API contient
metadata.approval_required: true.
Callbacks
new AiChatChatbot({
// ... autres options ...
// Appelé quand l'utilisateur clique "Approuver"
onApprove: (toolId: string, toolName: string, args: object) => {
console.log('Outil approuvé:', toolName, args);
},
// Appelé quand l'utilisateur clique "Rejeter"
onReject: (toolId: string, toolName: string) => {
console.log('Outil rejeté:', toolName);
},
});
Structure de la réponse HITL
{
"conversation_id": "conv-uuid",
"message": "Je souhaite exécuter l'outil suivant...",
"role": "assistant",
"metadata": {
"approval_required": true,
"tool_id": "tool-uuid",
"tool_name": "envoyer_email",
"tool_args": { "to": "...", "subject": "..." }
}
}
08
Événements & méthodes
L'instance AiChatChatbot expose des méthodes publiques et un système d'événements pour interagir programmatiquement avec le widget.
Méthodes
| Méthode | Type | Description |
|---|---|---|
| toggle(force?) | void | Ouvre ou ferme le widget. force=true pour forcer l'ouverture, false pour fermer. |
| destroy() | void | Démonte le widget et libère toutes les ressources DOM. |
| on(event, cb) | void | Abonne un callback à un événement. |
| off(event, cb) | void | Désabonne un callback d'un événement. |
Événements disponibles
| Événement | Payload | Description |
|---|---|---|
| ready | — | Widget monté et prêt à l'emploi |
| toggle | boolean | Widget ouvert (true) ou fermé (false) |
| message | ChatMessage | Nouveau message reçu de l'assistant |
| error | Error | Erreur lors de l'envoi ou de la réception |
Exemple
const bot = new AiChatChatbot({ /* options */ });
// Écouter les erreurs
bot.on('error', (err) => console.error('[AiChat]', err));
// Écouter chaque réponse de l'assistant
bot.on('message', (msg) => console.log(msg.content));
// Ouvrir/fermer programmatiquement
bot.toggle(true); // ouvrir
bot.toggle(false); // fermer
// Nettoyer
bot.destroy();
09
API REST
Le SDK consomme l'API REST AiChat. Voici l'endpoint principal utilisé par AiChatWebClient.sendMessage().
POST
/api/conversations/send
— Envoyer un message à un agent
En-têtes requis
Authorization: Bearer votre_clé_api
Content-Type: application/json
Corps de la requête
{
"agent_id": "uuid-de-votre-agent",
"message": "Bonjour, j'ai besoin d'aide",
"conversation_id": "uuid-optionnel" // omettre pour démarrer une nouvelle conversation
}
200
Réponse standard
{
"conversation_id": "conv-uuid-123",
"message": "Bien sûr ! Quel est votre problème ?",
"role": "assistant",
"metadata": null // ou objet HITL si approbation requise
}
Besoin d'aide ?
Créez votre agent depuis le tableau de bord, récupérez votre clé API, et intégrez le SDK en 2 minutes.
Démarrer gratuitement →