Agent IA Service Client — Documentation complète

Guide complet d’installation, de configuration et d’utilisation du plugin DataFirefly AI Customer Service Agent — un agent IA de support client pour WooCommerce qui comprend le contexte, appelle des outils en lecture seule sur votre boutique, et escalade intelligemment les cas complexes vers Slack et email.

1. Prérequis

• WordPress 6.4 ou supérieur
• WooCommerce 8.0 ou supérieur
• PHP 8.1, 8.2 ou 8.3
• Une clé API Anthropic (Claude) ou OpenAI (recommandé : Claude Sonnet 4.5)
• Optionnel : un webhook Slack pour l’escalade en temps réel
• Optionnel : Polylang Pro ou WPML si votre boutique est multilingue

2. Installation

Installation du ZIP

1. Depuis votre compte DataFirefly, téléchargez le fichier df-ai-customer-service.zip
2. Dans WordPress, allez dans Extensions → Ajouter une extension → Téléverser une extension
3. Sélectionnez le ZIP puis cliquez sur Installer
4. Cliquez sur Activer une fois l’installation terminée

Que se passe-t-il à l’activation ?

Le plugin crée automatiquement 5 tables dans la base de données préfixées wp_dfaics_ : conversations, messages, escalations, faq, analytics. Il déclare également la compatibilité HPOS et les blocs Gutenberg cart/checkout, puis planifie une tâche cron quotidienne pour nettoyer les conversations expirées.

3. Configuration du provider IA

Le plugin supporte deux providers IA. Vous choisissez celui que vous préférez dans AI Support → Réglages → IA. Vous fournissez votre propre clé API — DataFirefly n’intercepte rien et ne prélève aucune commission sur votre consommation.

Option A : Claude (recommandé)

1. Créez un compte sur console.anthropic.com
2. Générez une clé API dans Settings → API Keys
3. Copiez la clé (commence par sk-ant-...)
4. Dans WordPress, allez dans AI Support → Réglages → IA
5. Sélectionnez le provider Anthropic (Claude)
6. Collez votre clé dans le champ Clé API Anthropic
7. Modèle par défaut : claude-sonnet-4-5 (excellent rapport qualité / coût)
8. Cliquez sur Tester la clé pour valider
9. Enregistrez

Option B : OpenAI

1. Créez un compte sur platform.openai.com
2. Générez une clé API dans API Keys
3. Copiez la clé (commence par sk-...)
4. Dans WordPress, sélectionnez le provider OpenAI
5. Modèle par défaut : gpt-4o-mini (le plus économique avec tool calling fiable)

Coût indicatif

Une conversation typique de 5 à 10 échanges avec tool calling coûte :

• Environ 0,01 à 0,05 USD avec Claude Sonnet 4.5
• Environ 0,005 à 0,02 USD avec GPT-4o mini

Le dashboard affiche le total des tokens input/output consommés sur la période.

4. Configuration du widget

Le widget de chat s’affiche par défaut en bas à droite sur toutes les pages du site frontend. Personnalisez-le dans AI Support → Réglages → Widget.

Options d’apparence

