Ferndesk

Conversations de l’assistant

Lister les conversations de l’assistant

Renvoie les conversations de l’assistant IA, de la plus récente à la plus ancienne, paginées par curseur, avec des filtres feedback, coverage et de date.

Lorsqu’un filtre feedback ou coverage est actif, les correspondances sont collectées dans les fenêtres sous-jacentes afin qu’une page ne soit jamais raccourcie par des lignes filtrées. Pour qu’une seule requête reste limitée, l’analyse porte sur 10 fenêtres au maximum ; si cette limite est atteinte avant qu’une page complète soit collectée, has_more vaut true et next_cursor reprend à l’endroit où l’analyse s’est arrêtée. Le suivi du curseur poursuit donc l’analyse sans ignorer de correspondances.

Les champs de réponse constituent un contrat public délibéré : les métadonnées internes, les références et les structures brutes des messages ne sont jamais incluses dans la forme de liste. Requiert la portée conversations:read.

Portée requise : conversations:read

GET /assistant/conversations

Lister les conversations de l’assistant

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>"
}

Conversations paginées par curseur

Authorizations

  • Authorization string requis header

    Toutes les requêtes nécessitent un jeton Bearer dans l’en-tête Authorization. Les clés API sont préfixées par fdsk_ et doivent rester secrètes. Vous pouvez générer et gérer les clés depuis la page Paramètres développeur.

    Les clés peuvent être limitées à n’importe quel sous-ensemble de ces portées (chaque endpoint indique la portée requise via x-required-scopes) :

    • content:read : Lire et rechercher les articles, collections, sections et traductions du centre d’aide
    • content:write : Créer et modifier des brouillons d’articles, des utilisateurs et des tâches ; déplacer des articles et des collections
    • content:publish : Publier, dépublier, restaurer et mettre à la corbeille du contenu (appliquer les modifications)
    • analytics:read : Lire les rapports, analyses et retours sur les articles du centre d’aide
    • conversations:read : Lire les conversations et transcriptions de l’assistant IA
    • webhooks:manage : Créer et gérer les abonnements aux webhooks sortants

    Accorder content:write ou content:publish implique content:read. Les clés créées avant la mise en place des portées ont des portées nulles = accès complet (mode hérité).

Query Parameters

  • coverage string enum
  • end_date string

    Limite supérieure de date ISO.

  • feedback string enum
  • page_size integer

    Nombre d’éléments à renvoyer par page (1-100). Exemple: 20

  • start_cursor string

    Curseur de pagination opaque. Transmettez le next_cursor d’une réponse précédente pour récupérer la page suivante. Exemple: eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ

  • start_date string

    Limite inférieure de date ISO.

Response

application/json
  • results[] object array

    Éléments de cette page. Résumé de la conversation de l’assistant — un contrat public délibéré, et non la ligne brute.

    + Show Child Attributes
    • id string
    • createdAt string

      Horodatage ISO 8601 en UTC.

    • updatedAt string

      Horodatage ISO 8601 en UTC.

    • status string

      Statut du cycle de vie de la conversation.

    • source string enum | null

      Origine de la conversation : le centre d’aide (help) ou le widget intégré (widget).

    • pageUrl string | null

      Page sur laquelle se trouvait l’utilisateur final au démarrage de la conversation, si elle a été capturée.

    • user anyOf

      Utilisateur identifié du centre d’aide pour cette conversation, ou null lorsque l’utilisateur final était anonyme.

      + 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

            Identifiant de l’utilisateur du centre d’aide Ferndesk (hcusr_...).

          • name string | null

            Nom d’affichage de l’utilisateur du centre d’aide.

        • option 2 null
    • summary string | null

      Résumé en une ligne généré par l’IA, si disponible.

    • coverage string enum | null

      Degré auquel le centre d’aide a répondu à la question.

    • feedback string enum | null

      Évaluation par pouce de l’utilisateur final sur la conversation, ou null si aucune évaluation n’a été laissée.

    • escalated boolean

      Indique si la conversation a été transmise à un humain.

    • messageCount integer

      Nombre de messages de l’utilisateur final dans la conversation.

  • has_more boolean

    Indique si d’autres éléments sont disponibles après cette page.

  • next_cursor string | null

    Curseur à transmettre comme start_cursor pour la page suivante, ou null sur la dernière page.