Guide du module HelpDesk pour Larapen

Un système de support client complet avec gestion des tickets, routage par département, champs personnalisés et une Base de Connaissances intégrée : le tout dans un seul add-on Larapen.

Cas d’utilisation

Bureau de support produit

Vous vendez des logiciels ou des produits numériques et avez besoin d’un système de support structuré.

• Créez des départements pour chaque ligne de produits (par ex. “Support Plugin”, “Support Thème”).
• Ajoutez des champs personnalisés pour collecter la version du produit, l’URL ou la clé de licence lors de la création du ticket.
• Activez l’accès invité pour que les clients puissent soumettre des tickets sans s’inscrire.
• Utilisez l’assistant IA pour rédiger des réponses et accélérer les temps de réponse.

HelpDesk informatique interne

Votre entreprise a besoin d’un système de tickets interne pour les demandes de support informatique.

• Désactivez l’accès invité : seuls les employés authentifiés peuvent soumettre des tickets.
• Créez des départements : “Matériel”, “Logiciel”, “Réseau”, “Accès & permissions”.
• Utilisez les niveaux de priorité (Basse, Moyenne, Élevée, Urgente) pour le suivi SLA.
• Construisez une Base de Connaissances avec des FAQ et des guides de dépannage pour réduire le volume de tickets.

Portail de documentation en libre-service

Vous souhaitez un centre d’aide public avec des articles consultables organisés par sujet.

• Créez des collections KB pour les sujets principaux (Démarrage, Référence API, Facturation, etc.).
• Utilisez des collections imbriquées pour les sous-catégories.
• Activez les votes d’utilité pour que les utilisateurs puissent noter les articles.
• Liez le formulaire “Soumettre un ticket” depuis les pages d’articles, pour les problèmes non couverts par la documentation.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• barryvdh/laravel-dompdf (pour l’export PDF)
• laravel/ai (pour les fonctionnalités de l’assistant IA ; optionnel mais recommandé)

Installation

Étape 1 : Téléverser l’add-on

Dans le panneau d’administration, allez dans Admin → Extensions → Add-ons et cliquez sur le bouton Télécharger un add-on. Sélectionnez le fichier ZIP de l’add-on : le système le décompresse automatiquement et l’add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l’add-on

Repérez HelpDesk & Base de Connaissances dans la liste et cliquez sur Activer. Ses migrations, ses seeders (le cas échéant) et ses permissions sont mis en place automatiquement.

Étape 3 : Configurer

Naviguez vers Admin → HelpDesk → Paramètres pour configurer le workflow des tickets, l’accès invité, les champs personnalisés et les notifications. Voir Configuration.

Étape 4 : Créer des départements

Naviguez vers Admin → HelpDesk → Départements et créez au moins un département (par ex. “Support général”). Les départements sont obligatoires : un ticket ne peut pas être soumis sans département.

Code d’achat (clé de licence)

HelpDesk est vendu comme un produit séparé, il possède donc son propre code d’achat (clé de licence), distinct du code d’achat de l’application principale et de celui de chaque autre add-on. Il vous est demandé lorsque vous activez HelpDesk dans Panneau d’administration → Add-ons.

Nos produits sont vendus sur trois plateformes. La façon dont vous recevez un code d’achat dépend de l’endroit où vous avez acheté le produit.

Plateforme / Marketplace	Comment obtenir le code d’achat	Où le retrouver
Boutique bedigit.com Achat sur le site (Shop)	Généré automatiquement lorsque la commande est payée, puis envoyé par e-mail, soit dans un e-mail de licence dédié, soit dans l’e-mail de confirmation de commande.	Mon compte → Mes licences sur bedigit.com
Gumroad	Créé dès que Gumroad nous notifie la vente, puis envoyé dans un e-mail séparé, en plus du reçu Gumroad.	L’e-mail de licence, votre Bibliothèque Gumroad et Mon compte → Mes licences sur bedigit.com
Envato Market CodeCanyon	Délivré par Envato, pas par nous, et jamais envoyé par e-mail : vous le téléchargez vous-même depuis votre compte Envato.	Compte Envato → Downloads → License certificate & purchase code

1. Boutique bedigit.com (achat sur le site)

• Dès que le statut de paiement de la commande devient Payée, une clé de licence est générée automatiquement pour chaque article sous licence de la commande (une clé par unité achetée : acheter 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l’adresse utilisée pour la commande, soit dans un e-mail de licence dédié, soit dans l’e-mail de confirmation de commande. Vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• La clé reste disponible dans votre compte sous Mon compte → Mes licences. Les clés sont masquées dans la liste ; ouvrez la page de détail de la licence pour afficher et copier la clé complète, voir les domaines sur lesquels elle est activée, et désactiver un domaine pour libérer un emplacement d’activation.
• La facture correspondante se trouve sous Mon compte → Mes commandes.

2. Gumroad

• Un achat sur Gumroad produit deux e-mails distincts : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un e-mail de clé de licence (envoyé par bedigit.com) qui contient votre code d’achat.
• L’e-mail de clé de licence est généré dès que Gumroad nous notifie la vente, il arrive donc normalement quelques secondes après le paiement. Ici aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonctionnalité de clés de licence propre à Gumroad, la même clé apparaît aussi dans votre reçu Gumroad et sous Bibliothèque → votre achat sur gumroad.com.
• Utilisez la même adresse e-mail sur bedigit.com que sur Gumroad : vos clés sont alors liées automatiquement à votre compte et listées sous Mon compte → Mes licences, même si vous vous inscrivez après l’achat. Vous pouvez aussi ajouter une clé Gumroad manuellement depuis Mon compte → Mes licences Gumroad.

3. Envato Market (CodeCanyon)

• Les codes d’achat Envato sont délivrés et fournis par Envato Market, jamais envoyés par e-mail par nous, il n’y a donc rien à chercher dans votre dossier de spam : vous récupérez le code depuis votre compte Envato.
• Connectez-vous à votre compte Envato / CodeCanyon, ouvrez la page Downloads, trouvez l’article et choisissez License certificate & purchase code dans le menu déroulant Download. Le code est inscrit dans ce certificat.
• Un code d’achat Envato ressemble à 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 caractères). Il ne change jamais, et le renouvellement du support de l’article n’en délivre pas de nouveau.
• Article officiel Envato : Where Is My Purchase Code?

Configuration

Les paramètres sont gérés dans Admin → HelpDesk → Paramètres (stockés dans la table settings, groupe helpdesk). Les valeurs par défaut du fichier de configuration sont dans config/helpdesk.php.

Paramètres des tickets

