Kundenkarten
Eine Kundenkarte zeigt Daten aus Ihren eigenen Systemen neben jeder Support-Konversation an, zum Beispiel den Tarif, die Nutzung oder Bestellungen eines Kunden. Eine Karte ist ein einzelner HTTPS-Endpunkt auf Ihrem Server: Ferndesk ruft ihn mit dem Kunden auf, Ihr Endpunkt antwortet mit der Karte als JSON und Ferndesk stellt sie dar. Sie entscheiden, was die Karte zeigt, und Ferndesk bestimmt, wie sie aussieht. Was Ihr Team sieht, erfahren Sie unter Arbeit im Posteingang.
Support erforderlich. Inhaber und Administratoren können Karten hinzufügen.
Karte hinzufügen
Ein Inhaber oder Administrator fügt die Karte in Ferndesk mit einem Schlüssel, der URL Ihres Endpunkts und einem selbst gewählten Geheimnis hinzu. Ein Arbeitsbereich kann bis zu 25 Karten haben.
Die URL muss HTTPS verwenden und auf eine öffentliche Adresse verweisen.
Der Schlüssel darf bis zu 64 Buchstaben, Zahlen,
-und_enthalten. Ferndesk sendet ihn incardKeys, und Ihre Antwort verwendet ihn, um die jeweilige Karte zuzuordnen.Bevor Ferndesk eine neue Karte, eine neue URL oder ein neues Geheimnis speichert, ruft es Ihren Endpunkt einmal auf. Schlägt dieser Aufruf fehl (keine Antwort, ein abgelehntes Geheimnis, ein fehlender Schlüssel oder ein nicht lesbarer Inhalt), wird die Karte nicht gespeichert. Wenn es keinen echten Kunden gibt, zu dem eine Anfrage gestellt werden kann, wird für den Aufruf ein Beispielkunde verwendet (
[email protected], idc_example). Beantworten Sie die Anfrage wie jede andere, zum Beispiel mit"components": null.
Wenn Ferndesk Ihren Endpunkt aufruft
Ferndesk ruft Ihren Endpunkt jedes Mal auf, wenn es die Karte benötigt, und speichert zwischen den Aufrufen nichts:
wenn ein Teammitglied eine Konversation öffnet und das Kundenpanel geladen wird,
wenn ein Teammitglied eine Karte öffnet oder auf Aktualisieren klickt,
wenn Ihr KI-Agent den Kunden abruft, während er Ihrem Team bei einem Entwurf oder einer Notiz hilft.
Ferndesk ruft den Endpunkt nicht für Besucher auf, die keine E-Mail-Adresse angegeben haben, oder für Beispielkonversationen, mit denen ein neuer Posteingang startet. Ihr KI-Agent fragt nur Informationen zu einem verifizierten Kunden ab. Karten, die denselben Endpunkt und dasselbe Geheimnis verwenden, werden gemeinsam in einem Aufruf abgerufen. Aufrufe an verschiedene Endpunkte laufen parallel.
Die Anfrage
Ferndesk sendet einen POST-Aufruf an die URL der Karte und verwendet dabei drei Header: Authorization: Bearer <your secret>, Content-Type: application/json und Accept: application/json. Ferndesk folgt keinen Weiterleitungen, und Ihr gespeichertes Geheimnis wird nur an den Host gesendet, für den Sie es gespeichert haben. Der Inhalt:
{
"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
}
}Feld | Beschreibung |
|---|---|
| Immer |
| Die Schlüssel der Karten, die Ferndesk mit diesem Aufruf abfragt. |
| Die Kunden-ID in Ferndesk. |
| Die E-Mail-Adresse des Kunden. |
| Die ID aus Ihrem eigenen Anmeldesystem, wenn sich der Kunde in Ihrem Hilfe-Center oder Widget angemeldet hat; andernfalls |
| Die ID der Konversation in Ferndesk. |
| Vorläufig immer |
| Eine Kopie von |
Ferndesk legt den Kunden fest. Ihr KI-Agent wählt ihn niemals aus. Verwenden Sie ausschließlich den Kunden in customer und lesen Sie keinen Kunden aus einem anderen Feld aus.
Geheimnis überprüfen
Vergleichen Sie das Bearer-Token mit dem Geheimnis, das Sie Ferndesk mitgeteilt haben, und lehnen Sie die Anfrage ab, wenn die Werte nicht übereinstimmen.
// 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
}))
});
});Die Antwort
Antworten Sie innerhalb von 15 Sekunden mit Status 200 und einem JSON-Inhalt. Fügen Sie für jeden Schlüssel in cardKeys eine Karte hinzu.
{
"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" }
]
}]
}Feld | Beschreibung |
|---|---|
| Optional. |
| Erforderlich. Eine Liste mit bis zu 25 Karten. Eine Karte mit einem Schlüssel, den Ferndesk nicht angefragt hat, wird ignoriert. |
| Erforderlich. Einer der Schlüssel in |
| Erforderlich. Die Karte, von oben nach unten, mit bis zu 30 Komponenten, einschließlich Abschnitten und der darin enthaltenen Komponenten. Senden Sie |
| Optional. Eine kurze Zusammenfassung: |
| Optional. Bis zu 40 Zeichen. Wird für diesen Kunden anstelle des Kartennamens angezeigt. |
| Optional. Wie lange die Karte als aktuell gilt, von 0 bis 31.536.000 Sekunden. Der Standardwert ist 300 (5 Minuten). |
| Optional. Die Aktionen der Karte. Ferndesk führt Aktionen noch nicht aus, daher zeigt das Panel sie nicht an. |
Die Farben für Text, Zeilen, Tabellenzeilen, Timeline-Einträge und status sind NORMAL, MUTED, SUCCESS, WARNING und ERROR. Die Badge-Farben sind GREY, GREEN, YELLOW, RED und BLUE.
Komponenten
Jede Komponente hat das Format { "type": ..., ...fields }. Es gibt zwölf Typen im Format der Kundenkarten von Plain. Längenbegrenzungen gelten für Zeichen, sofern nichts anderes angegeben ist.
Typ | Erforderlich | Optional |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Pro Eintrag: |
|
| Pro Spalte: |
|
| Pro Eintrag: |
|
|
|
|
|
|
|
| Keine |
|
| Keine |
| Keine. Beendet den darüberliegenden Abschnitt. | Keine |
Jede url beginnt mit https:// oder http:// und darf bis zu 2.000 Zeichen lang sein. Eine Karte kann bis zu 6 Schaltflächen enthalten. Jede Komponente kann safeForCustomer enthalten; Ferndesk ignoriert dieses Feld, denn Karten sind für Ihr Team bestimmt. Ihr KI-Agent liest sie nur, um Ihrem Team bei Entwürfen und Notizen zu helfen, und gibt dem Kunden niemals Informationen daraus weiter.
Ferndesk legt das Layout fest. Zwischen Abschnitten wird eine Linie angezeigt. Innerhalb jedes Abschnitts erscheinen zuerst die Kennzahlen (zwei oder drei stat-Zeilen hintereinander werden in einem Streifen angezeigt), dann die Badges in einer Zeile, anschließend die übrigen Elemente in der von Ihnen festgelegten Reihenfolge und am Ende die Schaltflächen in einer Zeile. Die Schaltflächenzeile jedes Abschnitts zeigt bis zu 3 Schaltflächen; weitere befinden sich unter Mehr. Eine Liste, Tabelle oder Timeline ohne Überschrift erhält einen eigenen Abschnitt, und lange Abschnitte werden eingeklappt.
Fehler und Begrenzungen
Ein fehlerhafter Teil lässt niemals die gesamte Karte scheitern. Schlägt ein Aufruf fehl, zeigt die Karte Ihrem Team das Problem an. Schlägt eine Aktualisierung fehl, behält die Karte ihre vorherige Anzeige bei.
Ergebnis | Auswirkung |
|---|---|
Keine Verbindung oder die Adresse ist nicht öffentlich | Die Karte zeigt an, dass Ferndesk keine Verbindung herstellen konnte. |
Keine Antwort innerhalb von 15 Sekunden | Die Karte zeigt an, dass eine Zeitüberschreitung aufgetreten ist. |
401 oder 403 | Die Karte zeigt an, dass Ihr Endpunkt die Anfrage abgelehnt hat. Überprüfen Sie das Geheimnis. |
Ein anderer Status als 200, einschließlich einer Weiterleitung | Die Karte schlägt fehl. Ferndesk liest den Inhalt nicht aus. |
Ein Inhalt mit mehr als 64 KB oder kein JSON | Alle Karten in diesem Aufruf schlagen fehl. |
Keine | Alle Karten in diesem Aufruf schlagen fehl. |
Ein von Ferndesk angefragter Schlüssel fehlt | Diese Karte schlägt fehl. Die anderen werden angezeigt. |
Ein Text überschreitet die Begrenzung | Er wird abgeschnitten und endet mit „…“. |
Zu viele Einträge, Zeilen, Komponenten oder Schaltflächen | Die ersten Elemente bis zur Begrenzung werden angezeigt. |
Ein Feld, das Ferndesk nicht kennt | Es wird ignoriert. |
Ein anderer fehlerhafter Teil | Der kleinste Teil, der das Problem enthält, wird verworfen (ein Eintrag, ein Feld oder die Komponente). Der Rest der Karte wird angezeigt. |
Auf der Kartenseite in Ferndesk sehen Sie eine Vorschau der Antwort Ihres Endpunkts mit den einzelnen Problemen und ihrem JSON-Pfad, zum Beispiel cards[0].components[3].text.
Zeitangaben und timeToLiveSeconds
Ihr Endpunkt hat 15 Sekunden Zeit, um auf jeden Aufruf zu antworten. Ferndesk fragt die Karte jedes Mal erneut ab, wenn sie benötigt wird. timeToLiveSeconds verringert also nicht die Häufigkeit der Aufrufe. Der Wert legt fest, wie lange eine Karte als aktuell gilt. Ist eine Karte bei einem Teammitglied länger als diesen Zeitraum geöffnet oder ist eine Aktualisierung fehlgeschlagen, zeigt die Karte an, wann sie zuletzt aktualisiert wurde, sowie einen Link Aktualisieren.
Endpunkte für Plain
Ein Endpunkt, der für Kundenkarten von Plain geschrieben wurde, funktioniert unverändert. Die Anfrage enthält thread neben conversation, und Ferndesk liest die Komponentenformate von Plain wie die eigenen aus:
Plain-Komponente | Wird gelesen als |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Wird ignoriert. Ferndesk legt die Abstände fest. |