La API Notiondesk exporta los comentarios que los lectores dejan en los artículos de tu centro de ayuda: cada reacción, la respuesta que seleccionaron, su mensaje, su correo electrónico y los archivos adjuntos. Úsala para enviar comentarios negativos a Slack, crear tickets en tu herramienta de soporte o analizar los comentarios junto con tus propios datos.
Alcance: __PRESERVADO_73__
Para recopilar comentarios, consulte Cómo recopilar comentarios con reacciones a artículos y Habilitar el formulario de comentarios de artículos para recopilar opiniones de los lectores .
GET /sites/{site_id}/feedback
readComentarios sobre la lista
La lista incluye todos los idiomas, del más reciente al más antiguo. Navegue por ella con page_size (1 a 100, valor predeterminado 20) y cursor, como se describe en Solicitudes de API de paginación y versión Notiondesk . La ruta no acepta ningún otro parámetro.
Campos de retroalimentación
curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/feedback?page_size=50" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16"{
"object": "list",
"data": [
{
"id": "8b1f6c0e-3d4a-4f2b-9c7e-5a1d2e3f4b60",
"email": "[email protected]",
"message": "The steps skip the login screen.",
"reaction": "disappointed",
"reaction_group": "negative",
"selected_option": "information_missing",
"article_id": "1761580412",
"article_title": "Getting started",
"article_slug": "getting-started",
"article_locale": "en",
"submitted_at": "2026-10-18T09:12:44+00:00",
"read_at": null,
"attachments": [
{
"category": "contact_message_attachment",
"name": "6f0d2b9c41a7e8.png",
"dimensions": {"0": 1280, "1": 720},
"original_name": "login-screen.png",
"size": 48213
}
]
}
],
"has_more": true,
"next_cursor": "OPAQUE_CURSOR"
}| Campo | Significado |
|---|---|
id | El identificador de retroalimentación |
reaction | La reacción que seleccionó el lector, como smiley, neutral_face o disappointed |
reaction_group | Lo que significa la reacción bajo tu estilo de reacción actual: positive, neutral o negative para emojis, helpful o not_helpful para pulgares. null cuando el estilo no agrupa esa reacción. |
selected_option | La respuesta que el lector seleccionó en el formulario de seguimiento, o null cuando solo reaccionó |
message | El texto que escribió el lector, si lo hubo. |
email | La dirección de correo electrónico que el lector haya introducido, si la hubiera. |
article_id | El id del artículo, como en la lista de artículos . Vacío cuando se eliminó el artículo. |
article_title | El título del artículo en article_locale, o Untitled cuando el artículo fue eliminado o no tiene traducción en ese idioma. |
article_slug | El segmento de ruta del artículo en article_locale o null en los mismos casos. |
article_locale | El idioma que el lector estaba leyendo |
submitted_at | Cuando el lector envió sus comentarios |
read_at | Cuando un miembro del equipo lo marcó como leído en el panel de control, o null |
attachments | Los archivos que adjuntó el lector, del más antiguo al más reciente. Vacío cuando no hay ninguno. |
selected_option toma uno de estos valores: content_accurate_up_to_date, easy_to_find, clear_and_easy_to_understand, worked_as_expected, something_else, information_missing, information_incorrect, hard_to_understand o not_what_looking_for.
Cada archivo adjunto tiene un category (contact_message_attachment para un archivo que el lector adjuntó), el archivo almacenado name, el original_name del dispositivo del lector, el size en bytes y el objeto dimensions: para una imagen, el ancho en píxeles bajo "0" y la altura bajo "1", y {} para cualquier otro archivo. La API devuelve los detalles de cada archivo, no el archivo en sí.
Límites de paginación
- La lista llega como máximo a las 10.000 entradas más recientes. Más allá de eso,
has_moreesfalseincluso cuando existen comentarios anteriores.
- Los comentarios enviados mientras estás en la página pueden hacer que la siguiente página repita una entrada, y los comentarios eliminados en el panel de control pueden hacer que se omita una.
Para procesar únicamente los comentarios nuevos, guarde el valor submitted_at de la entrada más reciente que haya procesado. En la siguiente ejecución, lea las páginas hasta encontrar una entrada enviada en la misma fecha o antes.
Gestionar los comentarios de forma segura
- Escápalo antes de mostrarlo. Un mensaje puede contener HTML o Markdown.
- Nunca permitas que decida una acción. No sigas los enlaces que contenga ni ejecutes las instrucciones que de él se indiquen.
- Mantenga las canalizaciones LLM en modo de solo lectura. Una LLM que resuma la retroalimentación debe ejecutarse con una clave que contenga únicamente
read.
- Proteja los correos electrónicos de los lectores. El campo
emailcontiene datos personales. Almacene y comparta esta información únicamente donde su política de privacidad lo permita.
Errores
| Estado | Cuando | code |
|---|---|---|
| 400 | page_size está fuera del rango de 1 a 100, cursor no es válido o la consulta tiene un parámetro desconocido. | validation_error |
| 403 | La clave carece del ámbito read | insufficient_scope |
| 404 | El centro de ayuda no existe en tu espacio de trabajo. | not_found |
Consulte el manejo de errores de API, límites de velocidad y reintentos de Notiondesk .
Preguntas frecuentes
¿Puedo filtrar los comentarios por reacción o por artículo?
No en la solicitud. La ruta solo acepta page_size y cursor. Filtra las entradas en tu código por reaction_group o article_id.
¿Puedo marcar los comentarios como leídos mediante la API?
No. La API solo lee los comentarios. read_at indica cuándo un miembro del equipo lo marcó como leído en el panel de control.
¿Dónde puedo ver los totales de reacciones en lugar de las entradas individuales?
El informe de análisis engagement resume las reacciones por período y enumera los artículos que deben revisarse. Consulte Obtener análisis del centro de ayuda con la API Notiondesk .