Fiches client
Une fiche client affiche des données issues de vos propres systèmes à côté de chaque conversation du Helpdesk, par exemple le forfait, l’utilisation ou les commandes d’un client. Une fiche correspond à un point de terminaison HTTPS sur votre serveur : Ferndesk l’appelle avec les informations du client, votre point de terminaison renvoie la fiche au format JSON, et Ferndesk l’affiche. Vous choisissez ce que la fiche affiche, et Ferndesk décide de son apparence. Découvrez ce que voit votre équipe dans Travailler dans la boîte de réception.
Nécessite Helpdesk. Les propriétaires et les administrateurs peuvent ajouter des fiches.
Ajouter une fiche
Un propriétaire ou un administrateur ajoute la fiche dans Ferndesk en indiquant une clé, l’URL de votre point de terminaison et un secret de son choix. Un espace de travail peut comporter jusqu’à 25 fiches.
L’URL doit utiliser HTTPS et pointer vers une adresse publique.
La clé peut contenir jusqu’à 64 lettres, chiffres,
-et_. Ferndesk l’envoie danscardKeys, et votre réponse l’utilise pour indiquer à quelle fiche elle correspond.Avant d’enregistrer une nouvelle fiche, une nouvelle URL ou un nouveau secret, Ferndesk appelle une fois votre point de terminaison. Si cet appel échoue (absence de réponse, secret refusé, clé manquante ou corps que Ferndesk ne peut pas lire), la fiche n’est pas enregistrée. S’il n’y a aucun vrai client à interroger, l’appel utilise un client d’exemple (
[email protected], idc_example). Répondez comme à toute autre requête, par exemple avec `
Lorsque Ferndesk appelle votre point de terminaison
Ferndesk appelle votre point de terminaison chaque fois qu’il a besoin de la fiche, et ne conserve rien d’un appel à l’autre :
lorsqu’un collègue ouvre une conversation et que le panneau client correspondant se charge,
lorsqu’un collègue ouvre une fiche ou clique sur Actualiser,
lorsque votre agent IA consulte le client pour aider votre équipe à rédiger un brouillon ou une note.
Ferndesk ne l’appelle pas pour un visiteur qui n’a pas fourni d’adresse e-mail, ni pour les conversations d’exemple incluses dans une nouvelle boîte de réception. Votre agent IA ne demande des informations que sur un client vérifié. Les fiches qui partagent un point de terminaison et un secret sont récupérées en un seul appel. Les appels vers différents points de terminaison sont exécutés en parallèle.
La requête
Ferndesk envoie une requête POST à l’URL de la fiche avec trois en-têtes : Authorization: Bearer <your secret>, Content-Type: application/json et Accept: application/json. Ferndesk ne suit pas les redirections, et votre secret enregistré est envoyé uniquement à l’hôte auquel il est destiné. Le corps :
{
"version": 1,
"cardKeys": ["plan"],
"customer": {
"id": "cust_01J9ZK4M2Q8T",
"email": "[email protected]",
"externalId": "usr_8842"
},
"conversation": {
"id": "conv_01J9ZK7R5W",
"externalId": null
},
"thread": {
"id": "conv_01J9ZK7R5W",
"externalId": null
}
}Champ | Description |
|---|---|
| Toujours |
| Les clés des fiches demandées par Ferndesk dans cet appel. |
| L’identifiant du client dans Ferndesk. |
| L’adresse e-mail du client. |
| L’identifiant provenant de votre propre système de connexion, lorsque le client s’est connecté à votre centre d’aide ou à votre widget ; sinon, |
| L’identifiant de la conversation dans Ferndesk. |
| Toujours |
| Une copie de |
Ferndesk définit le client. Votre agent IA ne le choisit jamais. N’agissez que sur le client indiqué dans customer et ne récupérez pas de client depuis un autre champ.
Vérifier le secret
Comparez le jeton Bearer au secret fourni à Ferndesk et refusez la requête s’ils ne correspondent pas.
// Express
app.post('/ferndesk/cards', express.json(), async (req, res) => {
const token = (req.get('authorization') || '').replace(/^Bearer /, '');
if (token !== process.env.FERNDESK_CARD_SECRET) {
return res.status(401).end();
}
const { cardKeys, customer } = req.body;
// findAccount is your own lookup, by your id or by email.
const account = await findAccount(customer.externalId ?? customer.email);
res.json({
version: 1,
cards: cardKeys.map((key) => ({
key,
components: account
? [{ type: 'row', label: 'Plan', value: account.plan }]
: null
}))
});
});La réponse
Répondez avec le statut 200 et un corps JSON dans les 15 secondes. Incluez une fiche pour chaque clé de cardKeys.
{
"version": 1,
"cards": [{
"key": "plan",
"status": { "text": "Pro, renews 3 Dec", "color": "SUCCESS" },
"timeToLiveSeconds": 600,
"components": [
{ "type": "row", "label": "Plan", "value": "Pro" },
{ "type": "progress", "label": "Seats", "value": 12, "max": 15 },
{ "type": "linkButton", "label": "Open in admin", "url": "https://admin.example.com/u/usr_8842" }
]
}]
}Champ | Fonction |
|---|---|
| Facultatif. |
| Obligatoire. Une liste contenant jusqu’à 25 fiches. Toute fiche dont la clé n’a pas été demandée par Ferndesk est ignorée. |
| Obligatoire. L’une des clés de |
| Obligatoire. La fiche, de haut en bas, avec jusqu’à 30 composants, y compris les sections et les composants qu’elles contiennent. Envoyez |
| Facultatif. Une courte ligne de résumé : |
| Facultatif. Jusqu’à 40 caractères. Affiché à la place du nom de la fiche pour ce client. |
| Facultatif. Durée pendant laquelle la fiche est considérée comme à jour, de 0 à 31 536 000 secondes. La valeur par défaut est 300 (5 minutes). |
| Facultatif. Les actions de la fiche. Ferndesk ne les exécute pas encore, donc le panneau ne les affiche pas. |
Les couleurs du texte, des lignes, des lignes de tableau, des éléments de chronologie et de status sont NORMAL, MUTED, SUCCESS, WARNING et ERROR. Les couleurs des badges sont GREY, GREEN, YELLOW, RED et BLUE.
Composants
Chaque composant est au format `{
Type | Obligatoire | Facultatif |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Pour chaque élément : |
|
| Pour chaque colonne : |
|
| Pour chaque élément : |
|
|
|
|
|
|
|
| Aucun |
|
| Aucun |
| Aucun. Termine la section située au-dessus. | Aucun |
Chaque url commence par https:// ou http:// et peut contenir jusqu’à 2 000 caractères. Une fiche peut comporter jusqu’à 6 boutons. Tout composant peut inclure safeForCustomer, mais Ferndesk l’ignore : les fiches sont destinées à votre équipe. Votre agent IA ne les consulte que pour aider votre équipe à rédiger des brouillons et des notes, jamais pour s’adresser au client.
Ferndesk définit la mise en page. Il trace une ligne entre les sections. Dans chaque section, il affiche d’abord les chiffres clés (deux ou trois lignes stat consécutives sont regroupées sur une même ligne), puis les badges sur une ligne, puis le reste dans l’ordre que vous avez indiqué, et enfin les boutons sur une ligne. La ligne de boutons de chaque section affiche jusqu’à 3 boutons et place les autres sous Plus. Une liste, un tableau ou une chronologie sans titre est placé dans sa propre section, et les sections longues sont repliées.
Erreurs et limites
Un élément incorrect n’entraîne jamais l’échec de toute la fiche. Lorsqu’un appel échoue, la fiche affiche le problème à votre équipe. Si une actualisation échoue, la fiche conserve son contenu précédent.
Résultat | Résultat |
|---|---|
Aucune connexion ou adresse non publique | La fiche indique que Ferndesk n’a pas pu se connecter. |
Aucune réponse en 15 secondes | La fiche indique que le délai d’attente a expiré. |
401 ou 403 | La fiche indique que votre point de terminaison a refusé la requête. Vérifiez le secret. |
Tout autre statut que 200, y compris une redirection | La fiche échoue. Ferndesk ne lit pas le corps. |
Corps de plus de 64 Ko ou contenu qui n’est pas au format JSON | Toutes les fiches de l’appel échouent. |
Aucune liste | Toutes les fiches de l’appel échouent. |
Clé demandée par Ferndesk manquante | Cette fiche échoue. Les autres s’affichent. |
Texte dépassant sa limite | Il est tronqué et se termine par « … ». |
Trop d’éléments, de lignes, de composants ou de boutons | Les premiers éléments, jusqu’à la limite, s’affichent. |
Champ inconnu de Ferndesk | Il est ignoré. |
Tout autre élément incorrect | Le plus petit élément contenant le problème est supprimé (un élément, un champ ou le composant). Le reste de la fiche s’affiche. |
La page de la fiche dans Ferndesk affiche un aperçu de la réponse de votre point de terminaison, avec chaque problème et son chemin JSON, par exemple cards[0].components[3].text.
Durée et timeToLiveSeconds
Votre point de terminaison dispose de 15 secondes pour répondre à chaque appel. Ferndesk effectue une nouvelle requête chaque fois qu’il a besoin de la fiche ; timeToLiveSeconds ne réduit donc pas la fréquence des appels. Ce paramètre définit la durée pendant laquelle une fiche est considérée comme à jour. Lorsqu’un collègue garde une fiche ouverte au-delà de cette durée, ou après l’échec d’une actualisation, la fiche indique la date de sa dernière mise à jour et affiche un lien Actualiser.
Points de terminaison conçus pour Plain
Un point de terminaison conçu pour les fiches client de Plain fonctionne tel quel. La requête inclut thread à côté de conversation, et Ferndesk interprète les formats de composants de Plain comme les siens :
Composant Plain | Interprété comme |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Ignoré. Ferndesk définit l’espacement. |