Gesprekken-API

Een gesprek is één interview tussen de AI en één respondent. De API geeft terug wie de respondent is, de AI-samenvatting met één antwoord per vraag, en het volledige transcript. Zie het API-overzicht voor authenticatie, paginering en fouten.

Gesprekken ophalen#

HTTP

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

Geeft de gesprekken van een project terug, van nieuw naar oud, elk met de AI-samenvatting. Transcripten zitten niet in de lijst. Haal die op met Eén gesprek ophalen.

Queryparameters#

Parameter	Beschrijving
`status`	Eén of meer van `invited`, `opened`, `started`, `completed`, `cancelled`, gescheiden door komma's. Zonder deze parameter krijg je elke status behalve `invited`.
`sentiment`	Eén of meer van `positive`, `negative`, `neutral`, `mixed`, gescheiden door komma's
`created_after`	Alleen gesprekken die op of na deze ISO 8601-tijd zijn aangemaakt, zoals `2026-05-01T00:00:00Z`
`created_before`	Alleen gesprekken die op of voor deze tijd zijn aangemaakt
`search`	Tekst om te zoeken in samenvattingen, citaten en gegevens van de respondent. Maximaal 200 tekens.
`limit`	1 tot 100. Standaard `25`.
`cursor`	De `next_cursor` van de vorige pagina

Alleen afgeronde gesprekken hebben een volledige samenvatting, dus de meeste integraties sturen status=completed mee.

Voorbeeld#

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"

Response#

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

Velden van een gesprek#

Veld	Type	Beschrijving
`id`	string	ID van het gesprek, dezelfde die webhooks sturen als `conversation_id`
`project_id`	string	Het project waar het bij hoort
`status`	string	`invited`, `opened`, `started`, `completed` of `cancelled`. Het dashboard toont `started` als Bezig.
`created_at`	string	Wanneer het gesprek is aangemaakt. Bij uitnodigingen is dat het moment waarop de uitnodiging is aangemaakt.
`started_at`	string of null	Wanneer het interview is begonnen
`ended_at`	string of null	Wanneer het gesprek is afgerond of geannuleerd
`duration_seconds`	number of null	Tijd van begin tot eind
`country`	string of null	De landcode van de respondent, als die bekend is
`overall_sentiment`	string of null	`positive`, `negative`, `neutral` of `mixed`. Gelijk aan `summary.overall_sentiment`.
`respondent.label`	string of null	De beste naam voor de respondent: eerst het e-mailadres, dan de naam, dan een andere identiteit
`respondent.email`	string of null	Verouderd veld, `null` bij nieuwe gesprekken. Lees e-mailadressen uit `respondent.identities`.
`respondent.identities`	array	Alles wat over de respondent bekend is. `source` is `owner` (jij hebt het aangeleverd), `ai` (gehaald uit de berichten van de respondent) of `system` (toegevoegd door Diaform).
`metadata`	object	Leeg bij uitnodigingen en directe links. Bij ingesloten gesprekken bevat het embed-gegevens zoals `"embed": true` en `embed_parent_origin`.
`invite`	object of null	Gegevens van de uitnodiging als het gesprek uit een respondentuitnodiging komt, anders `null`
`summary`	object of null	De AI-samenvatting. `null` tot het gesprek is afgelopen en de samenvatting klaar is.

Velden van de samenvatting#

Veld	Type	Beschrijving
`overall_sentiment`	string	`positive`, `negative`, `neutral` of `mixed`
`answers`	array	Eén item per vraag die aan de respondent is gesteld
`answers[].question_id`	string	De ID van de vraag in het project
`answers[].question`	string	De vraag zoals die is gesteld
`answers[].summary`	string	Een korte samenvatting van het antwoord
`answers[].sentiment`	string	`positive`, `negative`, `neutral` of `mixed`
`answers[].confidence`	string	`high`, `medium` of `low`: hoe volledig de vraag is beantwoord
`answers[].quotes`	array	Opvallende citaten in de eigen woorden van de respondent. Vaak leeg.
`urgent_issues`	array	Kritieke problemen die de respondent noemde, als korte strings
`additional_insights`	string of null	Nuttige feedback die niet bij een vraag paste

Eén gesprek ophalen#

HTTP

GET /api/v1/conversations/{conversation_id}

Geeft één gesprek terug met elk veld van de lijst, plus het transcript in messages.

Voorbeeld#

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

Response#

De velden die ook in de lijst staan, zijn hier ingekort.

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

Veld	Type	Beschrijving
`messages`	array	Het transcript op volgorde. Leeg als de respondent nooit heeft geantwoord.
`messages[].role`	string	`interviewer` (de AI) of `respondent`
`messages[].text`	string	Wat er is gezegd. Gesproken antwoorden staan er als transcriptie, en een keuze of beoordeling als tekst zoals `Selected answers: Pro`.