• Couleur principale — Couleur du bouton flottant et du header (par défaut #0073aa)
• Couleur du texte — Couleur du texte dans le header (par défaut blanc)
• Position — Bas à droite ou bas à gauche
• Titre du widget — Ex. « Besoin d’aide ? »
• Message de bienvenue — Premier message affiché à l’ouverture
• Placeholder — Texte du champ de saisie
• Afficher le badge DataFirefly — Petite mention en bas du widget

Affichage conditionnel

Dans l’onglet Widget, vous pouvez limiter l’affichage :

• Toutes les pages — Comportement par défaut
• Pages produit uniquement — Pour un support ciblé sur les fiches
• Sauf panier et checkout — Éviter la distraction pendant l’achat
• Masquer sur ces IDs de contenu — Liste d’IDs à exclure

Shortcode

Vous pouvez également intégrer le chat dans une page ou un article avec le shortcode :

[dfaics_chat]

Cela affiche le widget en mode intégré (non flottant), pratique pour une page « Nous contacter » dédiée.

5. Les 6 outils de l’agent

L’agent dispose de 6 outils qu’il choisit d’appeler ou non en fonction de la question. Tous sont strictement en lecture seule. Vous les activez ou désactivez individuellement dans Réglages → Comportement.

lookup_order

Récupère le statut d’une commande WooCommerce. Nécessite une vérification email obligatoire avant divulgation : l’agent demande l’email au client et le confronte à celui de la commande. Retourne le numéro, statut, montant, date, méthode de livraison, numéro de suivi si disponible.

search_products

Recherche dans le catalogue par nom, catégorie, tag, disponibilité, gamme de prix. Retourne jusqu’à 5 résultats par défaut avec titre, SKU, prix, URL, stock. Utile pour répondre à « avez-vous ceci en bleu ? » ou « quel est le prix de X ? ».

get_shipping_info

Retourne les zones et méthodes de livraison configurées dans WooCommerce, avec les frais et délais. L’agent peut ainsi répondre précisément à « livrez-vous en Belgique ? » ou « combien coûte l’express ? ».

get_returns_policy

Retourne le contenu de votre politique de retour (que vous configurez dans les réglages). L’agent peut expliquer le délai, la procédure et les conditions.

search_faq

Cherche dans vos FAQ personnalisées (gérées dans AI Support → FAQ). Résultats scopés par langue de la conversation. Chaque entrée trouvée incrémente un compteur d’usage pour vous aider à identifier les questions les plus fréquentes.

escalate_to_human

L’agent appelle cet outil quand il détermine qu’un cas nécessite un humain (frustration client, cas complexe, plusieurs échecs d’outils). Déclenche les notifications Slack et / ou email configurées. Voir la section Escalade plus bas.

6. Gestion de la FAQ

Créez des entrées de FAQ personnalisées que l’agent pourra rechercher pendant une conversation. Chaque entrée est scopée par langue.

Créer une entrée

1. Allez dans AI Support → FAQ
2. Cliquez sur Ajouter une entrée
3. Choisissez la langue
4. Rédigez la question et la réponse en langage naturel
5. Ajoutez des mots-clés séparés par des virgules (facultatif, améliore la recherche)
6. Choisissez une catégorie (ex. livraison, tailles, garantie)
7. Enregistrez

Bonnes pratiques FAQ

• Formulez les questions comme un client les poserait, pas comme un rédacteur SEO
• Réponses courtes et actionnables (2 à 4 phrases suffisent, l’agent reformule)
• Créez une entrée par langue majeure de votre clientèle
• Consultez régulièrement le compteur d’usage pour identifier les questions à enrichir

7. Escalade vers un humain

L’escalade se configure dans Réglages → Escalade. Deux canaux sont supportés en parallèle : Slack et email.

Configuration Slack

1. Dans Slack, créez une nouvelle app sur api.slack.com/apps
2. Activez Incoming Webhooks
3. Créez un webhook vers le canal souhaité (ex. #support-escalations)
4. Copiez l’URL du webhook
5. Dans WordPress, collez-la dans Webhook Slack
6. Cliquez sur Tester le webhook pour envoyer un message de test

Chaque escalade envoie à Slack un message en blocs riches contenant : l’extrait des 3 derniers messages, le motif d’escalade, les métadonnées client (email vérifié, langue, page d’origine), et un bouton Ouvrir dans l’admin qui pointe directement vers le détail de la conversation.

Configuration email

Dans Email d’escalade, indiquez une ou plusieurs adresses séparées par des virgules. Chaque escalade envoie un email HTML contenant la transcription complète, les données client et un lien vers l’admin.

Déclencheurs d’escalade

L’agent escalade dans 3 situations :

1. Mots-clés sensibles — Liste configurable (par défaut : remboursement, avocat, cassé, réclamation, complaint, refund, lawyer, broken)
2. Seuil de sentiment — Détection de frustration ou de mécontentement (paramétrable de -1 à 0)
3. Échec répété d’outils — Après 6 tours sans résolution, escalade forcée

8. Dashboard et analytics

Le tableau de bord AI Support → Dashboard affiche 4 indicateurs clés :

• Volume — Nombre total de conversations sur les 7, 30 ou 90 derniers jours
• Taux d’auto-résolution — % de conversations qui se terminent sans escalade
• Satisfaction moyenne — Note en étoiles données par les clients après escalade
• Tokens consommés — Input + output cumulés pour l’estimation du coût IA

La page Conversations liste toutes les sessions avec filtres (langue, statut, escalade oui/non). Cliquez sur une ligne pour voir le transcript complet avec les tool calls détaillés en JSON.

9. Multilingue

Le plugin supporte nativement 5 langues : français, anglais, espagnol, allemand, italien. La langue de la conversation est résolue automatiquement dans cet ordre :

1. Langue Polylang de la page où le widget s’affiche (si Polylang installé)
2. Langue WPML de la page (si WPML installé)
3. Locale du navigateur du visiteur
4. Langue de repli configurée dans les réglages (par défaut : anglais)

Le system prompt de l’agent indique explicitement au modèle la langue de réponse attendue. Cela garantit qu’un visiteur français reçoit une réponse en français, même si votre boutique est majoritairement anglaise.

10. Sécurité et confidentialité

Chiffrement des clés API

Les clés Anthropic, OpenAI et le webhook Slack sont chiffrés en AES-256-CBC au moment de leur enregistrement, avec une clé dérivée de AUTH_KEY + AUTH_SALT. Le champ input ne réaffiche jamais la valeur : en laissant le champ vide et en enregistrant, l’ancienne valeur est préservée.

Vérification email pour les commandes

L’outil lookup_order exige obligatoirement une vérification : l’agent demande au client son email, et le confronte à celui associé à la commande. Sans correspondance, aucune donnée n’est divulguée. Ce comportement n’est pas désactivable — il protège contre le scraping de commandes via l’agent.

Rate limiting

Un rate limit anti-spam de 5 messages par minute par session est appliqué côté serveur. Le nombre maximum de messages par conversation est de 25 par défaut (configurable). Au-delà, l’agent propose une escalade humaine.

Rétention et RGPD

Les conversations sont conservées 30 jours par défaut, puis supprimées automatiquement par une tâche cron quotidienne. Vous pouvez réduire cette durée dans Réglages → Confidentialité. L’IP du visiteur et l’user agent peuvent être journalisés ou non selon votre politique.

Le plugin propose également une option Anonymiser les PII dans les logs qui masque emails et numéros de téléphone dans les journaux techniques (WooCommerce logger).

11. Compatibilité HPOS et blocs de checkout

Le plugin déclare officiellement la compatibilité avec :

• HPOS (High-Performance Order Storage) — Toutes les requêtes commandes passent par les CRUDs WooCommerce officiels (wc_get_order, wc_get_orders), donc fonctionnent aussi bien sur les tables anciennes que sur les tables HPOS
• Blocs Gutenberg cart et checkout — Aucune interférence avec les nouveaux blocs de paiement
• Multisite WordPress — Activation réseau supportée, options scopées par site

12. Hooks et filtres pour développeurs

Le plugin expose plusieurs hooks pour personnaliser son comportement sans modifier le code source.

Filtres disponibles

// Modifier le system prompt avant envoi au modèle
apply_filters('dfaics_system_prompt', $prompt, $context);

// Ajouter ou retirer des outils dynamiquement
apply_filters('dfaics_tools_available', $tools, $conversation);

// Modifier le seuil de messages max avant escalade forcée
apply_filters('dfaics_max_messages', 25, $conversation);

// Personnaliser le contenu de l'email d'escalade
apply_filters('dfaics_escalation_email_body', $html, $conversation);

// Enrichir les métadonnées Slack
apply_filters('dfaics_slack_metadata', $metadata, $conversation);

Actions disponibles

// Après création d'une conversation
do_action('dfaics_conversation_created', $conversation_id, $session);

// Après envoi d'un message par l'agent
do_action('dfaics_message_sent', $message_id, $conversation_id);

// Après une escalade
do_action('dfaics_escalated', $conversation_id, $reason, $channel);

// Après nettoyage cron des conversations expirées
do_action('dfaics_cleanup_done', $deleted_count);

Ajouter un outil personnalisé

Créez une classe qui étend ToolBase et enregistrez-la via le filtre dfaics_tools_available. Le namespace est DataFireflyAiCustomerServiceAgentTools. Chaque outil déclare son schéma JSON, sa description, et implémente une méthode execute() qui retourne un tableau associatif sérialisable.

13. Dépannage

Le widget ne s’affiche pas

• Vérifiez que le widget est activé dans Réglages → Widget → Activer le widget
• Vérifiez la règle d’affichage conditionnel (pages autorisées)
• Ouvrez la console navigateur (F12) et cherchez des erreurs JS
• Videz le cache si vous utilisez un plugin de cache (WP Rocket, W3 Total Cache…)

L’agent ne répond pas

• Vérifiez que la clé API est valide via le bouton Tester la clé
• Vérifiez votre crédit / quota sur le compte Anthropic ou OpenAI
• Consultez les logs WooCommerce dans WooCommerce → Statut → Logs, source df-ai-customer-service

L’escalade Slack n’arrive pas

• Vérifiez le webhook via le bouton Tester le webhook
• Regénérez le webhook côté Slack si nécessaire
• Vérifiez que le canal cible existe et que le bot y a accès

Réinitialiser complètement le plugin

Dans Réglages → Confidentialité, cochez Supprimer toutes les données à la désinstallation. Ensuite désactivez puis désinstallez le plugin : les 5 tables et les options sont supprimées.

14. FAQ technique

Puis-je changer de provider IA sans perdre les conversations ?

Oui, la bascule Claude ↔ OpenAI est instantanée et n’affecte pas l’historique. Les nouvelles conversations utiliseront le nouveau provider.

Le plugin fonctionne-t-il en mode headless ?

L’API REST du plugin (/wp-json/dfaics/v1/) est utilisable depuis n’importe quel front (Next.js, Vue, mobile). Le widget natif est en vanilla JS et peut être remplacé par votre propre implémentation qui appelle la même API.

Peut-on brancher le plugin sur Zendesk ou Freshdesk ?

Pas nativement en 1.0.0 : l’escalade est limitée à Slack et email. Vous pouvez cependant utiliser le hook dfaics_escalated pour déclencher votre propre intégration.

Est-ce que l’agent apprend de mes conversations ?

Non. Aucun fine-tuning n’est effectué. L’agent utilise uniquement le prompt système + les outils + le contexte de la conversation en cours. Vos données ne sont pas utilisées pour améliorer les modèles Anthropic ou OpenAI (les deux providers offrent une option d’opt-out qui est active par défaut sur leurs APIs professionnelles).

15. Support

Pour toute question ou signalement de bug, écrivez à support at datafirefly.com en indiquant votre numéro de licence. Nous répondons sous 48 h ouvrées.