API de conversaciones

Una conversación es una entrevista entre la IA y un participante. La API devuelve quién es el participante, el resumen de IA con una respuesta por pregunta y la transcripción completa. Para la autenticación, la paginación y los errores, consulta la descripción general de la API.

Listar conversaciones#

HTTP

GET /api/v1/projects/{project_id}/conversations

Devuelve las conversaciones de un proyecto, de la más reciente a la más antigua, cada una con su resumen de IA. Las transcripciones no se incluyen en la lista. Obtenlas con Obtener una conversación.

Parámetros de consulta#

Parámetro	Descripción
`status`	Uno o varios de `invited`, `opened`, `started`, `completed`, `cancelled`, separados por comas. Sin este parámetro, se devuelven todos los estados excepto `invited`.
`sentiment`	Uno o varios de `positive`, `negative`, `neutral`, `mixed`, separados por comas
`created_after`	Solo las conversaciones creadas a partir de esta fecha y hora ISO 8601, como `2026-05-01T00:00:00Z`
`created_before`	Solo las conversaciones creadas hasta esta fecha y hora
`search`	Texto que buscar en los resúmenes, las citas y los datos del participante. Hasta 200 caracteres.
`limit`	De 1 a 100. Valor predeterminado: `25`.
`cursor`	El `next_cursor` de la página anterior

Solo las conversaciones completadas tienen un resumen completo, así que la mayoría de las integraciones envían status=completed.

Ejemplo#

curl -G "https://diaform.io/api/v1/projects/b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d/conversations" \
  -H "Authorization: Bearer $DIAFORM_API_KEY" \
  --data-urlencode "status=completed" \
  --data-urlencode "sentiment=negative,mixed" \
  --data-urlencode "created_after=2026-05-01T00:00:00Z" \
  --data-urlencode "limit=50"

Respuesta#

JSON

{
  "data": [
    {
      "id": "0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee",
      "project_id": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
      "status": "completed",
      "created_at": "2026-05-07T12:00:00.123456+00:00",
      "started_at": "2026-05-07T12:01:11.482913+00:00",
      "ended_at": "2026-05-07T12:15:41.204+00:00",
      "duration_seconds": 870,
      "country": "DE",
      "overall_sentiment": "mixed",
      "respondent": {
        "label": "alex@acme.com",
        "email": null,
        "identities": [
          { "type": "email", "value": "alex@acme.com", "source": "owner" },
          { "type": "name", "value": "Alex", "source": "ai" }
        ]
      },
      "metadata": {},
      "invite": {
        "id": "3a4f49c7-b8f4-4c44-8f74-fd8e4277c3e4",
        "status": "completed",
        "created_at": "2026-05-07T12:00:00.123456+00:00",
        "opened_at": "2026-05-07T12:01:11.482913+00:00",
        "completed_at": "2026-05-07T12:15:41.204+00:00"
      },
      "summary": {
        "overall_sentiment": "mixed",
        "answers": [
          {
            "question_id": "V1StGXR8_Z5jdHi6B-myT",
            "question": "How did your first week with the product go?",
            "summary": "Setup was quick, but inviting teammates was confusing.",
            "sentiment": "mixed",
            "confidence": "high",
            "quotes": ["I had no idea where the invite button was"]
          }
        ],
        "urgent_issues": [],
        "additional_insights": "Would pay more for a Slack integration."
      }
    }
  ],
  "has_more": true,
  "next_cursor": "WyIyMDI2LTA1LTA3VDEyOjAwOjAwLjEyMzQ1NiswMDowMCIsIjBmOGQ0M2EyIl0"
}

Campos de la conversación#

Campo	Tipo	Descripción
`id`	string	ID de la conversación, el mismo que los webhooks envían como `conversation_id`
`project_id`	string	El proyecto al que pertenece
`status`	string	`invited`, `opened`, `started`, `completed` o `cancelled`. El panel muestra `started` como En curso.
`created_at`	string	Cuándo se creó la conversación. En las invitaciones, es cuando se creó la invitación.
`started_at`	string o null	Cuándo empezó la entrevista
`ended_at`	string o null	Cuándo se completó o se canceló la conversación
`duration_seconds`	number o null	Tiempo desde el inicio hasta el final
`country`	string o null	El código de país del participante, cuando se conoce
`overall_sentiment`	string o null	`positive`, `negative`, `neutral` o `mixed`. Igual que `summary.overall_sentiment`.
`respondent.label`	string o null	El mejor nombre para el participante: su correo, después su nombre y después otra identidad
`respondent.email`	string o null	Campo heredado, `null` en las conversaciones nuevas. Lee los correos de `respondent.identities`.
`respondent.identities`	array	Todo lo que se sabe del participante. `source` es `owner` (lo aportaste tú), `ai` (extraído de sus mensajes) o `system` (añadido por Diaform).
`metadata`	object	Vacío en las invitaciones y los enlaces directos. En las conversaciones insertadas contiene datos de la inserción, como `"embed": true` y `embed_parent_origin`.
`invite`	object o null	Datos de la invitación cuando la conversación viene de una invitación a un participante; si no, `null`
`summary`	object o null	El resumen de IA. `null` hasta que la conversación termina y el resumen está listo.

Campos del resumen#

Campo	Tipo	Descripción
`overall_sentiment`	string	`positive`, `negative`, `neutral` o `mixed`
`answers`	array	Una entrada por cada pregunta que se le hizo al participante
`answers[].question_id`	string	El ID de la pregunta en el proyecto
`answers[].question`	string	La pregunta tal como se hizo
`answers[].summary`	string	Resumen breve de la respuesta
`answers[].sentiment`	string	`positive`, `negative`, `neutral` o `mixed`
`answers[].confidence`	string	`high`, `medium` o `low`: hasta qué punto se respondió la pregunta
`answers[].quotes`	array	Citas destacadas con las propias palabras del participante. A menudo está vacío.
`urgent_issues`	array	Problemas críticos que planteó el participante, como cadenas breves
`additional_insights`	string o null	Feedback útil que no encajaba en ninguna pregunta

Obtener una conversación#

HTTP

GET /api/v1/conversations/{conversation_id}

Devuelve una conversación con todos los campos de la lista y, además, la transcripción en messages.

Ejemplo#

curl "https://diaform.io/api/v1/conversations/0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee" \
  -H "Authorization: Bearer $DIAFORM_API_KEY"

Respuesta#

Los campos que comparte con la lista aparecen aquí abreviados.

JSON

{
  "id": "0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee",
  "project_id": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
  "status": "completed",
  "overall_sentiment": "mixed",
  "summary": {},
  "messages": [
    {
      "role": "interviewer",
      "text": "Hi! Thanks for taking the time. How did your first week with the product go?"
    },
    {
      "role": "respondent",
      "text": "Setup was fast. But I had no idea where the invite button was."
    },
    {
      "role": "interviewer",
      "text": "Where did you expect to find it?"
    }
  ]
}

Campo	Tipo	Descripción
`messages`	array	La transcripción en orden. Vacío cuando el participante no llegó a responder.
`messages[].role`	string	`interviewer` (la IA) o `respondent`
`messages[].text`	string	Lo que se dijo. Las respuestas habladas aparecen como su transcripción, y una opción o una valoración como texto, por ejemplo `Selected answers: Pro`.