Paramètre	Description	Par défaut
helpdesk_guest_access	Autoriser les utilisateurs non authentifiés à créer des tickets.	true
helpdesk_items_per_page	Nombre de tickets par page dans les listes.	15
helpdesk_auto_close_resolved_days	Fermer automatiquement les tickets résolus après N jours d’inactivité. Mettre 0 pour désactiver.	0
helpdesk_allow_customer_close	Autoriser les clients à fermer leurs propres tickets depuis le portail front-end.	true
helpdesk_allow_priority_selection	Afficher le sélecteur de priorité sur le formulaire de création de ticket.	false
helpdesk_allow_attachments	Autoriser les pièces jointes sur les tickets et les réponses.	true
helpdesk_max_attachment_size	Taille maximale des pièces jointes en Ko.	5120 (5 Mo)
helpdesk_replies_order	Ordre d’affichage des réponses : oldest_first ou newest_first. Les réponses reçues par e-mail utilisent l’en-tête Date: du message comme created_at, cet ordre s’applique donc aussi aux messages ingérés.	oldest_first
helpdesk_tickets_order	Ordre des listes de tickets de l’administration : priority_date (la priorité d’abord, puis la date) ou date (la date seulement).	date
helpdesk_response_time	Temps de réponse attendu affiché aux clients.	48
helpdesk_response_time_unit	Unité du temps de réponse : minutes, hours, days, weeks.	hours
helpdesk_reply_draft_autosave_enabled	Enregistrer automatiquement la réponse en cours de rédaction sur la page de ticket admin (le message, l’option note interne et les fichiers joints), par ticket et par agent.	true
helpdesk_reply_draft_autosave_interval	Secondes entre deux enregistrements automatiques tant que le formulaire de réponse contient des modifications non enregistrées (5–600).	30
helpdesk_reply_draft_manual_save_enabled	Affiche un bouton Enregistrer le brouillon sur le formulaire de réponse. Désactivé, le bouton est masqué. Les deux options de brouillon désactivées désactivent entièrement les brouillons.	true
helpdesk_reply_form_position	Position du formulaire de réponse sur la page de ticket admin : before ou after les messages du ticket.	after
helpdesk_reply_editor_height	Hauteur en pixels de l’éditeur de réponse admin à son ouverture (60–1000). Il grandit avec la réponse en cours de rédaction. Les autres éditeurs conservent la hauteur WYSIWYG globale.	150
helpdesk_reply_editor_max_height	Hauteur en pixels à laquelle l’éditeur de réponse admin cesse de grandir ; une réponse plus longue défile à l’intérieur. 0 supprime la limite.	500

Paramètres de notification

Les notifications du HelpDesk sont enregistrées comme types de notification : elles s’activent et se désactivent sous Admin → Paramètres → Notifications, et non sur la page des paramètres du HelpDesk. Chaque type stocke un paramètre, et l’interrupteur principal notifications_enabled désactive toutes les notifications d’un coup. Les utilisateurs peuvent en outre se désabonner par type et par canal depuis leurs propres préférences de notification.

Paramètre	Description	Par défaut
notification_helpdesk_new_ticket_admin	Notifier tous les administrateurs lorsqu’un nouveau ticket est créé.	true
notification_helpdesk_ticket_confirmation	Envoyer l’e-mail de confirmation à l’auteur du ticket après la soumission.	true
notification_helpdesk_new_reply	Notifier l’auteur du ticket lorsqu’un agent publie une réponse (les notes internes sont exclues).	true
helpdesk_mail_from_address	Adresse d’expédition des e-mails du HelpDesk (Admin → HelpDesk → Paramètres → Notifications). Vide, elle reprend l’expéditeur par défaut du site.	vide
helpdesk_mail_from_name	Nom d’expéditeur des e-mails du HelpDesk. Vide, il reprend le nom d’expéditeur par défaut du site.	vide

Paramètres de la Base de Connaissances

Paramètre	Description	Par défaut
kb_require_auth	Exiger l’authentification pour accéder à la Base de Connaissances. Les articles dont la visibilité est always_public restent lisibles par tous.	false
kb_items_per_page	Nombre d’articles par page.	12
kb_show_search	Afficher la barre de recherche sur la page d’index de la KB.	true
kb_show_reading_time	Afficher le temps de lecture estimé sur les articles (calculé à ~200 mots/min).	true
kb_show_helpful_votes	Afficher le vote “Cet article était-il utile ?” oui/non sur les articles.	true
kb_show_related_articles	Afficher les articles connexes de la même collection en bas des pages d’articles.	true
kb_show_descendant_articles	Sur la page d’une collection, lister aussi les articles de toutes ses sous-collections (à toute profondeur), et pas seulement ses propres articles.	false

Types de pièces jointes autorisés

Les types de fichiers suivants sont acceptés pour les pièces jointes (configurés dans config/helpdesk.php) :

Admin : tableau de bord

Le tableau de bord (HelpDesk → Tableau de bord) fournit une vue combinée de tous les tickets avec des statistiques.

Cartes de statistiques

Compteurs agrégés affichés en haut :

• Total : tous les tickets du système
• Ouvert : tickets avec le statut open
• En cours : tickets en cours de traitement
• En attente : nombre combiné de waiting_customer et waiting_agent
• Résolu : tickets marqués comme résolus
• Fermé : tickets définitivement fermés

Graphiques

Sous les cartes de statistiques, quatre graphiques décrivent les tickets ouverts sur une période choisie avec les boutons en haut de la page (7 derniers jours, 30 jours, 90 jours ou 12 mois). Les cartes de statistiques reflètent l’arriéré en temps réel et ne dépendent pas de la période.

• Volume de tickets : tickets ouverts et tickets fermés par jour (par semaine sur 90 jours, par mois sur 12 mois)
• Tickets par statut : le statut actuel des tickets ouverts sur la période
• Tickets par département : où ces tickets ont été déposés, du département le plus chargé au moins chargé (les tickets sans département comptent comme Non assigné)
• Meilleurs clients : les clients inscrits ayant ouvert le plus de tickets

Chaque barre et chaque secteur est un lien : un clic ouvre la liste Tous les tickets déjà filtrée par ce statut, ce département ou ce client.

Admin : tickets

Listes de tickets filtrées

L’entrée Tickets de la barre latérale ouvre la liste Ouvert et porte un badge indiquant le nombre de tickets ouverts. De là, le bouton déroulant en haut de la page bascule entre les vues pré-filtrées, chacune n’affichant que les tickets d’un groupe de statut spécifique :

Liste	Statuts inclus
Ouvert	open
En pause	on_hold
En cours	in_progress, waiting_customer, waiting_agent, no_response
Résolu	resolved
Fermé	closed
Tous les tickets	tous les statuts
Sans réponse	no_response

Chaque liste prend en charge des filtres supplémentaires pour la priorité, le département, le client et la recherche.

