Guide du module HelpDesk

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_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_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

Paramètre	Description	Par défaut
helpdesk_notify_admin_on_new_ticket	Envoyer une notification par e-mail à tous les administrateurs lorsqu’un nouveau ticket est créé.	true
helpdesk_notify_author_on_new_ticket	Envoyer un e-mail de confirmation à l’auteur du ticket après la soumission.	true
helpdesk_notify_author_on_new_reply	Notifier l’auteur du ticket lorsqu’un administrateur publie une réponse (les notes internes sont exclues).	true

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.	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

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

Tableau des tickets

Sous les cartes de statistiques, un tableau paginé et filtrable de tous les tickets affichant la référence, le sujet, le département, le badge de statut, le badge de priorité, le nom du demandeur et la date de dernière activité. Les filtres incluent le statut, la priorité, le département et la recherche en texte libre (recherche dans la référence, le sujet, le nom de l’invité et l’e-mail de l’invité).

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 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 et la recherche.

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 fermés/résolus ne sont pas mis à jour automatiquement

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 : 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 (via parent_id).
• 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.
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) 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
• 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.

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_bridge_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_bridge_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_bridge_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_bridge_plus_addressing_prefix	Partie locale utilisée lorsque plus_addressing est actif (par ex. support).	support
helpdesk_email_bridge_subject_tag_format	Format de la balise pour la corrélation subject_tag. Doit contenir le placeholder :ref.	[#:ref]
helpdesk_email_bridge_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}/help/tickets/new	helpdesk.create.localized	Invité*	Formulaire de création de ticket
POST	/{locale}/help/tickets	helpdesk.store.localized	Invité*	Soumettre un nouveau ticket
GET	/{locale}/help/tickets/confirmation/{reference}	helpdesk.confirmation.localized	Invité*	Page de confirmation du ticket
GET	/{locale}/help/tickets	helpdesk.tickets.localized	Oui	Liste de mes tickets
GET	/{locale}/help/tickets/{reference}	helpdesk.show.localized	Oui	Voir le détail du ticket & la conversation
POST	/{locale}/help/tickets/{reference}/reply	helpdesk.reply.localized	Oui	Publier une réponse client
POST	/{locale}/help/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-00001, généré automatiquement par le TicketObserver lors de la création. Les références sont séquentielles et complétées par des zéros sur 5 chiffres.

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 nouvelles réponses

Front-end : Base de Connaissances

Routes

Méthode	URL	Nom de route	Description
GET	/{locale}/help	kb.index.localized	Accueil KB : collections, articles populaires & récents, recherche
GET	/{locale}/help/{slug}	kb.collection.localized	Page de collection : articles de la collection + collections enfants
GET	/{locale}/help/article/{slug}	kb.show.localized	Page d’article : contenu complet + articles connexes + vote
POST	/{locale}/help/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 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

Intégration de l’add-on Envato

Lorsque l’add-on Intégration Envato Market est actif, le HelpDesk s’intègre avec celui-ci pour le contrôle d’accès basé sur les achats.

Restriction par département

Lorsque envato_helpdesk_require_purchase est activé :

• Le formulaire de création de ticket filtre la liste des départements pour n’afficher que ceux auxquels l’utilisateur a accès par achat.
• L’accès est déterminé par EnvatoPurchaseValidator::getAccessibleEntityIds() en utilisant helpdesk_department comme type lié.
• Les départements sans éléments Envato liés restent sans restriction.

Restriction par collection KB

Lorsque envato_kb_restrict_by_purchase est activé :

• Les pages d’articles vérifient si la collection de l’article a des éléments Envato liés.
• Les non-acheteurs voient une page “Achat requis” avec la liste des éléments requis.
• 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 trois types de notifications par e-mail :

Notification	Destinataire	Déclencheur	Paramètre
NewTicketAdminNotification	Tous les administrateurs	Nouveau ticket créé	helpdesk_notify_admin_on_new_ticket
TicketConfirmationNotification	Auteur du ticket	Nouveau ticket créé	helpdesk_notify_author_on_new_ticket
NewReplyNotification	Auteur du ticket	Un administrateur publie une réponse (pas les notes internes)	helpdesk_notify_author_on_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 la liste des tickets se charge 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 Envato est actif avec envato_helpdesk_require_purchase activé, l’utilisateur doit avoir un achat vérifié 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 le paramètre de notification correspondant est activé (par ex. helpdesk_notify_admin_on_new_ticket).
• 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.
• 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 /help/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 achat Envato ne fonctionne pas

• Assurez-vous que l’add-on Intégration Envato Market est installé et actif.
• Activez envato_helpdesk_require_purchase dans les paramètres Envato.
• Liez au moins un élément Envato au département ou à la collection KB que vous souhaitez restreindre. Les entités sans éléments liés sont toujours sans restriction.