Documentation
Design de la Chatbox TALKR.ai
Guide complet : structure, tokens CSS, composants et personnalisation du widget de chat
Aperçu
La chatbox TALKR.ai est un widget de conversation autonome, léger (un seul fichier HTML) et entièrement personnalisable. Elle se connecte à l'API TALKR pour offrir une expérience conversationnelle fluide.
Messages animés
Bulles bot/utilisateur avec animation fade-in et indicateur de frappe (3 points rebondissants).
Refresh conversation
Bouton de réinitialisation : vide les messages, reset la session et relance l'accueil du bot.
Popover TALKR
Bouton éclair affichant le logo TALKR.ai avec un lien vers le site. Se ferme au clic extérieur.
Responsive
Adapté mobile : max-width 95vw, max-height 90vh. Fonctionne sur tous les écrans.
Structure HTML
Le widget suit une architecture BEM simple avec 4 zones principales :
<div .chat>
<div .chat__header>
├─ .chat__avatar - Icône / emoji du bot
├─ .chat__title + .chat__subtitle
└─ .chat__header-actions
├─ #refreshBtn - Nouvelle conversation
└─ #boltBtn + .popover
<div .chat__messages>
├─ .msg--bot - Bulle du bot
├─ .msg--user - Bulle utilisateur
├─ .msg--error - Message d'erreur
└─ .msg--typing - Indicateur de frappe
<div .chat__input>
├─ <input> - Champ texte
└─ <button #sendBtn> - Envoi
Design Tokens CSS
Les variables CSS personnalisables sont définies dans :root :
Couleurs
--purple
#7B2FBE - Accent principal, boutons, bulles user
--cyan
#2CC4D1 - Avatar du bot
--navy
#001B39 - Texte foncé, header gradient
--bg
#f4f5f7 - Fond de page
--gray-100
#f0f1f3 - Bulles bot, champ désactivé
--gray-300
#d1d5db - Bordures, scrollbar
--gray-500
#6b7280 - Texte secondaire, dots typing
--white
#ffffff - Fond chatbox, texte sur fond sombre
Dimensions
| Token | Valeur | Usage |
|---|---|---|
--radius |
1rem |
Border-radius global (container, bulles) |
width |
420px |
Largeur fixe du widget |
max-width |
95vw |
Limite mobile |
height |
680px |
Hauteur fixe du widget |
max-height |
90vh |
Limite viewport |
Typographie
| Élément | Font | Taille |
|---|---|---|
| Corps / messages | Inter 400 | .9rem |
| Titre header | Poppins 700 | 1rem |
| Sous-titre | Inter 400 | .75rem |
| Popover texte | Inter 400 | .8rem |
| Popover lien | Poppins 600 | .85rem |
Composants
Header
Barre supérieure avec dégradé
purple → navy. Contient l'avatar, le titre, le statut en ligne (pastille verte) et les boutons d'action.
.chat__header
.chat__avatar
.chat__title
.chat__subtitle
.chat__status
.chat__header-actions
Bulles de message
Trois variantes : bot (gris, aligné à gauche), user (violet, aligné à droite), error (rouge pâle, centré). Max-width 82%. Animation
fadeIn au rendu.
.msg
.msg--bot
.msg--user
.msg--error
Indicateur de frappe
Trois points animés (bounce décalé de 0.15s chacun) affichés pendant l'appel API. Automatiquement supprimé à la réception de la réponse.
.msg--typing
Zone de saisie
Input arrondi (
border-radius: 2rem) + bouton d'envoi circulaire violet avec icône flèche SVG. Focus = bordure violette. Désactivé pendant l'envoi.
.chat__input
#userInput
#sendBtn
Boutons d'action (header)
Cercles semi-transparents (
rgba(255,255,255,.15)) avec icônes SVG blanches. Hover = plus opaque.
Refresh : réinitialise session + messages.
Éclair : toggle un popover avec logo TALKR et lien vers le site.
.chat__header-btn
#refreshBtn
#boltBtn
.popover
Animations
| Animation | Durée | Cible | Effet |
|---|---|---|---|
fadeIn |
0.25s ease | Toutes les bulles .msg |
Slide-up 6px + fade opacity 0→1 |
bounce |
0.6s infinite alternate | Dots du typing indicator | Translation Y -6px + opacity →0.4 |
| Transitions | 0.2s | Boutons, input focus, popover link | Background-color, border-color, transform |
Personnalisation
Changer les couleurs
Modifiez les variables CSS dans :root pour adapter le widget à votre charte graphique :
CSS
:root {
--purple: #E63946; /* Accent → rouge */
--cyan: #457B9D; /* Avatar → bleu */
--navy: #1D3557; /* Header → bleu foncé */
--radius: 0.5rem; /* Coins moins arrondis */
}
Changer l'avatar
Remplacez l'emoji dans .chat__avatar par une image :
HTML
<div class="chat__avatar">
<img src="logo.png" alt="Bot"
style="width:100%;height:100%;border-radius:50%;object-fit:cover">
</div>
Changer l'endpoint API
Modifiez la constante API_URL dans le <script> :
JavaScript
const API_URL = 'https://api-production.talkr.ai/{workspace}/bots/{id}/api/web';
Dimensions du widget
Ajustez width et height dans la classe .chat :
CSS
.chat {
width: 360px; /* Plus étroit */
height: 600px; /* Plus court */
}
Logique JavaScript
Flux de conversation
Le widget gère automatiquement la session avec l'API TALKR :
- Initialisation - Appel POST sans session → le bot retourne son message d'accueil + un ID de session
- Messages suivants - Chaque appel envoie
session,trackinget le message utilisateur - Réponse - Extraction des messages intermédiaires (
data.messages) et de la réponse finale (variables.bot_answer) - Refresh - Reset de
sessionettrackingànull, vidage des messages, re-init
Fonctions principales
| Fonction | Rôle |
|---|---|
init() |
Charge le message d'accueil du bot au démarrage |
callAPI(msg) |
Envoie une requête POST à l'API TALKR |
extractBotResponse(data) |
Parse la réponse API et retourne un tableau de textes |
sendMessage() |
Gère l'envoi d'un message utilisateur (UI + API) |
addMessage(text, type) |
Ajoute une bulle dans le DOM |
showTyping() / hideTyping() |
Affiche/masque l'indicateur de frappe |
setEnabled(bool) |
Active/désactive l'input pendant un envoi |
Exemple complet
Le widget est un fichier HTML autonome. Voici la structure minimale pour l'intégrer :
HTML
<!-- 1. Inclure Google Fonts -->
<!-- 2. Copier le CSS (variables + composants) dans un <style> -->
<!-- 3. Structure HTML -->
<div class="chat">
<div class="chat__header">...</div>
<div class="chat__messages" id="messages"></div>
<div class="chat__input">
<input type="text" id="userInput">
<button id="sendBtn">...</button>
</div>
</div>
<!-- 4. Configurer l'API URL dans le <script> -->
<script>
const API_URL = 'https://api-production.talkr.ai/{workspace}/bots/{id}/api/web';
// ... logique complète
</script>
Le fichier complet est disponible dans le dossier chatbox/ du projet.
Prêt à intégrer votre chatbox ?
Consultez la documentation API pour configurer votre bot et le connecter au widget.
Documentation API Guide de démarrage