Ferndesk

Conversaciones del asistente

Enumerar conversaciones del asistente

Devuelve las conversaciones del asistente de IA, de la más reciente a la más antigua, paginadas mediante cursor, con filtros de fecha, feedback y coverage.

Cuando hay un filtro de feedback o coverage activo, las coincidencias se recopilan en las ventanas subyacentes para que una página nunca tenga menos elementos debido a filas filtradas. Para mantener acotada una sola solicitud, se exploran como máximo 10 ventanas; si se alcanza ese límite antes de recopilar una página completa, has_more es true y next_cursor reanuda desde el punto donde se detuvo la exploración, de modo que al seguir el cursor la exploración continúa sin omitir coincidencias.

Los campos de respuesta son un contrato público deliberado: los metadatos internos, las referencias y las estructuras de mensajes sin procesar nunca se incluyen en la forma de lista. Requiere el alcance conversations:read.

Alcance requerido: conversations:read

GET /assistant/conversations

Enumerar conversaciones del asistente

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

Conversaciones paginadas mediante cursor

Authorizations

  • Authorization string obligatorio header

    Todas las solicitudes requieren un token Bearer en el encabezado Authorization. Las claves de API llevan el prefijo fdsk_ y deben mantenerse en secreto. Puedes generar y administrar claves desde la página de configuración para desarrolladores.

    Las claves pueden restringirse a cualquier subconjunto de estos alcances (cada endpoint indica el alcance que requiere mediante x-required-scopes):

    • content:read: Leer y buscar artículos, colecciones, secciones y traducciones del centro de ayuda
    • content:write: Crear y editar borradores de artículos, usuarios y tareas; mover artículos y colecciones
    • content:publish: Publicar, despublicar, restaurar y enviar contenido a la papelera (hacer que los cambios sean visibles)
    • analytics:read: Leer informes, análisis y comentarios de artículos del centro de ayuda
    • conversations:read: Leer conversaciones y transcripciones del asistente de IA
    • webhooks:manage: Crear y administrar suscripciones a webhooks salientes

    Conceder content:write o content:publish implica content:read. Las claves creadas antes de la asignación de alcances tienen null scopes = acceso completo (modo heredado).

Query Parameters

  • coverage string enum
  • end_date string

    Límite superior de fecha ISO.

  • feedback string enum
  • page_size integer

    Número de elementos que se devolverán por página (1-100). Ejemplo: 20

  • start_cursor string

    Cursor de paginación opaco. Pasa el next_cursor de una respuesta anterior para obtener la página siguiente. Ejemplo: eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ

  • start_date string

    Límite inferior de fecha ISO.

Response

application/json
  • results[] object array

    Elementos de esta página. Resumen de la conversación del asistente: un contrato público deliberado, no la fila sin procesar.

    + Show Child Attributes
    • id string
    • createdAt string

      Marca de tiempo ISO 8601 en UTC.

    • updatedAt string

      Marca de tiempo ISO 8601 en UTC.

    • status string

      Estado del ciclo de vida de la conversación.

    • source string enum | null

      Origen de la conversación: el centro de ayuda (help) o el widget integrado (widget).

    • pageUrl string | null

      La página en la que se encontraba el usuario final cuando comenzó la conversación, si se capturó.

    • user anyOf

      Usuario identificado del centro de ayuda para esta conversación, o null cuando el usuario final era anónimo.

      + 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 de usuario del centro de ayuda de Ferndesk (hcusr_...).

          • name string | null

            Nombre visible del usuario del centro de ayuda.

        • option 2 null
    • summary string | null

      Resumen de una línea generado por IA, si está disponible.

    • coverage string enum | null

      Qué tan bien el centro de ayuda cubrió la pregunta.

    • feedback string enum | null

      Comentario del usuario final mediante pulgar arriba o abajo sobre la conversación, o null si no se dejó ninguno.

    • escalated boolean

      Indica si la conversación se derivó a una persona.

    • messageCount integer

      Número de mensajes del usuario final en la conversación.

  • has_more boolean

    Indica si hay más elementos disponibles después de esta página.

  • next_cursor string | null

    Cursor que se debe pasar como start_cursor para la página siguiente, o null en la última página.