Le bon chatbot ne se résume pas à une API branchée sur une bulle de discussion. Il faut une architecture nette, un contrat JSON stable, une gestion sérieuse du cache et une logique de navigation qui ne casse pas le tunnel conversationnel.
Les quatre idées qui structurent tout le projet :
- Le front ne doit jamais voir la clé API
- Le prompt doit imposer un JSON strict
- L’historique visuel et l’historique envoyé au modèle ne sont pas la même chose
- Un bouton link a besoin d’une logique de suite si l’on veut continuer la conversation sur la page suivante
Pourquoi ce type de chatbot mérite une vraie architecture ?
Sur l’un de nos sites client, l’objectif n’était pas de placer une simple bulle de discussion décorative dans le coin d’une page. Il fallait guider un visiteur vers un catalogue de formations, clarifier les abonnements, lever les freins commerciaux, conserver l’historique entre deux pages et continuer la discussion sans exposer la clé API côté navigateur.
C’est précisément le point où beaucoup de projets échouent. Le premier prototype marche sur une page isolée, puis tout se casse dès qu’on ajoute un cache agressif, un changement de page, un bouton d’action, un rechargement ou un vrai trafic. La bonne approche consiste donc à traiter le chatbot comme un composant applicatif complet, avec un front, un proxy serveur, un contrat de réponse strict, un mécanisme de persistance de session et une stratégie de débogage.
La promesse d’un bon chatbot WordPress avec l’API ChatGPT est simple. Il doit répondre vite, rester lisible, relancer la conversation au bon moment, orienter proprement vers des pages utiles et continuer son tunnel même après navigation. Pour atteindre ce résultat, il faut une structure technique sobre, mais rigoureuse.
Schéma d’ensemble la stabilité vient de la séparation claire entre front, plugin WordPress, prompt système et API.
La pile technique qui tient en production
Le socle le plus fiable reste un plugin WordPress sur mesure. Le front JavaScript gère l’interface, l’historique de session, l’affichage des boutons, la persistance temporaire et l’expérience utilisateur. Le plugin PHP agit comme proxy serveur, lit le prompt système, appelle l’API OpenAI et renvoie au front un JSON propre contenant trois éléments : intent, message et actions. Cette séparation est essentielle, car elle permet de garder la clé API côté serveur et d’isoler les erreurs réseau ou de format.
Le flux recommandé est le suivant. Le navigateur envoie un message utilisateur au endpoint WordPress. Le proxy PHP assemble le prompt système et l’historique utile, puis appelle l’API Responses. Le front reçoit ensuite une réponse structurée et l’affiche sans recharger la page. À ce stade, la stabilité dépend moins du modèle que de la qualité du contrat JSON et de la discipline d’intégration.
Le vrai gain de cette architecture est opérationnel. Elle permet d’ajouter un indicateur d’écriture, de limiter les requêtes simultanées, de tronquer l’historique envoyé au modèle, de supporter des boutons intent et link, et de gérer un tunnel après navigation sans réinventer toute la logique conversationnelle.
{
« intent »: « I3_DEBUTANT »,
« message »: « Ce site est parfaitement adapté aux débutants. »,
« actions »: [
{ « label »: « Voir le cours recommandé », « type »: « link », « url »: « /cours-en-ligne/… » },
{ « label »: « Voir les abonnements », « type »: « intent », « value »: « I7_ABONNEMENTS » }
]
}
Exemple minimal : le front sait quoi afficher parque que la réponse garde toujours la même structure.
Poser un contrat de réponse strict avant d’écrire la première ligne de front
Un chatbot commercial devient vite incohérent si le modèle renvoie parfois du texte brut, parfois du JSON partiel et parfois une réponse conversationnelle sans actions. C’est pourquoi le prompt système doit imposer un format de sortie unique. Une structure simple fonctionne très bien : intent pour l’étape logique, message pour le texte visible, actions pour les boutons.
Dans la pratique, le prompt système doit aussi donner des règles d’or. Répondre en français. Ne pas inventer d’information. Utiliser uniquement les URLs prévues. Proposer des actions courtes et explicites. Renvoyer toujours du JSON strict. Cette discipline évite une grande partie des bugs qui sont souvent attribués à tort au modèle alors qu’ils proviennent d’un contrat flou.
Il faut également séparer clairement les rôles de intent, value et after_intent. Un bouton intent déclenche immédiatement une requête API sur la même page. Un bouton link ouvre une autre page. Un bouton link doté de after_intent stocke une suite logique à exécuter sur la page suivante. Ce découpage semble mineur, mais il change complètement la fiabilité du tunnel conversationnel.
Créer le plugin WordPress comme un proxy et non comme un simple script
Le plugin n’a pas besoin d’être complexe, mais il doit être propre. Il faut un fichier principal pour l’enregistrement des hooks, un répertoire JS, un répertoire CSS et un fichier prompt-system.txt. Le plugin doit pouvoir s’injecter partout sur le site, idéalement via wp_footer, tout en évitant les doublons si un shortcode existe déjà.
Côté serveur, le point critique est le endpoint REST. Il reçoit le message, applique un rate limit minimal, lit le prompt système et prépare l’entrée pour l’API. Avec la Responses API, la structure des contenus doit être correcte. Les messages utilisateur partent en input_text. Les messages assistant renvoyés dans l’historique doivent être envoyés en output_text. Une erreur de type à cet endroit produit immédiatement un code 400.
Le proxy est aussi le bon endroit pour centraliser les protections. Limitation simple par IP, contrôle de taille de message, traitement propre des erreurs 429, et fallback lisible si le quota API est dépassé. En phase de développement, il est préférable d’afficher une erreur claire dans le chat plutôt qu’un silence total. En production, on peut renvoyer une réponse utile avec des liens vers les pages clés même si l’API est momentanément indisponible.
Rendre le front robuste face au cache, au reload et à la navigation
Sur WordPress, le problème n’est presque jamais le premier message. Le vrai problème apparaît au changement de page, surtout avec un cache type LiteSpeed. Sans persistance locale, le visiteur perd tout. Sans réhydratation correcte, les messages reviennent mais pas les boutons. Sans garde-fous, le widget relance start à répétition et déclenche des quotas ou des limites serveur.
La solution la plus simple consiste à stocker la session du chat dans sessionStorage. Ce choix est pertinent pour un tunnel par onglet. La conversation reste active tant que l’onglet reste ouvert, mais elle ne pollue pas les sessions futures. L’historique stocké doit contenir des messages texte et des blocs d’actions. Au rechargement, le script reconstitue l’interface en relisant cet historique. Le chatbot retrouve alors ses messages, ses boutons, son état réduit ou ouvert et peut reprendre la suite du tunnel.
Il faut aussi distinguer ce qui est affiché au visiteur de ce qui est envoyé au modèle. Le front peut conserver tout l’historique visuel, mais ne doit transmettre au backend que les derniers messages texte utiles, par exemple les douze derniers éléments pertinents. On réduit ainsi la taille des payloads, on garde un contexte suffisant et on diminue le risque de lenteur ou de blocage.
Différencier intent et link + after intent évite les tunnels cassés au changement de page
Gérer correctement les boutons intent, link et after_intent
C’est ici que beaucoup de chatbots donnent une impression de bricolage. Un bouton intent ne doit pas afficher sa valeur technique. Si l’utilisateur clique sur Je débute, le fil de discussion doit montrer Je débute , pas I3_DEBUTANT. Le front affiche donc le label et envoie la value au backend. Cette petite différence améliore énormément la lisibilité.
Pour un bouton link, la logique est différente. Si l’on navigue directement sans préparation, toute continuation conversationnelle disparaît. Une première méthode consiste à stocker un pending intent dans la session et à le relire sur la page cible. Une méthode encore plus robuste consiste à créer un nav job indépendant, consommé une seule fois après chargement. Ce job attend quelques secondes, puis déclenche un intent de suite, par exemple I10_CONTACT ou I6_CATALOGUE_PAGE. Le visiteur a alors l’impression que le chatbot l’accompagne naturellement d’une page à l’autre.
Cette distinction n’est pas qu’un détail de code. Elle permet d’organiser un vrai tunnel. Depuis l’accueil, un bouton ouvre le catalogue. Sur la page catalogue, after_intent relance une réponse spécifique au contexte et propose de filtrer par niveau, de comparer les abonnements ou de contacter l’équipe. Le chatbot ne se contente plus de répondre, il orchestre un parcours.
Ajouter les bons garde-fous pour éviter les faux bugs
Beaucoup de dysfonctionnements attribués au modèle viennent en réalité de couches périphériques. Le premier piège est le cache JavaScript. Une ancienne version du fichier peut rester servie alors que le code a déjà changé. Le remède le plus simple est d’utiliser un nom de fichier distinct ou un versioning basé sur filemtime côté plugin.
Le deuxième piège est le nonce REST combiné au cache. Sur certaines pages servies avec un nonce périmé, les appels échouent de manière aléatoire. Si le chatbot est public et déjà protégé par un rate limit côté serveur, un endpoint REST public avec contrôles applicatifs est souvent plus stable qu’un faux sentiment de sécurité porté par un nonce fragile.
Le troisième piège est l’excès de requêtes. Il faut poser un verrou in-flight pour empêcher deux appels simultanés, un petit cooldown entre deux requêtes et une fonction ensureStartedOnce qui évite de relancer start alors que l’historique existe déjà. Sans ces trois garde-fous, un widget peut paraître instable, alors que la cause réelle est simplement un doublon de requêtes.
Le quatrième piège est la qualité du débogage. Sur ce type de projet, F12, l’onglet Network et le filtrage sur /wp-json/cc-chatbot/v1/chat deviennent des outils quotidiens. Tant qu’on ne voit pas un POST réel, il est inutile d’accuser le prompt. Tant qu’un 429 local existe, il est inutile d’augmenter la température du modèle. Le temps gagné est énorme dès qu’on lit le bon symptôme au bon endroit.
Quand un bug apparaît, la lecture du bon symptôme dans Network fait gagner un temps considérable
Réflexe de production avant d’accuser le modèle, filtrer l’onglet Network sur /wp-json/cc-chatbot/v1/chat, vérifier les POST réels, regarder le code HTTP et lire la réponse brute renvoyée par le proxy WordPress.
Améliorer l’UX avec des détails qui comptent
Un bon chatbot technique n’a pas besoin d’artifices, mais certains détails changent radicalement la perception du produit. Le premier est l’indicateur d’écriture. Trois petits points animés suffisent à montrer qu’une réponse est en cours, que l’action a bien été prise en compte et que le système ne s’est pas figé. Cet indicateur doit apparaître pour les intents, les messages texte et les suites déclenchées après navigation.
Le second détail est la réduction du widget. Sur mobile, une fenêtre plein écran donne vite une impression d’intrusion. Une bulle réduite au chargement, puis une ouverture à environ soixante-dix pour cent de la largeur et de la hauteur, offre un meilleur compromis entre visibilité et confort. Le troisième détail est la persistance des boutons dans le fil de discussion. Un bouton affiché dans une zone séparée se perd visuellement. Un bouton inséré dans la conversation s’intègre beaucoup mieux à la mémoire du parcours.
Enfin, il faut veiller à la qualité des libellés. Les visiteurs ne cliquent pas sur des codes fonctionnels, ils cliquent sur des formulations claires. Le bon libellé n’est pas Catalogue. Le bon libellé est Voir les cours débutants ou Comparer les abonnements. Cette précision améliore à la fois le taux de clic et la qualité du contexte envoyé ensuite au modèle.
La check-list de mise en production
Avant la mise en ligne, une série de vérifications évite la plupart des incidents. La première concerne la facturation API et les quotas, car un chatbot techniquement parfait peut tomber immédiatement si le projet API n’a plus de budget. La deuxième concerne le bon chargement du script sur toutes les pages, avec exclusion éventuelle des optimisations JS trop agressives. La troisième concerne les POST réels vers le endpoint WordPress. Ils doivent être visibles, contrôlables et raisonnables en volume.
La quatrième vérification touche le prompt système. Il doit rester lisible, maintenable et centré sur les intents réels. Ajouter une base de connaissance n’a de sens que si l’on conserve un contrat de réponse strict. La cinquième vérification concerne la session. Changement de page, rechargement, ouverture sur mobile, retour arrière, clic sur un lien, tout cela doit être testé comme un parcours utilisateur réel.
La dernière vérification porte sur le niveau d’autonomie du chatbot. Un bon assistant n’est pas seulement capable de répondre à une question. Il sait relancer une intention, à l’image de Reimagine YouTube Shorts qui relance une idée à partir d’un contenu existant, afficher un bouton utile, reprendre un fil interrompu, éviter les redites et continuer le tunnel sans casser l’expérience. C’est cette continuité qui transforme un widget de support en outil de conversion.
Check-list de validation rapide
Contrôle | Ce qu’il faut observer | Validation |
Chargement du script | Un seul fichier JS chatbot chargé, bonne version visible dans la console | ok / non |
Persistance de session | Messages et boutons réapparaissent après reload dans le même onglet | ok / non |
Navigation inter-pages | Link + suite logique relance bien le tunnel après changement de page | ok / non |
API et quota | POST visibles, réponses 200, budget API actif | ok / non |
Mobile | Chat réduit au chargement, ouverture lisible sans plein écran agressif | ok / non |
A retenir pour aller vite et bien
Construire un chatbot WordPress avec l’API ChatGPT ne demande pas une architecture lourde. En revanche, cela demande des choix nets. Un proxy serveur pour protéger la clé. Un prompt système contractuel. Un front léger mais discipliné. Une persistance de session. Un historique tronqué avant envoi. Une différenciation claire entre intent et link. Et un plan de débogage pragmatique.
La vraie bascule se produit quand on cesse de traiter le chatbot comme une boîte noire. Le jour où l’on suit réellement le trajet d’un clic, du bouton jusqu’au POST, puis du POST jusqu’au rendu dans la conversation, le projet devient beaucoup plus simple à stabiliser. La complexité n’est plus abstraite. Elle se découpe en micro-problèmes mesurables et donc corrigeables.
Pour un technicien, la leçon est simple. Un chatbot performant n’est pas celui qui parle le mieux. C’est celui qui parle correctement, au bon moment, dans une interface fiable, avec des appels maîtrisés, une mémoire temporaire cohérente et des actions qui font avancer l’utilisateur. C’est exactement ce qui permet d’apprendre vite, d’industrialiser proprement et de livrer un composant réellement utile sur un site web.
