Ferndesk

Assistentenkonversationen

Assistentenkonversationen auflisten

Gibt KI-Assistentenkonversationen zurück, zuerst die neuesten, mit Cursor-Paginierung sowie feedback-, coverage- und Datumsfiltern.

Wenn ein feedback- oder coverage-Filter aktiv ist, werden Treffer über die zugrunde liegenden Fenster hinweg gesammelt, sodass eine Seite nie durch herausgefilterte Zeilen verkürzt wird. Um eine einzelne Anfrage zu begrenzen, werden höchstens 10 Fenster durchsucht. Wird diese Grenze erreicht, bevor eine vollständige Seite zusammengestellt ist, ist has_more auf true gesetzt und next_cursor setzt die Suche an der Stelle fort, an der sie angehalten wurde. Wenn dem Cursor gefolgt wird, wird die Suche ohne Überspringen von Treffern fortgesetzt.

Die Antwortfelder sind ein bewusst definierter öffentlicher Vertrag: Interne Metadaten, Referenzen und Rohstrukturen von Nachrichten werden niemals in der Listenstruktur enthalten sein. Erfordert den Scope conversations:read.

Erforderlicher Scope: conversations:read

GET /assistant/conversations

Assistentenkonversationen auflisten

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

Cursor-paginierte Konversationen

Authorizations

  • Authorization string erforderlich header

    Alle Anfragen erfordern ein Bearer-Token im Authorization-Header. API-Schlüssel tragen das Präfix fdsk_ und sollten geheim gehalten werden. Schlüssel können über die Seite Developer settings 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: Hilfeartikel, 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, Veröffentlichung aufheben, wiederherstellen und in den Papierkorb verschieben (Änderungen live schalten)
    • analytics:read: Berichte, Analysen und Artikel-Feedback des Helpcenters lesen
    • conversations:read: KI-Assistentenkonversationen und Transkripte lesen
    • webhooks:manage: Ausgehende Webhook-Abonnements erstellen und verwalten

    Die Vergabe von content:write oder content:publish schließt content:read ein. Vor der Einführung von Scopes erstellte Schlüssel haben null Scopes = vollständiger Zugriff (Legacy-Modus).

Query Parameters

  • coverage string enum
  • end_date string

    Obere ISO-Datumsgrenze.

  • feedback string enum
  • page_size integer

    Anzahl der pro Seite zurückzugebenden Elemente (1–100). Beispiel: 20

  • start_cursor string

    Intransparenter Paginierungs-Cursor. Übergeben Sie den next_cursor aus einer vorherigen Antwort, um die nächste Seite abzurufen. Beispiel: eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ

  • start_date string

    Untere ISO-Datumsgrenze.

Response

application/json
  • results[] object array

    Elemente auf dieser Seite. Zusammenfassung der Assistentenkonversation — ein bewusst definierter öffentlicher Vertrag, nicht die Rohzeile.

    + Show Child Attributes
    • id string
    • createdAt string

      ISO-8601-Zeitstempel in UTC.

    • updatedAt string

      ISO-8601-Zeitstempel in UTC.

    • status string

      Status im Lebenszyklus der Konversation.

    • source string enum | null

      Ursprung der Konversation: das Helpcenter (help) oder das eingebettete Widget (widget).

    • pageUrl string | null

      Die Seite, auf der sich der Endbenutzer beim Start der Konversation befand, sofern erfasst.

    • user anyOf

      Der identifizierte Helpcenter-Benutzer für diese Konversation 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 Helpcenter-Benutzer-ID (hcusr_...).

          • name string | null

            Anzeigename des Helpcenter-Benutzers.

        • option 2 null
    • summary string | null

      Von der KI generierte einzeilige Zusammenfassung, sofern verfügbar.

    • coverage string enum | null

      Wie gut das Helpcenter die Frage abgedeckt hat.

    • feedback string enum | null

      Daumen-Feedback des Endbenutzers zur Konversation oder null, wenn kein Feedback hinterlassen wurde.

    • escalated boolean

      Gibt an, ob die Konversation an einen Menschen eskaliert wurde.

    • messageCount integer

      Anzahl der Nachrichten des Endbenutzers in der Konversation.

  • has_more boolean

    Gibt an, ob nach dieser Seite weitere Elemente verfügbar sind.

  • next_cursor string | null

    Cursor, der als start_cursor für die nächste Seite übergeben wird, oder null auf der letzten Seite.