API rozmów

Rozmowa to jeden wywiad między AI a jednym respondentem. API zwraca informację, kim jest respondent, podsumowanie AI z jedną odpowiedzią na każde pytanie i pełną transkrypcję. O uwierzytelnianiu, paginacji i błędach przeczytasz na stronie Przegląd API.

Lista rozmów#

HTTP

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

Zwraca rozmowy w projekcie, od najnowszych, każdą z podsumowaniem AI. Lista nie zawiera transkrypcji. Pobierzesz je w sposób opisany w sekcji Pobieranie rozmowy.

Parametry zapytania#

Parametr	Opis
`status`	Jedna lub więcej wartości `invited`, `opened`, `started`, `completed`, `cancelled`, rozdzielonych przecinkami. Bez tego parametru zwracane są wszystkie statusy oprócz `invited`.
`sentiment`	Jedna lub więcej wartości `positive`, `negative`, `neutral`, `mixed`, rozdzielonych przecinkami
`created_after`	Tylko rozmowy utworzone w podanym czasie ISO 8601 lub później, np. `2026-05-01T00:00:00Z`
`created_before`	Tylko rozmowy utworzone w podanym czasie lub wcześniej
`search`	Tekst do wyszukania w podsumowaniach, cytatach i danych respondenta. Do 200 znaków.
`limit`	Od 1 do 100. Domyślnie `25`.
`cursor`	Wartość `next_cursor` z poprzedniej strony

Pełne podsumowanie mają tylko zakończone rozmowy, więc większość integracji wysyła status=completed.

Przykład#

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"

Odpowiedź#

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

Pola rozmowy#

Pole	Typ	Opis
`id`	string	ID rozmowy, to samo, które webhooki wysyłają jako `conversation_id`
`project_id`	string	Projekt, do którego należy rozmowa
`status`	string	`invited`, `opened`, `started`, `completed` lub `cancelled`. Panel pokazuje `started` jako W toku.
`created_at`	string	Kiedy utworzono rozmowę. W przypadku zaproszeń to moment utworzenia zaproszenia.
`started_at`	string lub null	Kiedy zaczął się wywiad
`ended_at`	string lub null	Kiedy rozmowa została zakończona lub anulowana
`duration_seconds`	number lub null	Czas od początku do końca
`country`	string lub null	Kod kraju respondenta, jeśli jest znany
`overall_sentiment`	string lub null	`positive`, `negative`, `neutral` lub `mixed`. To samo co `summary.overall_sentiment`.
`respondent.label`	string lub null	Najlepsze oznaczenie respondenta: e-mail, potem imię i nazwisko, potem inna tożsamość
`respondent.email`	string lub null	Przestarzałe pole, `null` w nowych rozmowach. Adresy e-mail odczytuj z `respondent.identities`.
`respondent.identities`	array	Wszystko, co wiadomo o respondencie. `source` to `owner` (podane przez Ciebie), `ai` (wyodrębnione z wiadomości respondenta) lub `system` (dodane przez Diaform).
`metadata`	object	Puste dla zaproszeń i bezpośrednich linków. W osadzonych rozmowach zawiera szczegóły osadzenia, np. `"embed": true` i `embed_parent_origin`.
`invite`	object lub null	Szczegóły zaproszenia, gdy rozmowa pochodzi z zaproszenia respondenta, w przeciwnym razie `null`
`summary`	object lub null	Podsumowanie AI. `null`, dopóki rozmowa się nie zakończy i podsumowanie nie będzie gotowe.

Pola podsumowania#

Pole	Typ	Opis
`overall_sentiment`	string	`positive`, `negative`, `neutral` lub `mixed`
`answers`	array	Jeden wpis na każde pytanie zadane respondentowi
`answers[].question_id`	string	ID pytania w projekcie
`answers[].question`	string	Pytanie w brzmieniu, w jakim zostało zadane
`answers[].summary`	string	Krótkie podsumowanie odpowiedzi
`answers[].sentiment`	string	`positive`, `negative`, `neutral` lub `mixed`
`answers[].confidence`	string	`high`, `medium` lub `low`: na ile pełna była odpowiedź na pytanie
`answers[].quotes`	array	Ciekawe cytaty, dosłowne słowa respondenta. Często puste.
`urgent_issues`	array	Krytyczne problemy zgłoszone przez respondenta, jako krótkie ciągi znaków
`additional_insights`	string lub null	Przydatne opinie, które nie pasowały do żadnego pytania

Pobieranie rozmowy#

HTTP

GET /api/v1/conversations/{conversation_id}

Zwraca jedną rozmowę ze wszystkimi polami z listy oraz transkrypcją w messages.

Przykład#

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

Odpowiedź#

Pola wspólne z listą są tu skrócone.

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

Pole	Typ	Opis
`messages`	array	Transkrypcja po kolei. Pusta, gdy respondent ani razu nie odpowiedział.
`messages[].role`	string	`interviewer` (AI) lub `respondent`
`messages[].text`	string	Treść wypowiedzi. Odpowiedzi głosowe pojawiają się jako transkrypcja, a wybór lub ocena jako tekst, np. `Selected answers: Pro`.