API des conversations

Une conversation est un entretien entre l’IA et un répondant. L’API renvoie l’identité du répondant, le résumé IA avec une réponse par question, et la transcription complète. Pour l’authentification, la pagination et les erreurs, consultez la Vue d’ensemble de l’API.

Lister les conversations#

HTTP

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

Renvoie les conversations d’un projet, des plus récentes aux plus anciennes, chacune avec son résumé IA. Les transcriptions ne figurent pas dans la liste. Récupérez-les avec Obtenir une conversation.

Paramètres de requête#

Paramètre	Description
`status`	Une ou plusieurs valeurs parmi `invited`, `opened`, `started`, `completed`, `cancelled`, séparées par des virgules. Sans ce paramètre, tous les statuts sauf `invited` sont renvoyés.
`sentiment`	Une ou plusieurs valeurs parmi `positive`, `negative`, `neutral`, `mixed`, séparées par des virgules
`created_after`	Uniquement les conversations créées à partir de cette date et heure ISO 8601, par exemple `2026-05-01T00:00:00Z`
`created_before`	Uniquement les conversations créées jusqu’à cette date et heure
`search`	Texte à rechercher dans les résumés, les citations et les informations sur le répondant. Jusqu’à 200 caractères.
`limit`	De 1 à 100. `25` par défaut.
`cursor`	Le `next_cursor` de la page précédente

Seules les conversations terminées ont un résumé complet : la plupart des intégrations envoient donc status=completed.

Exemple#

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"

Réponse#

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

Champs d’une conversation#

Champ	Type	Description
`id`	string	ID de la conversation, le même que celui envoyé par les webhooks dans `conversation_id`
`project_id`	string	Le projet auquel elle appartient
`status`	string	`invited`, `opened`, `started`, `completed` ou `cancelled`. Le tableau de bord affiche `started` comme En cours.
`created_at`	string	Date de création de la conversation. Pour les invitations, il s’agit de la date de création de l’invitation.
`started_at`	string ou null	Date de début de l’entretien
`ended_at`	string ou null	Date à laquelle la conversation s’est terminée ou a été annulée
`duration_seconds`	number ou null	Durée entre le début et la fin
`country`	string ou null	Le code pays du répondant, s’il est connu
`overall_sentiment`	string ou null	`positive`, `negative`, `neutral` ou `mixed`. Identique à `summary.overall_sentiment`.
`respondent.label`	string ou null	Le meilleur nom disponible pour le répondant : son e-mail, sinon son nom, sinon une autre identité
`respondent.email`	string ou null	Champ hérité, `null` pour les nouvelles conversations. Lisez les e-mails dans `respondent.identities`.
`respondent.identities`	array	Tout ce que l’on sait du répondant. `source` vaut `owner` (vous l’avez fourni), `ai` (extrait de ses messages) ou `system` (ajouté par Diaform).
`metadata`	object	Vide pour les invitations et les liens directs. Pour les conversations intégrées, contient des détails sur l’intégration, comme `"embed": true` et `embed_parent_origin`.
`invite`	object ou null	Détails de l’invitation quand la conversation provient d’une invitation de répondant, sinon `null`
`summary`	object ou null	Le résumé IA. `null` tant que la conversation n’est pas terminée et que le résumé n’est pas prêt.

Champs du résumé#

Champ	Type	Description
`overall_sentiment`	string	`positive`, `negative`, `neutral` ou `mixed`
`answers`	array	Une entrée par question posée au répondant
`answers[].question_id`	string	L’ID de la question dans le projet
`answers[].question`	string	La question telle qu’elle a été posée
`answers[].summary`	string	Court résumé de la réponse
`answers[].sentiment`	string	`positive`, `negative`, `neutral` ou `mixed`
`answers[].confidence`	string	`high`, `medium` ou `low` : dans quelle mesure la question a reçu une réponse complète
`answers[].quotes`	array	Citations marquantes, dans les mots du répondant. Souvent vide.
`urgent_issues`	array	Problèmes critiques signalés par le répondant, sous forme de courtes chaînes
`additional_insights`	string ou null	Feedback utile qui ne relevait d’aucune question

Obtenir une conversation#

HTTP

GET /api/v1/conversations/{conversation_id}

Renvoie une conversation avec tous les champs de la liste, plus la transcription dans messages.

Exemple#

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

Réponse#

Les champs communs avec la liste sont abrégés ici.

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

Champ	Type	Description
`messages`	array	La transcription, dans l’ordre. Vide quand le répondant n’a jamais répondu.
`messages[].role`	string	`interviewer` (l’IA) ou `respondent`
`messages[].text`	string	Ce qui a été dit. Les réponses orales apparaissent sous forme de transcription, et un choix ou une note sous forme de texte, comme `Selected answers: Pro`.