Documentation — Telltab

⚡ Installation rapide

Ajoutez une seule ligne avant </body> sur votre site :

<script
  src="https://telltab.com/api/widget.js"
  data-site="mon-site.com"></script>

C'est tout. Le bouton de feedback apparaît en bas à droite. Aucune dépendance, aucun cookie, zéro configuration requise.

🎯 Premier feedback

Une fois le widget intégré :

Ouvrez votre site dans un navigateur
Cliquez sur le bouton violet en bas à droite
Sélectionnez une catégorie, saisissez un message, envoyez
Le feedback apparaît immédiatement dans le dashboard admin

⚙️ Options du widget

Toutes les options se configurent via des attributs data-* sur la balise <script> :

Attribut	Valeur par défaut	Description
data-site	hostname de la page	Identifiant du site (permet de filtrer les feedbacks par projet)
data-lang	`fr`	Langue du widget : `fr` ou `en`
data-color	`#4F46E5`	Couleur principale du bouton et des accents (hex)
data-position	`bottom-right`	Position : `bottom-right`, `bottom-left`, `top-right`, `top-left`
data-user	vide	Identifiant de l'utilisateur connecté (ex : ID ou email) — permet de retrouver qui a soumis le feedback
data-site-token	vide	Token d'authentification du site (optionnel, pour les configurations sécurisées)
data-offset-x	`20`	Décalage horizontal en px par rapport au bord (gauche ou droit selon `data-position`)
data-offset-y	`20`	Décalage vertical en px par rapport au bord (haut ou bas selon `data-position`)

🏷️ Catégories

Le widget propose 5 catégories standard pour classifier les feedbacks :

Bug — dysfonctionnement, erreur, crash. Active automatiquement la capture de métadonnées techniques (user-agent, viewport, erreurs JS).
Idée — suggestion de nouvelle fonctionnalité
Amélioration — suggestion sur l'existant
Feedback — retour général
Fonctionnalité — demande de feature précise

🌍 Langues

<!-- Widget en français (défaut) -->
<script src="https://telltab.com/api/widget.js"
  data-site="mon-site.com"
  data-lang="fr"></script>

<!-- Widget en anglais -->
<script src="https://telltab.com/api/widget.js"
  data-site="my-site.com"
  data-lang="en"></script>

La langue affecte tous les textes de l'interface ainsi que la reconnaissance vocale (fr-FR ou en-US).

🎨 Apparence

<script
  src="https://telltab.com/api/widget.js"
  data-site="mon-site.com"
  data-color="#E11D48"        <!-- rouge -->
  data-position="bottom-left"  <!-- coin inférieur gauche -->
></script>

📄 Intégration HTML

<!DOCTYPE html>
<html>
  <body>
    <!-- Votre contenu -->

    <!-- Telltab widget — juste avant </body> -->
    <script
      src="https://telltab.com/api/widget.js"
      data-site="mon-site.com"
      data-lang="fr"
      data-color="#4F46E5"
      data-position="bottom-right"></script>
  </body>
</html>

⚛️ React / Next.js

// components/TelltabWidget.tsx
import Script from 'next/script'

export default function TelltabWidget() {
  return (
    <Script
      src="https://telltab.com/api/widget.js"
      data-site={process.env.NEXT_PUBLIC_SITE_ID}
      data-lang="fr"
      data-color="#4F46E5"
      data-user={session?.user?.email ?? ''}
      strategy="lazyOnload"
    />
  )
}

Montez le composant dans votre layout racine (app/layout.tsx ou _app.tsx). L'attribut data-user associe chaque feedback à l'utilisateur connecté.

💚 Vue.js

// main.js ou App.vue (mounted hook)
mounted() {
  const script = document.createElement('script')
  script.src = 'https://telltab.com/api/widget.js'
  script.setAttribute('data-site', 'mon-site.com')
  script.setAttribute('data-lang', 'fr')
  script.setAttribute('data-color', '#4F46E5')
  document.body.appendChild(script)
}

🖥️ Dashboard admin

Le dashboard est accessible à l'adresse :

https://telltab.com/admin

