Design Chatbox — Documentation

🖥️ 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 :

├─ .chat__avatar — Icône / emoji du bot

├─ .chat__title + .chat__subtitle

└─ .chat__header-actions

├─ #refreshBtn — Nouvelle conversation

└─ #boltBtn + .popover

├─ .msg--bot — Bulle du bot

├─ .msg--user — Bulle utilisateur

├─ .msg--error — Message d'erreur

└─ .msg--typing — Indicateur de frappe

├─ <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, tracking et le message utilisateur
Réponse — Extraction des messages intermédiaires (data.messages) et de la réponse finale (variables.bot_answer)
Refresh — Reset de session et tracking à 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

Design de la Chatbox TALKR.ai