Cartes client
Une carte client affiche, à côté de chaque conversation Support, des données issues de vos propres systèmes, comme le forfait d’un client, son usage ou ses commandes. Une carte correspond à un point de terminaison HTTPS sur votre serveur : Ferndesk l’appelle avec le client, votre point de terminaison répond avec la carte au format JSON, et Ferndesk l’affiche. Vous choisissez ce que la carte montre, et Ferndesk décide de son apparence. Ce que votre équipe voit est décrit dans Travailler dans la boîte de réception.
Nécessite Support. Les owners et admins ajoutent des cartes.
Ajouter une carte
Un owner ou un admin ajoute la carte dans Ferndesk avec une clé, l’URL de votre point de terminaison et un secret que vous choisissez. Un workspace peut avoir jusqu’à 25 cartes.
L’URL doit utiliser HTTPS et résoudre 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 carte est laquelle.Avant que Ferndesk enregistre une nouvelle carte, une nouvelle URL ou un nouveau secret, il appelle votre point de terminaison une fois. Si cet appel échoue (pas de réponse, un secret refusé, une clé manquante ou un corps que Ferndesk ne peut pas lire), la carte n’est pas enregistrée. Lorsqu’il n’y a pas de vrai client à interroger, l’appel utilise un client d’exemple (
[email protected], idc_example). Répondez-lui comme à toute autre requête, par exemple avec"components": null.
Quand Ferndesk appelle votre point de terminaison
Ferndesk appelle votre point de terminaison chaque fois qu’il a besoin de la carte, et ne conserve rien entre les appels :
lorsqu’un coéquipier ouvre une conversation et que son panneau client se charge,
lorsqu’un coéquipier ouvre une carte ou clique sur Actualiser,
lorsque votre agent IA lit le client pendant qu’il aide votre équipe avec un brouillon ou une note.
Ferndesk ne l’appelle pas pour un visiteur qui n’a fourni aucun e-mail, ni pour les conversations d’exemple avec lesquelles une nouvelle boîte de réception commence. Votre agent IA ne pose des questions que sur un client vérifié. Les cartes qui partagent un point de terminaison et un secret arrivent en un seul appel. Les appels vers différents points de terminaison s’exécutent en parallèle.
La requête
Ferndesk envoie un POST à l’URL de la carte 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é n’est envoyé qu’à l’hôte pour lequel vous l’avez enregistré. 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 | Ce que c’est |
|---|---|
| Toujours |
| Les clés des cartes que Ferndesk demande dans cet appel. |
| L’identifiant du client dans Ferndesk. |
| L’adresse e-mail du client. |
| L’identifiant issu 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. Agissez uniquement sur le client présent dans customer, et ne lisez pas le client depuis un autre champ.
Vérifier le secret
Comparez le jeton Bearer au secret que vous avez donné à Ferndesk, et refusez la requête s’il ne correspond 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 en moins de 15 secondes. Incluez une carte pour chaque clé dans 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 | Ce que cela fait |
|---|---|
| Facultatif. |
| Obligatoire. Une liste d’au plus 25 cartes. Une carte dont la clé n’a pas été demandée par Ferndesk est ignorée. |
| Obligatoire. L’une des clés de |
| Obligatoire. La carte, de haut en bas, jusqu’à 30 composants, en comptant les sections et les composants qu’elles contiennent. Envoyez |
| Facultatif. Une courte ligne récapitulative : |
| Facultatif. Jusqu’à 40 caractères. Affiché à la place du nom de la carte pour ce client. |
| Facultatif. Durée pendant laquelle la carte 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 carte. Ferndesk n’exécute pas encore les actions, donc le panneau ne les affiche pas. |
Les couleurs pour le texte, les lignes, les lignes de tableau, les éléments de timeline et status sont NORMAL, MUTED, SUCCESS, WARNING et ERROR. Les couleurs des badges sont GREY, GREEN, YELLOW, RED et BLUE.
Composants
Chaque composant est { "type": ..., ...fields }. Il existe douze types, au format des cartes client de Plain. Les limites sont exprimées en caractères sauf indication contraire.
Type | Obligatoire | Facultatif |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Par élément : |
|
| Par colonne : |
|
| Par élément : |
|
|
|
|
|
|
|
| Aucun |
|
| Aucun |
| Aucun. Il termine la section au-dessus de lui. | Aucun |
Chaque url commence par https:// ou http:// et peut contenir jusqu’à 2 000 caractères. Une carte comporte jusqu’à 6 boutons. Tout composant peut contenir safeForCustomer, et Ferndesk l’ignore : les cartes sont destinées à votre équipe. Votre agent IA ne les lit que pour aider votre équipe avec des brouillons et des notes, jamais pour les communiquer au client.
Ferndesk définit la mise en page. Il trace une ligne entre les sections. À l’intérieur de chaque section, il affiche d’abord les chiffres principaux (deux ou trois lignes stat consécutives partagent un même bandeau), puis les badges sur une ligne, puis le reste dans votre ordre, et les boutons sur une seule ligne à la fin. La rangée de boutons de chaque section affiche jusqu’à 3 boutons et place les autres sous Plus. Une liste, un tableau ou une timeline sans titre obtient sa propre section, et une longue section se replie.
Erreurs et limites
Une seule partie défaillante ne fait jamais échouer toute la carte. Lorsqu’un appel échoue, la carte affiche le problème à votre équipe. Si un rafraîchissement échoue, la carte conserve ce qu’elle affichait auparavant.
Ce qui se passe | Résultat |
|---|---|
Pas de connexion, ou l’adresse n’est pas publique | La carte indique que Ferndesk n’a pas pu se connecter. |
Pas de réponse en 15 secondes | La carte indique un délai dépassé. |
401 ou 403 | La carte 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 carte échoue. Ferndesk ne lit pas le corps. |
Un corps de plus de 64 Ko, ou qui n’est pas du JSON | Chaque carte de l’appel échoue. |
Pas de liste | Chaque carte de l’appel échoue. |
Une clé demandée par Ferndesk est manquante | Cette carte échoue. Les autres s’affichent. |
Un texte au-delà de sa limite | Il est tronqué et se termine par « … ». |
Trop d’éléments, de lignes, de composants ou de boutons | Les premiers jusqu’à la limite s’affichent. |
Un champ que Ferndesk ne connaît pas | Il est ignoré. |
Toute autre partie cassée | La plus petite partie qui contient le problème est supprimée (un élément, un champ ou le composant). Le reste de la carte s’affiche. |
La page de la carte dans Ferndesk affiche un aperçu de la réponse de votre point de terminaison, avec chaque problème et son chemin JSON, comme cards[0].components[3].text.
Timing et timeToLiveSeconds
Votre point de terminaison dispose de 15 secondes pour répondre à chaque appel. Ferndesk redemande à chaque fois qu’il a besoin de la carte, donc timeToLiveSeconds ne réduit pas la fréquence des appels. Il définit combien de temps une carte est considérée comme actuelle. Lorsqu’un coéquipier garde une carte ouverte au-delà de cette durée, ou après un rafraîchissement qui a échoué, la carte affiche quand elle a été mise à jour pour la dernière fois et un lien Actualiser.
Points de terminaison écrits pour Plain
Un point de terminaison écrit pour les cartes client de Plain fonctionne tel quel. La requête transporte thread à côté de conversation, et Ferndesk lit les formes de composants de Plain comme les siennes :
Composant Plain | Lu comme |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Ignoré. Ferndesk définit l’espacement. |