Connectez-vous avec votre token d'accès. Le token est disponible auprès de l'administrateur Telltab.

Pour obtenir votre token (depuis le serveur) :

curl http://172.20.0.107:3000/api/admin/token   # VPN requis uniquement pour cette opération

Fonctionnalités disponibles :

Filtrer par site, catégorie, statut, période (date from/to), texte libre
Changer le statut d'un feedback : Nouveau → En cours → Terminé → Rejeté
Définir la priorité : Faible / Moyen / Élevé / Critique
Ajouter des notes dans le champ réponse admin
Supprimer individuellement ou en lot
Exporter en CSV avec les filtres actifs

Le dashboard détecte automatiquement la langue de votre navigateur (FR ou EN).

🔔 Notifications email

Telltab envoie automatiquement un email pour chaque feedback de priorité Élevé ou Critique. Configuration dans .env :

NOTIFY_EMAIL=votre@email.com
SMTP_HOST=votre-serveur-smtp
SMTP_PORT=587
SMTP_USER=noreply@votre-domaine.com
SMTP_PASSWORD=mot-de-passe
SMTP_TLS=true   # false pour relay interne sans STARTTLS

🔗 Webhooks

Recevez chaque nouveau feedback dans Slack, n8n, ou tout service compatible webhook :

SITE_WEBHOOKS={"mon-site.com":"https://hooks.slack.com/services/xxx","autre-site":"https://n8n.xxx/webhook/yyy"}

Le payload envoyé :

{
  "id": 42,
  "site": "mon-site.com",
  "category": "bug",
  "priority": "critical",
  "message": "Crash au démarrage sur Safari",
  "created_at": 1744143600,
  "dashboard_url": "https://telltab.com"
}

📥 Export CSV

Exportez tous vos feedbacks (avec filtres optionnels) via l'API :

curl -H "Authorization: Bearer VOTRE_TOKEN" \
  "https://telltab.com/api/feedback/export?site=mon-site.com" \
  -o feedbacks.csv

Paramètres supportés : site, category, status, date_from (YYYY-MM-DD), date_to, search.

🔌 API REST

Tous les endpoints admin nécessitent le header Authorization: Bearer TOKEN.

Méthode	Endpoint	Description
GET	/api/feedback	Lister les feedbacks (filtres : site, category, status, search, date_from, date_to, limit, offset)
GET	/api/feedback/stats	Statistiques globales
PATCH	/api/feedback/{id}	Modifier statut, priorité ou réponse
DELETE	/api/feedback/{id}	Supprimer un feedback
DELETE	/api/feedback/bulk	Suppression en lot (body: {"ids": [1,2,3]})
GET	/api/feedback/export	Export CSV (mêmes filtres que list)
GET	/api/feedback/stats	Stats par catégorie et par site
GET	/api/admin/weekly-summary	Résumé IA de la semaine (VPN uniquement)

🎙️ Feedback vocal

Le widget inclut un mode dictée avec transcription automatique. L'utilisateur clique sur "Dicter", parle, puis envoie. La transcription est effectuée côté serveur et stockée avec le feedback.

Compatibilité : Chrome, Edge, Safari 15+. Firefox partiellement supporté. La reconnaissance vocale en temps réel (SpeechRecognition) nécessite HTTPS.

🐛 Mode bug enrichi

En sélectionnant la catégorie Bug, le widget capture automatiquement :

User-agent complet du navigateur
Dimensions de la fenêtre (viewport) et pixel ratio
URL et referrer de la page
Les 5 dernières erreurs JavaScript capturées sur la page

Un bouton 📷 permet également de capturer un screenshot de la page au moment du bug (technologie html2canvas, chargé à la demande).

🤖 Résumé IA hebdomadaire

Obtenez un résumé intelligent de vos feedbacks de la semaine :

curl -H "X-Forwarded-For: 100.x.x.x" \  # depuis Tailscale VPN
  "http://172.20.0.107:3000/api/admin/weekly-summary"

Le résumé identifie les thèmes récurrents, les bugs critiques et propose une recommandation d'action prioritaire. Nécessite la variable LITELLM_URL configurée.