Helpdesk & base de connaissances

Le helpdesk a deux volets : une base de connaissances gérée avec le router tRPC helpdeskKb, et des tickets construits sur les conversations de la boîte de réception unifiée. Les deux sont accessibles dans la console, à /manage/helpdesk.

Le router helpdeskKb

Les articles de la base de connaissances et leurs catégories se gèrent avec le router helpdeskKb de l'API Plateforme, appelé à /api/trpc/helpdeskKb.<procedure> selon les conventions tRPC :

Procédure Type Entrée Permission
getArticles query filtres (facultatifs) helpdesk:read
getArticleById query { id } helpdesk:read
createArticle mutation champs de l'article helpdesk:write
updateArticle mutation { id, ...champs } helpdesk:write
deleteArticle mutation { id } helpdesk:write
getCategories query aucune helpdesk:read
getCategoryById query { id } helpdesk:read
createCategory mutation champs de la catégorie helpdesk:write
updateCategory mutation { id, ...champs } helpdesk:write
deleteCategory mutation { id } helpdesk:write

Toutes les procédures travaillent sur les données de l'espace de l'utilisateur authentifié. Les identifiants sont des UUID.

Articles

Champs acceptés par createArticle (seul title est obligatoire) :

Champ Type Défaut
title string, non vide
slug string dérivé du titre
excerpt string null
body string null
status string : draft ou published draft
visibility string : internal ou public internal
categoryId string ou null null
tags string[] []
seoTitle string null
seoDescription string null
order entier 0

Le slug est normalisé (minuscules, accents retirés, caractères non alphanumériques remplacés par -, 120 caractères au plus), qu'il soit fourni ou dérivé du titre. Il doit être unique dans le site.

updateArticle prend un objet à plat : id plus les champs à modifier, tous facultatifs, ainsi que archived (booléen) pour archiver ou désarchiver un article.

getArticles accepte ces filtres, tous facultatifs :

Filtre Type Effet
search string Recherche sans casse dans le titre, l'extrait et le corps.
status string Filtre sur le statut.
visibility string Filtre sur la visibilité.
categoryId string Filtre sur la catégorie.
includeArchived boolean Inclut les articles archivés (défaut false).

La liste est triée par order croissant, puis par date de modification décroissante. Chaque élément contient id, title, slug, excerpt, status, visibility, categoryId, tags, order, updatedAt et category ({ id, name }). getArticleById, les mutations de création et de mise à jour, et deleteArticle renvoient l'article complet : ces champs plus body, seoTitle, seoDescription, archived, createdAt et les compteurs de votes helpfulYes / helpfulNo.

Publier un brouillon :

curl -X POST "https://manage.inklura.fr/api/trpc/helpdeskKb.updateArticle" \
  -H "Authorization: Bearer $INKLURA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"id":"<article-id>","status":"published","visibility":"public"}}'

Lister les articles publiés d'une catégorie :

curl -G "https://manage.inklura.fr/api/trpc/helpdeskKb.getArticles" \
  -H "Authorization: Bearer $INKLURA_TOKEN" \
  --data-urlencode 'input={"json":{"status":"published","categoryId":"<category-id>"}}'

Catégories

Champs acceptés par createCategory (seul name est obligatoire) :

Champ Type Défaut
name string, non vide
slug string dérivé du nom
description string null
icon string null
parentId string ou null null (catégorie racine)
order entier 0

Le slug suit les mêmes règles que pour les articles. updateCategory prend lui aussi un objet à plat (id plus les champs à modifier, et archived).

getCategories renvoie les catégories non archivées, triées par order, avec id, name, slug, description, icon, parentId et order. getCategoryById ajoute archived, createdAt et updatedAt.

Supprimer une catégorie ne supprime pas son contenu : ses articles passent à categoryId: null et ses sous-catégories à parentId: null.

Erreurs

Code Cas
UNAUTHORIZED Pas de session valide.
FORBIDDEN La session n'a pas la permission helpdesk:read ou helpdesk:write.
BAD_REQUEST Entrée invalide (par exemple title ou name vide, id absent).
NOT_FOUND getArticleById ou getCategoryById avec un identifiant inconnu dans l'espace.
INTERNAL_SERVER_ERROR Échec d'écriture, notamment un slug déjà pris dans le site, ou une mise à jour ou suppression sur un identifiant inconnu.
Astuce

Pour modéliser votre propre domaine relationnel (articles et catégories, par exemple) dans une application construite sur le framework, voir Entités.

Tickets

Un ticket est une conversation de la boîte de réception unifiée à laquelle s'ajoutent les champs du helpdesk :

  • priorité (low, normal, high, urgent ; normal par défaut)
  • tags
  • SLA (échéances de première réponse et de résolution)
  • résolution (solved ou closed)
  • satisfaction client (CSAT : une note et un commentaire)

La console les affiche à /manage/helpdesk/tickets (page d'arrivée de /manage/helpdesk), à côté de la base de connaissances (/manage/helpdesk/knowledge-base). Les messages d'un ticket passent par la boîte de réception comme n'importe quelle conversation ; le helpdesk ajoute les informations de suivi. Ces champs se modifient dans la console : le router helpdeskKb ne couvre que la base de connaissances.

Voir aussi