Les listes sont triées par date par défaut, de la plus récente à la plus ancienne : selon la dernière réponse du client dans la liste Ouverts, et selon la dernière activité des messages (réponse ajoutée ou modifiée) dans les autres listes. Réglez HelpDesk → Paramètres → Affichage & Comportement → Ordre des tickets sur Par priorité, puis par date pour lister d’abord les tickets urgents, puis ceux de priorité haute, moyenne et basse, chaque niveau conservant l’ordre par date. Pour répondre en premier à certains clients, donnez à leurs tickets une priorité plus élevée avec un filtre de tickets (l’action Définir la priorité).

Dans chaque liste, une ligne ouvre le ticket, et trois de ses cellules sont aussi de vrais liens, qui peuvent donc être ouverts dans un nouvel onglet depuis le menu du clic droit :

• le Sujet ouvre le ticket ;
• le nom Soumis par ouvre la liste Tous les tickets filtrée par ce client (pour un invité, la liste est recherchée par son e-mail) ;
• le Département ouvre la liste Tous les tickets filtrée par ce département.

Page de détail du ticket

La page de détail du ticket (HelpDesk → Tickets → {reference}) affiche :

• En-tête du ticket : numéro de référence, sujet, badge de statut, badge de priorité, département, informations du demandeur, date de création
• Contrôles Statut/Priorité/Département : sélecteurs déroulants en ligne pour changer le statut, la priorité ou le département (alimentés par AJAX, retournent des réponses JSON)
• Fil de conversation : toutes les réponses par ordre chronologique (configurable via helpdesk_replies_order). Chaque réponse affiche le nom de l’auteur, le badge admin/client, l’horodatage, le texte du corps et les pièces jointes
• Notes internes : notes réservées aux administrateurs, visibles uniquement par le personnel, stylées différemment des réponses clients
• Valeurs des champs personnalisés : les valeurs soumises pour tous les champs personnalisés du ticket
• Tickets récents : panneau latéral affichant jusqu’à 10 tickets récents du même client
• Achats Envato : si l’add-on Envato est actif et que le ticket a un utilisateur lié, affiche les achats Envato vérifiés de l’utilisateur

Répondre aux tickets

Le formulaire de réponse en bas de la page de détail du ticket prend en charge :

• Corps de la réponse : zone de texte riche pour la réponse
• Bascule note interne : marque la réponse comme note interne uniquement (non envoyée au client, non visible sur le front-end)
• Pièces jointes : joindre des fichiers à la réponse
• Brouillons : la réponse non envoyée (le message, l’option note interne et les fichiers joints) est conservée par ticket et par agent. Elle est enregistrée automatiquement à intervalle régulier et/ou avec le bouton Enregistrer le brouillon, selon les paramètres Brouillons de réponse ; Supprimer le brouillon l’abandonne. Les fichiers enregistrés avec le brouillon sont rattachés à la réponse lors de l’envoi et comptent dans la limite de pièces jointes
• Action de réponse : après l’envoi, choisir de rester sur le ticket, d’aller à la liste des tickets ou de passer au ticket suivant
• Modifier/Supprimer les réponses : les administrateurs peuvent modifier le corps de n’importe quelle réponse ou supprimer des réponses entièrement (alimenté par AJAX)

Mises à jour automatiques du statut lors de la réponse

Lorsqu’une réponse est publiée sur un ticket ouvert :

• Réponse admin → le statut change automatiquement en in_progress
• Réponse client → le statut change automatiquement en open
• Les tickets en pause restent on_hold lors d’une réponse client ou d’une note interne ; une réponse publique de l’admin les passe en in_progress
• Les tickets fermés/résolus ne sont pas mis à jour automatiquement

Tickets en pause

Mettez un ticket En pause (sélecteur de statut sur la page du ticket) lorsqu’il ne demande pas de réponse urgente et que vous souhaitez y répondre correctement plus tard. Le ticket quitte la liste Ouvert et le badge Tickets de la barre latérale, et attend dans la liste En pause du sélecteur.

• Le client ne voit jamais En pause : de son côté, le ticket reste affiché comme Ouvert.
• Un nouveau message du client laisse le ticket en pause, tout comme une note interne.
• Une réponse publique d’un agent sort le ticket de la pause et le passe en in_progress.
• Le marquage automatique Sans réponse ignore les tickets en pause.

Fusion & export PDF

Fusion de tickets

L’administrateur peut fusionner un ticket source dans un ticket cible via POST admin/helpdesk/tickets/{ticket}/merge. Cette opération :

1. Déplace toutes les réponses de la source vers le ticket cible
2. Déplace les pièces jointes au niveau du ticket (relation morph) vers la cible
3. Supprime les valeurs des champs personnalisés de la source (non transférables)
4. Supprime l’enregistrement du ticket source

L’opération entière s’exécute à l’intérieur d’une transaction de base de données.

Export PDF

Cliquez sur le bouton Télécharger PDF sur n’importe quelle page de détail de ticket pour générer un PDF formaté contenant l’en-tête du ticket, toutes les réponses et les métadonnées. Utilise barryvdh/laravel-dompdf.

Admin : filtres de tickets

Les filtres de tickets sont des règles qui agissent automatiquement sur les tickets : les fermer, les déplacer vers la corbeille, les diriger vers un département, modifier leur priorité, et plus encore. Gérés via HelpDesk → Filtres de tickets.

Fonctionnement des filtres

• Sur les nouveaux tickets : chaque filtre actif dont l’option Exécuter sur les nouveaux tickets est activée est vérifié dès la création d’un ticket, du haut de la liste vers le bas. Chaque filtre correspondant applique ses actions. Utilisez Réordonner les filtres pour modifier l’ordre.
• Arrêter ici : lorsqu’un filtre doté de cette option correspond, les filtres situés en dessous sont ignorés pour ce ticket.
• Sur les tickets existants : cliquez sur le bouton lecture d’un filtre pour voir combien de tickets existants correspondent (avec une liste d’exemples), puis appliquez le filtre à tous. Les tickets de la corbeille ne sont jamais inclus.

Les filtres s’exécutent avant l’envoi de toute notification : un filtre qui place un ticket de spam dans la corbeille n’envoie donc aucune notification au client ni aux agents (seuls les e-mails d’alerte et de transfert désignés par le filtre lui-même sont envoyés).

Conditions

Choisissez si toutes les conditions ou au moins une condition doivent correspondre. Conditions disponibles :

Groupe	Condition	Comparaisons
Client	Client (compte inscrit), E-mail du client (e-mail du compte ou de l’invité), Type de client (inscrit ou invité)	Fait partie de / ne fait pas partie de ; comparaisons de texte pour l’e-mail (contient, est égal à, commence par, se termine par...)
Produit	Produit possédé : le client détient une clé de licence active et non expirée pour l’un des produits choisis (nécessite l’add-on Licenses)	Fait partie de / ne fait pas partie de
Ticket	Département, Agent assigné (y compris “Non assigné”), Statut, Priorité, Canal (formulaire web, e-mail, API), Sujet, Message du client, Adresse IP	Fait partie de / ne fait pas partie de ; comparaisons de texte
Ticket	Âge du ticket, Inactivité (jours depuis le dernier message)	Plus de / moins de N jours

