Ferndesk

Conversations de l’assistant

Obtenir la transcription d’une conversation

Renvoie une conversation avec sa transcription en texte brut et les articles auxquels elle fait référence.

La transcription contient uniquement le texte de l’utilisateur et de l’assistant : les appels d’outils, le raisonnement, les barrières de métadonnées internes, les brouillons d’escalade et le sentiment ne sont jamais exposés. Nécessite le scope conversations:read.

Scope requis : conversations:read

GET /assistant/conversations/{id}

Obtenir la transcription d’une conversation

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
}

Transcription de conversation

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 des scopes suivants (chaque endpoint indique le scope requis 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 (rendre les modifications visibles)
    • 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

    L’attribution de content:write ou content:publish implique content:read. Les clés créées avant la mise en place des scopes ont des scopes null = accès total (mode hérité).

Path Parameters

  • id string requis

    ID de ressource de l’entité demandée. Exemple: art_01JXY9AZK4KV

Response

application/json
  • 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ébut de la conversation, si elle a été enregistrée.

  • user anyOf

    Utilisateur du centre d’aide identifié 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

          ID 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é d’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

    Retour de l’utilisateur final par pouce sur la conversation, ou null si aucun retour n’a été laissé.

  • escalated boolean

    Indique si la conversation a été transférée à un humain.

  • messageCount integer

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

  • transcript[] object array

    Transcription en texte brut. Tours de l’utilisateur et de l’assistant uniquement ; les appels d’outils, le raisonnement, les métadonnées internes et les tours vides sont exclus. Tour de transcription d’une conversation.

    + Show Child Attributes
    • role string enum enum

      Allowed values: user, assistant.

    • text string

      Contenu du message en texte brut (barrières de métadonnées supprimées, appels d’outils et raisonnement exclus).

  • references[] object array

    Articles cités par l’assistant au cours de la conversation. Article auquel l’assistant a fait référence dans la conversation.

    + Show Child Attributes
    • articleId string

      ID d’article Ferndesk (art_...).

    • title string

      Titre de l’article au moment de la référence (utilise le titre actuel par défaut).