API delle conversazioni

Una conversazione è un’intervista tra l’IA e un rispondente. L’API restituisce chi è il rispondente, il riepilogo IA con una risposta per ogni domanda e la trascrizione completa. Per autenticazione, paginazione ed errori, vedi la Panoramica dell’API.

Elenca le conversazioni#

HTTP

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

Restituisce le conversazioni di un progetto, dalla più recente, ognuna con il suo riepilogo IA. Le trascrizioni non sono incluse nell’elenco. Recuperale con Ottieni una conversazione.

Parametri della query#

Parametro	Descrizione
`status`	Uno o più tra `invited`, `opened`, `started`, `completed`, `cancelled`, separati da virgole. Senza questo parametro vengono restituiti tutti gli stati tranne `invited`.
`sentiment`	Uno o più tra `positive`, `negative`, `neutral`, `mixed`, separati da virgole
`created_after`	Solo le conversazioni create a partire da questa data e ora ISO 8601, ad esempio `2026-05-01T00:00:00Z`
`created_before`	Solo le conversazioni create fino a questa data e ora
`search`	Testo da cercare nei riepiloghi, nelle citazioni e nei dati del rispondente. Fino a 200 caratteri.
`limit`	Da 1 a 100. Predefinito `25`.
`cursor`	Il `next_cursor` della pagina precedente

Solo le conversazioni completate hanno un riepilogo completo, quindi la maggior parte delle integrazioni invia status=completed.

Esempio#

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"

Risposta#

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

Campi della conversazione#

Campo	Tipo	Descrizione
`id`	string	ID della conversazione, lo stesso che i webhook inviano come `conversation_id`
`project_id`	string	Il progetto a cui appartiene
`status`	string	`invited`, `opened`, `started`, `completed` o `cancelled`. La dashboard mostra `started` come In corso.
`created_at`	string	Quando è stata creata la conversazione. Per gli inviti, è il momento in cui è stato creato l’invito.
`started_at`	string o null	Quando è iniziata l’intervista
`ended_at`	string o null	Quando la conversazione è stata completata o annullata
`duration_seconds`	number o null	Tempo dall’inizio alla fine
`country`	string o null	Il codice del paese del rispondente, se è noto
`overall_sentiment`	string o null	`positive`, `negative`, `neutral` o `mixed`. Uguale a `summary.overall_sentiment`.
`respondent.label`	string o null	Il nome migliore per il rispondente: la sua email, poi il suo nome, poi un’altra identità
`respondent.email`	string o null	Campo legacy, `null` per le nuove conversazioni. Leggi le email da `respondent.identities`.
`respondent.identities`	array	Tutto ciò che si sa del rispondente. `source` è `owner` (l’hai fornito tu), `ai` (estratto dai suoi messaggi) o `system` (aggiunto da Diaform).
`metadata`	object	Vuoto per gli inviti e i link diretti. Per le conversazioni incorporate contiene i dettagli dell’embed, come `"embed": true` ed `embed_parent_origin`.
`invite`	object o null	I dettagli dell’invito quando la conversazione arriva da un invito a un rispondente, altrimenti `null`
`summary`	object o null	Il riepilogo IA. `null` finché la conversazione non finisce e il riepilogo non è pronto.

Campi del riepilogo#

Campo	Tipo	Descrizione
`overall_sentiment`	string	`positive`, `negative`, `neutral` o `mixed`
`answers`	array	Una voce per ogni domanda posta al rispondente
`answers[].question_id`	string	L’ID della domanda nel progetto
`answers[].question`	string	La domanda così com’è stata posta
`answers[].summary`	string	Breve riepilogo della risposta
`answers[].sentiment`	string	`positive`, `negative`, `neutral` o `mixed`
`answers[].confidence`	string	`high`, `medium` o `low`: quanto è completa la risposta alla domanda
`answers[].quotes`	array	Citazioni rilevanti, con le parole del rispondente. Spesso vuoto.
`urgent_issues`	array	Problemi critici segnalati dal rispondente, come brevi stringhe
`additional_insights`	string o null	Feedback utile che non rientrava in nessuna domanda

Ottieni una conversazione#

HTTP

GET /api/v1/conversations/{conversation_id}

Restituisce una conversazione con tutti i campi dell’elenco, più la trascrizione in messages.

Esempio#

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

Risposta#

I campi in comune con l’elenco qui sono abbreviati.

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	Descrizione
`messages`	array	La trascrizione, in ordine. Vuoto quando il rispondente non ha mai risposto.
`messages[].role`	string	`interviewer` (l’IA) o `respondent`
`messages[].text`	string	Ciò che è stato detto. Le risposte a voce compaiono come trascrizione, e una scelta o una valutazione come testo, ad esempio `Selected answers: Pro`.