Les comparaisons de texte ignorent la casse. Astuce : E-mail du client se termine par @example.com cible toute une entreprise.

Actions

• Définir le statut : choisissez Fermé pour fermer les tickets automatiquement (enregistrés comme fermés par le système).
• Définir la priorité et Assigner à un département.
• Assigner à un agent : l’agent est prévenu par e-mail. Les agents sont les administrateurs et tout utilisateur autorisé à consulter les tickets du helpdesk. Les tickets peuvent aussi être assignés à la main depuis le sélecteur d’agent de l’en-tête du ticket, et les listes de tickets disposent d’une colonne et d’un filtre Agent, avec un interrupteur Mes tickets.
• Répondre avec une réponse prédéfinie : publie l’une de vos réponses prédéfinies et l’envoie par e-mail au client.
• Ajouter une note interne : une note visible uniquement par les agents.
• Envoyer une alerte par e-mail : une courte alerte (référence, sujet, client et lien vers le ticket) à 10 adresses au plus, séparées par des virgules.
• Envoyer le ticket par e-mail : le ticket complet (détails, tous les messages sauf les notes internes, et les pièces jointes jusqu’à 10 Mo) à 10 adresses au plus. Répondre à cet e-mail écrit au client.
• Désactiver l’alerte des agents : sur les nouveaux tickets uniquement, les agents ne sont pas prévenus.
• Déplacer vers la corbeille : le ticket peut encore être restauré depuis la corbeille.

Les actions s’exécutent toujours dans le même ordre : l’acheminement et la priorité d’abord, puis les messages, puis le statut, et la corbeille en dernier. Le bouton Aperçu du formulaire de filtre compte les tickets correspondants avant même l’enregistrement.

Admin : départements

Les départements organisent les tickets en groupes logiques (par ex. “Ventes”, “Support technique”, “Facturation”). Gérés via HelpDesk → Départements.

Champs de département

Champ	Description
Nom (traduisible)	Nom d’affichage montré aux clients dans le sélecteur de département.
Slug (traduisible)	Identifiant adapté aux URL.
Description (traduisible)	Description optionnelle pour référence administrative.
E-mail	E-mail de contact optionnel pour le département.
Est actif	Seuls les départements actifs apparaissent dans le formulaire de création de ticket.
Position	Ordre de tri dans les menus déroulants et les listes.

La page de liste des départements affiche le nombre de tickets par département. Opérations CRUD standard : créer, modifier, supprimer.

Créer un département à partir d’un produit de licence

Lorsque l’add-on Licences est actif, vous pouvez créer un département de support pour un produit sous licence directement depuis le catalogue des licences. Sur Licences → Produits, chaque produit porte un bouton Créer un département d’assistance (une icône de casque sur la ligne, et un bouton dans la fenêtre modale de modification du produit). En un clic :

• Un département helpdesk portant le nom du produit est créé (traductions, slug et état actif repris), ou mis à jour s’il a déjà été créé, aucun doublon n’est jamais produit.
• Un lien d’accès licence → département est ajouté automatiquement, de sorte que le département est réservé aux détenteurs de ce produit (voir Restriction par département). Les liens existants sur le département sont préservés.

Admin : champs personnalisés

Les champs personnalisés étendent le formulaire de création de ticket avec une collecte de données supplémentaire. Gérés via HelpDesk → Champs personnalisés.

Types de champs pris en charge

Type	Description	A des options ?
text	Saisie de texte sur une seule ligne (max 255 caractères)	Non
textarea	Saisie de texte multi-lignes (max 5000 caractères)	Non
select	Sélection déroulante avec options prédéfinies	Oui
checkbox	Cases à cocher multiples (valeurs stockées en JSON)	Oui
radio	Boutons radio avec options prédéfinies	Oui
number	Saisie numérique	Non
email	Saisie d’adresse e-mail avec validation de format	Non
date	Sélecteur de date	Non
file	Téléversement de fichier (stocké via MediaService)	Non

Propriétés des champs personnalisés

Champ	Description
Libellé (traduisible)	Libellé d’affichage montré à l’utilisateur.
Nom	Identifiant interne (utilisé comme nom de champ de formulaire).
Type	Un des 9 types pris en charge ci-dessus.
Options	Tableau de valeurs valides (uniquement pour les types select, checkbox, radio).
Texte indicatif (traduisible)	Texte indicatif pour la saisie.
Est requis	Si le champ est obligatoire lors de la création du ticket.
Est actif	Seuls les champs actifs sont affichés sur le formulaire.
Position	Ordre de tri sur le formulaire.

Validation dynamique

La méthode CustomFieldService::buildValidationRules() génère automatiquement les règles de validation Laravel à partir des définitions de champs personnalisés actifs. Les règles sont adaptées au type (par ex. le type email ajoute la validation e-mail, select/radio valident par rapport aux options définies, file valide les limites de taille).

Admin : Base de Connaissances

Collections KB

Les collections regroupent les articles en catégories. Gérées via HelpDesk → Collections KB.

• Imbricable : les collections prennent en charge une hiérarchie parent/enfant, que suit leur URL front-end : une collection “Guides” placée sous “Product” se trouve à /support/product/guides, et ses articles à /support/product/guides/article-slug.
• Slugs : le slug d’une collection doit seulement être unique parmi les collections qui partagent son parent ; deux collections sous des parents différents peuvent donc avoir le même nom et le même slug. Au premier niveau, tickets, search, article et vote sont réservés à d’autres pages du support.
• Traduisible : le nom, le slug et la description prennent en charge plusieurs langues.
• Icône : classe d’icône Bootstrap optionnelle (par ex. bi-book) affichée sur le front-end.
• Actif/Inactif : seules les collections actives sont affichées sur le front-end.
• Position : contrôle l’ordre de tri.

Articles KB

Les articles sont des documents à contenu riche au sein des collections. Gérés via HelpDesk → Articles KB.

Champs des articles

Champ	Description
Titre (traduisible)	Titre de l’article affiché dans les listes et comme en-tête de page.
Slug (traduisible)	Identifiant adapté aux URL, traduisible pour chaque langue. Il doit être unique dans toute la Base de Connaissances ; laissé vide, il est généré à partir du titre (avec un suffixe numérique s’il est déjà pris).
Contenu (traduisible)	Corps complet de l’article (contenu HTML).
Extrait (traduisible)	Résumé court affiché dans les listes d’articles.
Titre méta / Description méta (traduisible)	Remplacements des métadonnées SEO.
Collection	La collection KB à laquelle cet article appartient.
Statut	draft, published ou archived.
Visibilité	public (visible par tous), always_public (visible par tous, même si la Base de Connaissances exige une connexion) ou auth_only (connexion requise).
Position	Ordre de tri au sein de la collection.

