Ferndesk

Assistentengespräche

Gesprächstranskript abrufen

Gibt ein Gespräch mit seinem Klartext-Transkript und den darin referenzierten Artikeln zurück.

Das Transkript enthält ausschließlich Benutzer-/Assistententext: Tool-Aufrufe, Überlegungen, interne Metadatenbegrenzungen, Eskalationsentwürfe und Sentiment werden niemals offengelegt. Erfordert den Scope conversations:read.

Erforderlicher Scope: conversations:read

GET /assistant/conversations/{id}

Gesprächstranskript abrufen

curl --request GET \
  --url 'https://api.ferndesk.com/v1/assistant/conversations/{ID}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "status": "<string>",
  "source": "help",
  "pageUrl": "<string>",
  "user": {
    "id": "<string>",
    "name": "<string>"
  },
  "summary": "<string>",
  "coverage": "covered",
  "feedback": "positive",
  "escalated": true,
  "messageCount": 1
}

Gesprächstranskript

Authorizations

  • Authorization string erforderlich header

    Alle Anfragen erfordern ein Bearer-Token im Authorization-Header. API-Schlüssel beginnen mit fdsk_ und sollten geheim gehalten werden. Schlüssel können über die Seite Entwicklereinstellungen erstellt und verwaltet werden.

    Schlüssel können auf eine beliebige Teilmenge dieser Scopes beschränkt werden (jeder Endpunkt führt den über x-required-scopes erforderlichen Scope auf):

    • content:read: Hilfecenter-Artikel, Sammlungen, Abschnitte und Übersetzungen lesen und durchsuchen
    • content:write: Artikelentwürfe, Benutzer und Aufgaben erstellen und bearbeiten; Artikel und Sammlungen verschieben
    • content:publish: Inhalte veröffentlichen, die Veröffentlichung aufheben, wiederherstellen und in den Papierkorb verschieben (Änderungen live schalten)
    • analytics:read: Hilfecenter-Berichte, Analysen und Artikel-Feedback lesen
    • conversations:read: AI-Assistentengespräche und Transkripte lesen
    • webhooks:manage: Ausgehende Webhook-Abonnements erstellen und verwalten

    Die Vergabe von content:write oder content:publish beinhaltet content:read. Vor der Einführung der Bereichsbeschränkung ausgestellte Schlüssel haben null Scopes = Vollzugriff (Legacy-Modus).

Path Parameters

  • id string erforderlich

    Ressourcen-ID der angeforderten Entität. Beispiel: art_01JXY9AZK4KV

Response

application/json
  • id string
  • createdAt string

    ISO-8601-Zeitstempel in UTC.

  • updatedAt string

    ISO-8601-Zeitstempel in UTC.

  • status string

    Lebenszyklusstatus des Gesprächs.

  • source string enum | null

    Ursprung des Gesprächs: das Hilfecenter (help) oder das eingebettete Widget (widget).

  • pageUrl string | null

    Die Seite, auf der sich der Endbenutzer beim Beginn des Gesprächs befand, sofern erfasst.

  • user anyOf

    Der für dieses Gespräch ermittelte Hilfecenter-Benutzer oder null, wenn der Endbenutzer anonym war.

    + Show Child Attributes
    • anyOf options 2 variants anyOf

      One or more options can apply.

      + Show Child Attributes
      • option 1 object
        + Show Child Attributes
        • id string

          Ferndesk-Hilfecenter-Benutzer-ID (hcusr_...).

        • name string | null

          Anzeigename des Hilfecenter-Benutzers.

      • option 2 null
  • summary string | null

    Von AI generierte einzeilige Zusammenfassung, sofern verfügbar.

  • coverage string enum | null

    Wie gut das Hilfecenter die Frage abgedeckt hat.

  • feedback string enum | null

    Daumen-Feedback des Endbenutzers zum Gespräch oder null, wenn kein Feedback hinterlassen wurde.

  • escalated boolean

    Gibt an, ob das Gespräch an einen Menschen eskaliert wurde.

  • messageCount integer

    Anzahl der Endbenutzernachrichten im Gespräch.

  • transcript[] object array

    Klartext-Transkript. Nur Benutzer- und Assistentenbeiträge; Tool-Aufrufe, Überlegungen, interne Metadaten und leere Beiträge sind ausgeschlossen. Ein Beitrag des Gesprächstranskripts.

    + Show Child Attributes
    • role string enum enum

      Allowed values: user, assistant.

    • text string

      Klartext-Nachrichteninhalt (Metadatenbegrenzungen entfernt, Tool-Aufrufe und Überlegungen entfernt).

  • references[] object array

    Artikel, die der Assistent im Gespräch zitiert hat. Ein Artikel, auf den der Assistent im Gespräch verwiesen hat.

    + Show Child Attributes
    • articleId string

      Ferndesk-Artikel-ID (art_...).

    • title string

      Artikeltitel zum Zeitpunkt der Referenz (fällt auf den aktuellen Titel zurück).