Gespräche-API

Ein Gespräch ist ein Interview zwischen der KI und einem Teilnehmer. Die API gibt zurück, wer der Teilnehmer ist, dazu die KI-Zusammenfassung mit einer Antwort pro Frage und das vollständige Transkript. Authentifizierung, Paginierung und Fehler sind im API-Überblick beschrieben.

Gespräche auflisten#

HTTP

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

Gibt die Gespräche eines Projekts zurück, die neuesten zuerst, jeweils mit KI-Zusammenfassung. Transkripte sind in der Liste nicht enthalten. Ruf sie mit Gespräch abrufen ab.

Query-Parameter#

Parameter	Beschreibung
`status`	Einer oder mehrere der Werte `invited`, `opened`, `started`, `completed`, `cancelled`, durch Kommas getrennt. Ohne den Parameter wird jeder Status außer `invited` zurückgegeben.
`sentiment`	Einer oder mehrere der Werte `positive`, `negative`, `neutral`, `mixed`, durch Kommas getrennt
`created_after`	Nur Gespräche, die zu diesem ISO-8601-Zeitpunkt oder danach erstellt wurden, etwa `2026-05-01T00:00:00Z`
`created_before`	Nur Gespräche, die zu diesem Zeitpunkt oder davor erstellt wurden
`search`	Text, nach dem in Zusammenfassungen, Zitaten und Angaben zum Teilnehmer gesucht wird. Bis zu 200 Zeichen.
`limit`	1 bis 100. Standard `25`.
`cursor`	Der `next_cursor` der vorherigen Seite

Nur abgeschlossene Gespräche haben eine vollständige Zusammenfassung, deshalb senden die meisten Integrationen status=completed.

Beispiel#

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"

Antwort#

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

Felder eines Gesprächs#

Feld	Typ	Beschreibung
`id`	string	ID des Gesprächs, dieselbe, die Webhooks als `conversation_id` senden
`project_id`	string	Das Projekt, zu dem es gehört
`status`	string	`invited`, `opened`, `started`, `completed` oder `cancelled`. Das Dashboard zeigt `started` als Läuft an.
`created_at`	string	Wann das Gespräch erstellt wurde. Bei Einladungen ist das der Zeitpunkt, zu dem die Einladung erstellt wurde.
`started_at`	string oder null	Wann das Interview begonnen hat
`ended_at`	string oder null	Wann das Gespräch abgeschlossen oder abgebrochen wurde
`duration_seconds`	number oder null	Zeit vom Beginn bis zum Ende
`country`	string oder null	Der Ländercode des Teilnehmers, falls bekannt
`overall_sentiment`	string oder null	`positive`, `negative`, `neutral` oder `mixed`. Entspricht `summary.overall_sentiment`.
`respondent.label`	string oder null	Die beste Bezeichnung für den Teilnehmer: zuerst seine E-Mail-Adresse, dann sein Name, dann eine andere Identität
`respondent.email`	string oder null	Altes Feld, bei neuen Gesprächen `null`. Lies E-Mail-Adressen aus `respondent.identities`.
`respondent.identities`	array	Alles, was über den Teilnehmer bekannt ist. `source` ist `owner` (von dir geliefert), `ai` (aus seinen Nachrichten erkannt) oder `system` (von Diaform hinzugefügt).
`metadata`	object	Bei Einladungen und direkten Links leer. Bei eingebetteten Gesprächen enthält es Angaben zur Einbettung wie `"embed": true` und `embed_parent_origin`.
`invite`	object oder null	Angaben zur Einladung, wenn das Gespräch aus einer Teilnehmer-Einladung stammt, sonst `null`
`summary`	object oder null	Die KI-Zusammenfassung. `null`, bis das Gespräch endet und die Zusammenfassung fertig ist.

Felder der Zusammenfassung#

Feld	Typ	Beschreibung
`overall_sentiment`	string	`positive`, `negative`, `neutral` oder `mixed`
`answers`	array	Ein Eintrag pro Frage, die dem Teilnehmer gestellt wurde
`answers[].question_id`	string	Die ID der Frage im Projekt
`answers[].question`	string	Die Frage, wie sie gestellt wurde
`answers[].summary`	string	Eine kurze Zusammenfassung der Antwort
`answers[].sentiment`	string	`positive`, `negative`, `neutral` oder `mixed`
`answers[].confidence`	string	`high`, `medium` oder `low`: wie vollständig die Frage beantwortet wurde
`answers[].quotes`	array	Markante Zitate in den eigenen Worten des Teilnehmers. Oft leer.
`urgent_issues`	array	Kritische Probleme, die der Teilnehmer angesprochen hat, als kurze Strings
`additional_insights`	string oder null	Nützliches Feedback, das zu keiner Frage gepasst hat

Gespräch abrufen#

HTTP

GET /api/v1/conversations/{conversation_id}

Gibt ein Gespräch mit jedem Feld der Liste zurück, dazu das Transkript in messages.

Beispiel#

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

Antwort#

Die Felder, die auch in der Liste vorkommen, sind hier gekürzt.

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

Feld	Typ	Beschreibung
`messages`	array	Das Transkript in der richtigen Reihenfolge. Leer, wenn der Teilnehmer nie geantwortet hat.
`messages[].role`	string	`interviewer` (die KI) oder `respondent`
`messages[].text`	string	Was gesagt wurde. Gesprochene Antworten erscheinen als Transkription, eine Auswahl oder Bewertung als Text wie `Selected answers: Pro`.