Propriétés calculées

• Temps de lecture : calculé à partir du nombre de mots à ~200 mots par minute.
• Pourcentage d’utilité : ratio des votes positifs sur le total des votes (null si aucun vote).
• Compteur de vues : incrémenté chaque fois que l’article est consulté sur le front-end.

Liste des articles

La liste d’articles admin est paginée et filtrable par statut, collection et terme de recherche. Colonnes : titre, collection, badge de statut, visibilité, compteur de vues, position.

Paramètres KB

Une page de paramètres séparée, à HelpDesk → Paramètres KB, contrôle les options d’affichage de la Base de Connaissances (voir Configuration : paramètres de la Base de Connaissances).

Admin : paramètres

La page des paramètres (HelpDesk → Paramètres) est organisée en sections :

Configuration des tickets

• Bascule d’accès invité
• Éléments par page
• Jours de fermeture automatique
• Bascule d’autorisation de fermeture par le client
• Bascule d’autorisation de sélection de priorité
• Bascule d’autorisation des pièces jointes + taille maximale
• Ordre des réponses (plus anciennes d’abord / plus récentes d’abord)
• Brouillons de réponse : bascule et intervalle d’enregistrement automatique, bascule d’enregistrement manuel
• Formulaire de réponse : position (avant ou après les messages), hauteur et hauteur maximale de l’éditeur (l’éditeur grandit avec son contenu)
• Bascule CAPTCHA (s’intègre avec le CaptchaService du noyau)
• Temps de réponse et unité

Configuration des notifications

• Notifier les administrateurs lors d’un nouveau ticket
• Envoyer une confirmation à l’auteur du ticket
• Notifier l’auteur lors d’une nouvelle réponse

Configuration de la Base de Connaissances

• Accès invité / authentification requise
• Éléments par page
• Afficher la recherche / temps de lecture / votes d’utilité / articles connexes

Configuration du Pont Email

• Bascule principale + intégration de la réponse dans les e-mails sortants
• Stratégie de corrélation (en-têtes / plus-addressing / balise dans le sujet)
• Auto-répondeur pour expéditeur inconnu + limite de débit par expéditeur
• Auto-répondeur pour ticket fermé (la réponse envoyée par e-mail par un client n’est jamais ajoutée à un ticket fermé)
• Identifiants IMAP, dossier et intervalle d’interrogation
• Tentatives / délai de reconnexion pour les hébergeurs instables
• Jeton du webhook (régénérable depuis cette page)
• Voir Pont Email pour la référence complète.

Admin : Pont Email & tickets

Le Pont Email permet aux clients de répondre à la notification e-mail d’un agent et d’avoir cette réponse affichée comme un nouveau message sur le ticket. C’est un pont bidirectionnel :

• Sortant : lorsque le pont est activé, le corps de la réponse est intégré directement dans les e-mails NewReplyNotification pour que le client puisse répondre en ligne.
• Entrant : un poller lit la boîte IMAP configurée, corrèle chaque message avec un ticket existant et l’ajoute comme nouvelle réponse.
• Auto-répondeur : les e-mails provenant d’adresses ne pouvant pas être corrélées à un ticket déclenchent une réponse polie qui redirige l’expéditeur vers l’URL publique de création de ticket.
• Tickets fermés : un ticket fermé n’accepte que les réponses des agents. Un e-mail client associé à un tel ticket n’est pas ajouté ; l’expéditeur reçoit une réponse lui expliquant que le ticket est fermé, avec un lien pour en ouvrir un nouveau.

Tous les paramètres sont modifiables sous Admin → HelpDesk → Paramètres → Pont Email et sont persistés dans la table settings (groupe helpdesk). Les valeurs par défaut du fichier de configuration se trouvent dans config/helpdesk.php sous les clés email_bridge et imap.

Paramètres du pont

Paramètre	Description	Par défaut
helpdesk_email_bridge_enabled	Bascule principale. Si false, la commande CLI, l’ordonnanceur et le webhook renvoient immédiatement.	false
helpdesk_email_embed_reply_body	Intègre la réponse de l’agent dans les e-mails de notification sortants pour que les clients puissent répondre en ligne.	true
helpdesk_email_unknown_sender_autoresponder	Envoie un auto-répondeur poli aux expéditeurs dont l’e-mail ne peut pas être corrélé à un ticket. Désactivé en mode backfill pour ne pas répondre à d’anciens e-mails.	true
helpdesk_email_closed_ticket_autoresponder	Répond au client qui envoie par e-mail une réponse à un ticket fermé, en lui indiquant que le ticket est fermé et en lui donnant le lien de la page de création de ticket. La réponse est refusée dans tous les cas ; désactiver ce paramètre ne fait que supprimer l’e-mail de courtoisie.	true
helpdesk_email_correlation_strategy	Comment les e-mails entrants sont associés à un ticket : header (In-Reply-To / References), plus_addressing (support+REF@domain) ou subject_tag ([#REF]).	header
helpdesk_email_plus_addressing_prefix	Partie locale utilisée lorsque plus_addressing est actif (par ex. support).	support
helpdesk_email_subject_tag_format	Format de la balise pour la corrélation subject_tag. Doit contenir le placeholder :ref.	[#:ref]
helpdesk_email_rate_limit_per_hour	Nombre maximal de réponses entrantes acceptées par expéditeur et par heure glissante. Contourné en mode backfill.	10

Paramètres de la boîte IMAP

Paramètre	Description	Par défaut
helpdesk_imap_host / helpdesk_imap_port	Hôte et port du serveur (habituellement 993 pour IMAPS, 995 pour POP3S).	: / 993
helpdesk_imap_encryption	L’une de ssl, tls, starttls, none.	ssl
helpdesk_imap_validate_cert	Rejeter les certificats serveur auto-signés ou invalides.	true
helpdesk_imap_protocol	Protocole de messagerie : imap ou pop3.	imap
helpdesk_imap_username / helpdesk_imap_password	Identifiants de la boîte. Le mot de passe est stocké chiffré en base de données.	:
helpdesk_imap_folder	Dossier de la boîte à interroger.	INBOX
helpdesk_imap_poll_interval	Intervalle de l’ordonnanceur en minutes : 1, 5, 10, 15, 30 ou 60.	5
helpdesk_imap_max_per_poll	Nombre maximal de messages récupérés par cycle (plafonné à 500 par le contrôleur/la commande).	50
helpdesk_imap_connect_retries	Tentatives de connexion supplémentaires après la première erreur transitoire (par ex. “Connection refused” chez OVH lorsqu’une session précédente est encore retenue). 0 désactive la reprise.	1
helpdesk_imap_connect_backoff_seconds	Délai entre les tentatives de connexion.	3

Ordonnanceur & commande CLI

Une fois le pont activé, l’add-on enregistre automatiquement une commande Artisan planifiée :

php artisan helpdesk:fetch-inbound

Le service provider construit l’expression cron à partir de helpdesk_imap_poll_interval (par ex. */5 * * * * pour 5 minutes, 0 * * * * pour 60). La tâche s’exécute avec withoutOverlapping(10), runInBackground() et onOneServer().

La commande accepte aussi deux options pour les exécutions manuelles :

Option	Description
--limit=N	Nombre maximal de messages récupérés en un cycle. Par défaut 50 ; plafonné à 500.
--backfill	Inclut les messages déjà lus (\Seen). Désactive l’auto-répondeur et contourne la limite de débit par expéditeur pour importer sans risque de longs fils de discussion historiques.

Webhook entrant (déclencheur cron externe)

Certains hébergements bloquent IMAP sortant depuis la CLI mais l’autorisent depuis PHP-FPM. Dans ce cas, un ordonnanceur externe (cron-job.org, UptimeRobot, GitHub Actions, etc.) peut piloter le pont en appelant l’URL du webhook :

Récupération de boîtes existantes (backfill)

Activez le pont sur une boîte qui contient déjà de l’historique, puis importez les réponses existantes en une seule exécution :

php artisan helpdesk:fetch-inbound --backfill --limit=500

ou via le webhook :

GET /helpdesk/inbound/fetch/{token}?backfill=1&limit=500

Le mode backfill :

• Inclut les messages déjà lus (\Seen) (les interrogations normales n’utilisent que unseen()).
• Désactive l’auto-répondeur pour ne pas répondre à d’anciens e-mails sans rapport.
• Contourne la limite de débit par expéditeur pour les longs fils historiques.
• Conserve l’en-tête Date: d’origine de chaque réponse comme created_at, de sorte que le fil du ticket respecte l’ordre Plus récentes d’abord / Plus anciennes d’abord configuré dans les paramètres.
• Est idempotent : le hash SHA-256 du corps brut du message (inbound_raw_hash) bloque les doublons.

Admin : assistant IA

L’assistant IA est disponible sur la page de détail du ticket et fournit des actions IA contextuelles alimentées par le SDK Laravel AI.

Actions disponibles

Action	Description
suggest_reply	Générer une réponse professionnelle à un seul message client.
suggest_reply_conversation	Générer une réponse basée sur l’historique complet de la conversation du ticket. Le message actuel est marqué avec [CURRENT MESSAGE] pour que l’IA se concentre dessus.
suggest_reply_articles	Générer une réponse référençant des articles pertinents de la Base de Connaissances. Jusqu’à 5 articles sont recherchés par correspondance de mots-clés et nombre de vues.
summarize	Résumer les points clés d’un message client.
translate_english	Traduire le message en anglais.
translate_french	Traduire le message en français.
make_shorter	Condenser un message tout en préservant son sens.
custom_prompt	Traiter le texte avec une instruction personnalisée fournie par l’administrateur.

Configuration de l’agent

Le TicketAiAssistantAgent est configuré avec :

• Temperature(0.7) : équilibre entre créativité et précision
• MaxTokens(4096) : permet des réponses détaillées
• Le modèle IA est lu depuis setting('ai_default_model') ou retombe sur le modèle par défaut du fournisseur

Front-end : portail des tickets

Routes

Méthode	URL	Nom de route	Auth ?	Description
GET	/{locale}/support/tickets/new	helpdesk.create.localized	Invité*	Formulaire de création de ticket
POST	/{locale}/support/tickets	helpdesk.store.localized	Invité*	Soumettre un nouveau ticket
GET	/{locale}/support/tickets/confirmation/{reference}	helpdesk.confirmation.localized	Invité*	Page de confirmation du ticket
GET	/{locale}/support/tickets	helpdesk.tickets.localized	Oui	Liste de mes tickets
GET	/{locale}/support/tickets/{reference}	helpdesk.show.localized	Oui	Voir le détail du ticket & la conversation
POST	/{locale}/support/tickets/{reference}/reply	helpdesk.reply.localized	Oui	Publier une réponse client
POST	/{locale}/support/tickets/{reference}/close	helpdesk.close.localized	Oui	Fermer un ticket

* L’accès invité dépend du paramètre helpdesk_guest_access. Des variantes non localisées (sans {locale}) sont également enregistrées.

Formulaire de création de ticket

Le formulaire de création comprend :

• Sujet : champ texte requis (max 255 caractères)
• Département : menu déroulant requis des départements actifs
• Message : zone de texte requise (max 10 000 caractères)
• Priorité : menu déroulant optionnel (affiché uniquement si helpdesk_allow_priority_selection est activé)
• Champs invité : champs nom et e-mail (affichés uniquement pour les utilisateurs non authentifiés)
• Champs personnalisés : tous les champs personnalisés actifs sont rendus dynamiquement
• Pièces jointes : téléversement de fichiers (jusqu’à 5 fichiers, si les pièces jointes sont activées)
• CAPTCHA : affiché si activé via helpdesk_captcha_enabled

Numéros de référence des tickets

Chaque ticket reçoit un numéro de référence unique au format HD-7KQ4M9XP2R, généré automatiquement par le TicketObserver lors de la création. Les références sont aléatoires (10 caractères, sans les caractères ambigus 0/O et 1/I/L), de sorte qu’une référence ne peut pas être devinée à partir d’une autre.

Vue client du ticket

La page de détail du ticket côté front-end affiche :

• En-tête du ticket (référence, sujet, statut, priorité, département)
• Fil de conversation : les notes internes sont filtrées (non visibles pour les clients)
• Formulaire de réponse pour publier des messages supplémentaires
• Bouton de fermeture (si helpdesk_allow_customer_close est activé et que le ticket n’est pas déjà fermé)
• Valeurs des champs personnalisés

Contrôle d’accès

• Les utilisateurs authentifiés ne peuvent voir que leurs propres tickets (correspondance user_id)
• Les administrateurs peuvent voir tous les tickets
• Les tickets fermés ne peuvent pas recevoir de réponses des clients, ni depuis la page du ticket, ni par e-mail. Les agents et administrateurs peuvent toujours publier une réponse, ce qui ne rouvre pas le ticket

Front-end : Base de Connaissances

Routes

Méthode	URL	Nom de route	Description
GET	/{locale}/support	kb.index.localized	Accueil KB : collections, articles populaires & récents, recherche
GET	/{locale}/support/{collection-path}	kb.path.localized	Page de collection, à son chemin imbriqué (par ex. /support/product/guides) : articles de la collection + collections enfants
GET	/{locale}/support/{collection-path}/{article}	kb.path.localized	Page d’article sous la collection depuis laquelle il est consulté : contenu complet + articles connexes + vote. L’URL canonique est toujours sous la collection principale de l’article
GET	/{locale}/support/article/{slug}	kb.show.localized	Ancienne URL d’article : redirection 301 vers l’URL imbriquée de l’article
POST	/{locale}/support/vote/{id}	kb.vote.localized	Voter pour un article comme utile/non utile (AJAX)

Des variantes non localisées (sans {locale}) sont également enregistrées.

Page d’index KB

• Barre de recherche : recherche en texte intégral dans les titres d’articles, le contenu et les extraits (si kb_show_search est activé)
• Grille de collections : collections de niveau racine avec le nombre d’articles
• Articles populaires : top 5 des articles par nombre de vues
• Articles récents : 5 articles les plus récemment publiés

Page de collection

• Nom de la collection, description et icône
• Liste paginée des articles publiés dans la collection
• Collections enfants (le cas échéant)

Page d’article

• Contenu complet de l’article avec estimation du temps de lecture
• Votes d’utilité (boutons “Cet article était-il utile ?” oui/non, alimentés par AJAX)
• Articles connexes de la même collection
• Métadonnées SEO (titre méta / description méta depuis les champs de l’article ou générés automatiquement)

Visibilité & accès

• Les articles Publics sont visibles par tous
• Les articles Toujours publics sont visibles par tous, même si la KB exige une authentification : utilisez cette visibilité pour un guide dont les visiteurs ont besoin avant d’avoir un compte. Un visiteur non connecté ne voit que les autres articles Toujours publics dans la barre latérale et les articles liés d’une telle page
• Les articles Auth uniquement sont visibles uniquement par les utilisateurs authentifiés
• Si kb_require_auth est activé, l’ensemble de la KB nécessite une authentification, sauf les articles Toujours publics

Intégration des add-ons Licenses & Envato

Le contrôle d’accès basé sur les achats est piloté par l’add-on Licenses, qui couvre les clés de licence de tous les fournisseurs (Envato, Gumroad, la Boutique, manuel). L’add-on Intégration Envato Market ajoute les achats Envato vérifiés de l’acheteur à la vue du ticket côté agent. Les deux paramètres ci-dessous se trouvent sous Admin → HelpDesk → Paramètres → Intégration Licenses.

Restriction par département

Lorsque l’add-on Licenses est actif et que licenses_helpdesk_require_purchase est activé :

• Le formulaire de création de ticket filtre la liste des départements pour n’afficher que ceux pour lesquels l’utilisateur détient une licence active.
• L’accès est déterminé par LicensesAccessService::getAccessibleEntityIds() en utilisant le type lié HelpdeskDepartment, et le department_id soumis est revérifié côté serveur afin qu’une requête forgée à la main ne puisse pas contourner la liste déroulante.
• Les départements sans produit lié restent sans restriction.

Restriction par collection KB

Lorsque licenses_kb_restrict_by_purchase est activé :

• Les pages d’articles vérifient si la collection de l’article a des produits liés (type lié HelpdeskKbCollection).
• Les visiteurs sans licence correspondante sont envoyés vers leur page de licences, où ils peuvent enregistrer une clé manquante.
• Les utilisateurs non authentifiés sont redirigés vers la page de connexion.

Contexte du détail du ticket

La page de détail du ticket côté admin affiche les achats Envato vérifiés du client dans un panneau latéral (si l’utilisateur a un compte lié), donnant aux agents un contexte immédiat sur les produits que le client possède.

Notifications

L’add-on envoie quatre types de notifications par e-mail :

Notification	Destinataire	Déclencheur	Paramètre
NewTicketAdminNotification	Tous les administrateurs	Nouveau ticket créé	notification_helpdesk_new_ticket_admin
TicketConfirmationNotification	Auteur du ticket	Nouveau ticket créé	notification_helpdesk_ticket_confirmation
NewReplyNotification	Auteur du ticket	Un administrateur publie une réponse (pas les notes internes)	notification_helpdesk_new_reply

Mise à jour

Il existe deux façons de mettre cet add-on à jour : via le panneau d’administration (recommandé) ou en remplaçant manuellement les fichiers.

Méthode 1 : Téléversement via le panneau d’administration (recommandé)

1. Téléchargez le dernier fichier .zip de cet add-on.
2. Allez dans Panneau d’administration → Add-ons et cliquez sur le bouton Téléverser.
3. Sélectionnez ou faites glisser le fichier .zip dans la zone de téléversement.
4. Une invite de confirmation affichera les numéros de version actuelle et nouvelle. Cliquez sur Remplacer pour continuer.
5. Allez dans Panneau d’administration → Mise à jour du système (/admin/update) pour appliquer les migrations de base de données en attente.

Méthode 2 : Remplacement manuel des fichiers

Étape 1 : Remplacer les fichiers

Remplacez le répertoire de l’add-on par la nouvelle version.

Étape 2 : Exécuter les migrations

php artisan migrate

Les migrations en attente ne s’exécutent qu’une seule fois : la commande peut être relancée sans risque.

Étape 3 : Vider les caches

php artisan config:clear
php artisan route:clear
php artisan view:clear

Étape 4 : Vérifier

Visitez HelpDesk → Tableau de bord et confirmez que les cartes de statistiques et les graphiques se chargent correctement. Vérifiez la page front-end de la Base de Connaissances pour confirmer que les articles sont affichés.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez HelpDesk & Knowledge Base et cliquez sur Désactiver.

• Ses routes, ses vues, ses entrées de menu d’administration et ses permissions cessent d’être enregistrées, et ses pages publiques ne répondent plus.
• Ses tables de base de données et toutes les données qu’elles contiennent sont conservées, et ses fichiers restent dans extensions/addons/helpdesk/. Rien n’est supprimé.
• Le code d’achat enregistré lors de l’activation est conservé lui aussi : réactiver l’add-on ne le redemande pas.
• La désactivation est refusée tant qu’un autre add-on actif dépend de celui-ci : désactivez d’abord cet add-on.

Cliquez sur Activer sur la même carte pour le rallumer. Les migrations en attente sont rejouées, les assets republiés, et l’add-on reprend exactement là où il s’était arrêté.

Suppression

La suppression est définitive et détruit les données de l’add-on. Le bouton Supprimer n’apparaît que sur un add-on désactivé : la suppression se fait donc toujours en deux temps :

1. Désactivez HelpDesk & Knowledge Base (voir Désinstallation).
2. Cliquez sur Supprimer sur sa carte et confirmez la demande.

Le panneau d’administration, en une seule passe :

• exécute le hook de désinstallation de l’add-on, s’il en fournit un, tant que son code est encore sur le disque ;
• révoque les permissions déclarées dans son addon.json ;
• annule ses migrations, ce qui supprime ses tables de base de données et toutes les lignes qu’elles contiennent, et purge ses entrées de la table migrations, afin qu’une réinstallation ultérieure reparte de zéro ;
• supprime ses assets publiés : public/addons/helpdesk/, public/vendor/helpdesk/ et storage/app/public/addons/helpdesk/ ;
• supprime le dossier de l’add-on extensions/addons/helpdesk/ ;
• supprime sa ligne dans la table addons (le code d’achat enregistré disparaît avec elle) et vide le cache de l’application.

La suppression est refusée, avec un message explicatif et avant toute destruction, lorsque l’add-on est encore actif, lorsqu’un autre add-on actif en dépend, ou lorsque l’utilisateur du serveur web (PHP) ne peut pas supprimer extensions/addons/helpdesk/. Dans ce dernier cas, donnez à cet utilisateur le droit d’écriture sur le dossier et sur son parent, puis réessayez.

Supprimer le dossier en FTP ou en SSH n’est pas équivalent : les tables de l’add-on, ses entrées dans la table migrations et sa ligne addons restent en place, et sa carte reste dans la liste. Utilisez plutôt Supprimer dans le panneau d’administration.

Dépannage

Le formulaire de création de ticket n’affiche aucun département

• Assurez-vous qu’au moins un département existe et est marqué comme actif.
• Si l’add-on Licenses est actif avec licenses_helpdesk_require_purchase activé, l’utilisateur doit détenir une clé de licence active pour un produit lié à ce département.

Les utilisateurs invités ne peuvent pas soumettre de tickets

• Vérifiez que helpdesk_guest_access est défini à true dans les paramètres.
• Le paramètre est par défaut à true mais peut avoir été désactivé dans le panneau d’administration.

Les champs personnalisés n’apparaissent pas sur le formulaire de ticket

• Assurez-vous que le champ personnalisé est marqué comme actif.
• Vérifiez que le type du champ est défini correctement.
• Pour les champs select/checkbox/radio, assurez-vous que le tableau options est rempli.

Les notifications ne sont pas envoyées

• Vérifiez que l’interrupteur principal notifications_enabled et le type de notification correspondant (par ex. notification_helpdesk_new_ticket_admin) sont activés sous Admin → Paramètres → Notifications, et que le destinataire ne s’est pas désabonné dans ses propres préférences de notification.
• Vérifiez que votre configuration mail dans .env (SMTP, Mailgun, etc.) est correcte.
• Vérifiez la table failed_jobs pour les échecs de notifications en file d’attente.
• Pour les tickets invités, assurez-vous que l’adresse e-mail de l’invité est valide.

L’assistant IA retourne des erreurs

• Assurez-vous qu’au moins une clé API de fournisseur IA est configurée dans .env (par ex. ANTHROPIC_API_KEY, OPENAI_API_KEY).
• Vérifiez config/ai.php pour la configuration du fournisseur par défaut.
• Vérifiez que le package laravel/ai est installé (composer show laravel/ai).
• Vérifiez les journaux du serveur pour les messages d’erreur détaillés du fournisseur IA.

Les articles KB ne s’affichent pas sur le front-end

• Assurez-vous que les articles ont le statut défini à published et que published_at est dans le passé.
• Vérifiez la visibilité : les articles auth_only sont cachés pour les invités.
• Si kb_require_auth est activé, les utilisateurs non authentifiés sont redirigés vers la connexion (sauf sur les articles always_public).
• Assurez-vous que la collection de l’article est marquée comme active.

L’export PDF échoue

• Assurez-vous que le package barryvdh/laravel-dompdf est installé.
• Vérifiez que le répertoire storage/app est accessible en écriture par le serveur web.
• Si le contenu du ticket contient des images externes, assurez-vous que isRemoteEnabled est à true (c’est le cas par défaut).

La fusion de tickets échoue

• Vous ne pouvez pas fusionner un ticket avec lui-même : la source et la cible doivent être des tickets différents.
• Assurez-vous d’avoir la permission helpdesk.tickets.edit.
• Vérifiez les journaux du serveur pour les erreurs de transaction de base de données.

Les votes d’utilité ne fonctionnent pas

• Assurez-vous que kb_show_helpful_votes est activé dans les paramètres KB.
• Le point de terminaison de vote (POST /support/vote/{id}) retourne du JSON : vérifiez que le JavaScript gère correctement l’appel AJAX.
• Vérifiez la console du navigateur pour les erreurs réseau.

Le webhook entrant renvoie Fetched 0 alors que la boîte contient des messages

• Les interrogations normales ne récupèrent que les messages non lus. Les réponses déjà lues (par exemple celles que vous avez ouvertes au préalable dans un client de messagerie) sont ignorées par conception.
• Pour importer l’historique déjà lu, ajoutez ?backfill=1 à l’URL du webhook ou lancez php artisan helpdesk:fetch-inbound --backfill. Les doublons sont bloqués automatiquement grâce au hash du corps brut.

Le webhook entrant renvoie 404

• Le jeton doit être la valeur complète de helpdesk_fetch_inbound_token (32 caractères alphanumériques minimum). Régénérez-le depuis les paramètres du Pont Email s’il a fuité.
• Les jetons sont comparés avec hash_equals() : même un espace en fin provoque un échec.

Les réponses ingérées ont un horodatage incorrect (toutes regroupées à l’heure de l’import)

• Le pipeline d’ingestion utilise l’en-tête Date: de chaque message comme created_at. Ce correctif requiert la v1.0.5 ou supérieure : les imports plus anciens conservent l’heure d’ingestion.
• Pour réimporter un fil concerné : supprimez les réponses mal horodatées du ticket et relancez un backfill avec php artisan helpdesk:fetch-inbound --backfill.

La connexion IMAP échoue sans cesse avec “Connection refused”

• Certains hébergeurs (OVH notamment) gardent la session précédente ouverte quelques secondes. Augmentez helpdesk_imap_connect_retries (par ex. 2 ou 3) et helpdesk_imap_connect_backoff_seconds (par ex. 5) dans les paramètres du Pont Email.
• Sur les hébergements où la CLI ne peut pas ouvrir du tout le port 993, utilisez le webhook entrant piloté par un ordonnanceur externe.

La restriction d’accès par licence ne fonctionne pas

• Assurez-vous que l’add-on Licenses est installé et actif.
• Activez licenses_helpdesk_require_purchase (ou licenses_kb_restrict_by_purchase pour la Base de Connaissances) sous Admin → HelpDesk → Paramètres → Intégration Licenses.
• Liez au moins un produit au département ou à la collection KB que vous souhaitez restreindre. Les entités sans produit lié sont toujours sans restriction.