Conversations API v2

Utilisez ces points de terminaison pour consulter l’historique des conversations et manipuler les messages de l’API v2. Chaque point de terminaison de cette page nécessite Authorization: Bearer YOUR_API_KEY et un accès à {agentId}.

Périmètre des conversations

Les points de terminaison de conversation en lecture seule utilisent par défaut source=api_v2. Définissez source=widget pour renvoyer les conversations du widget et du Playground ; les lignes du Playground sont stockées avec la source widget. Définissez source=all pour renvoyer les conversations API v2, widget et Playground. Les résultats restent toujours limités à l’agent du compte authentifié. Une valeur source invalide ou plusieurs paramètres de requête source renvoient 400 VALIDATION_INVALID_BODY. La poursuite du chat, les relances, les évaluations, la liste des messages et les lectures par utilisateur restent limitées aux conversations API v2.

Objets de réponse

Les résumés de conversation contiennent :

Les objets message contiennent :

Les lignes de message de type outil sont omises des transcriptions de conversation et des listes de messages.

Lister les conversations

Chemin : /api/v2/agents/{agentId}/conversations

GET /api/v2/agents/{agentId}/conversations

Authentification : clé API Bearer ayant accès à {agentId}.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations?source=all&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Succès : 200 OK

{
  "data": [
    {
      "id": "b2mD4kL8pQ1sT6vX",
      "title": "Where is my order?",
      "createdAt": 1784332800,
      "updatedAt": 1784332860,
      "userId": "customer_123",
      "source": "api_v2",
      "status": "ongoing"
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Une limite, un curseur, une valeur source invalide, ou des paramètres source en double renvoient 400 VALIDATION_INVALID_BODY.

Exporter les conversations

Chemin : /api/v2/agents/{agentId}/conversations/export

GET /api/v2/agents/{agentId}/conversations/export

Authentification : clé API Bearer ayant accès à {agentId}.

L’export utilise le même ordre de conversation et le même contrat de curseur que le point de terminaison de liste, mais plafonne chaque page à 20 conversations. Chaque conversation inclut tous les messages non liés à un outil, classés du plus ancien au plus récent.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/export?source=api_v2' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Succès : 200 OK

{
  "data": [
    {
      "id": "b2mD4kL8pQ1sT6vX",
      "title": "Where is my order?",
      "createdAt": 1784332800,
      "updatedAt": 1784332860,
      "userId": "customer_123",
      "source": "api_v2",
      "status": "ongoing",
      "messages": [
        {
          "id": "122",
          "role": "user",
          "parts": [{ "type": "text", "text": "Where is my order?" }],
          "createdAt": 1784332800,
          "feedback": null,
          "metadata": null
        }
      ]
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Obtenir une conversation

Chemin : /api/v2/agents/{agentId}/conversations/{conversationId}

GET /api/v2/agents/{agentId}/conversations/{conversationId}

Authentification : clé API Bearer ayant accès à {agentId}.

La réponse inclut la transcription complète non liée à un outil, classée du plus ancien au plus récent. Ce point de terminaison n’est pas paginé par curseur ; utilisez le point de terminaison de liste des messages pour un accès paginé aux messages API v2.

Succès : 200 OK

{
  "data": {
    "id": "b2mD4kL8pQ1sT6vX",
    "title": "Where is my order?",
    "createdAt": 1784332800,
    "updatedAt": 1784332860,
    "userId": "customer_123",
    "source": "api_v2",
    "status": "ongoing",
    "messages": [
      {
        "id": "122",
        "role": "user",
        "parts": [{ "type": "text", "text": "Where is my order?" }],
        "createdAt": 1784332800,
        "feedback": null,
        "metadata": null
      }
    ]
  },
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Une conversation introuvable dans la source sélectionnée renvoie 404 RESOURCE_NOT_FOUND.

Lister les messages

Chemin : /api/v2/agents/{agentId}/conversations/{conversationId}/messages

GET /api/v2/agents/{agentId}/conversations/{conversationId}/messages

Authentification : clé API Bearer ayant accès à {agentId}. La conversation doit être une conversation API v2.

Les curseurs de message sont le seul curseur de pagination v2 dont le composant d’ID côté serveur est validé comme une chaîne numérique, car les messages utilisent des ID de type bigint. Toutes les autres ressources paginées v2 valident des ID UUID. Traitez ces deux formes comme opaques ; ne construisez et ne décodez jamais les curseurs. Les messages de chaque page renvoyée sont classés du plus ancien au plus récent.

Succès : 200 OK

{
  "data": [
    {
      "id": "122",
      "role": "user",
      "parts": [{ "type": "text", "text": "Where is my order?" }],
      "createdAt": 1784332800,
      "feedback": null,
      "metadata": null
    },
    {
      "id": "123",
      "role": "assistant",
      "parts": [{ "type": "text", "text": "Please share your order number." }],
      "createdAt": 1784332860,
      "feedback": "positive",
      "metadata": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 2
  }
}

Une conversation API v2 introuvable renvoie 404 RESOURCE_NOT_FOUND ; une limite ou un curseur invalide renvoie 400 VALIDATION_INVALID_BODY.

Relancer une réponse de l’assistant

Chemin : /api/v2/agents/{agentId}/conversations/{conversationId}/retry

POST /api/v2/agents/{agentId}/conversations/{conversationId}/retry

Authentification : clé API Bearer ayant accès à {agentId}. La conversation doit être une conversation API v2.

La relance supprime le message utilisateur précédent, la réponse de l’assistant sélectionnée et tous les messages ultérieurs, puis rejoue ce texte utilisateur pour régénérer la réponse. Si la régénération ne parvient pas à être persistée, les lignes supprimées sont restaurées.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/b2mD4kL8pQ1sT6vX/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"messageId":"123","stream":false}'

Succès : 200 OK. Avec stream: true, la réponse est un flux d’événements envoyés par le serveur (Server-Sent Events) utilisant le même format d’événements que le chat. Avec stream: false, la réponse est :

{
  "data": {
    "id": "124",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Here is a regenerated answer." }],
    "metadata": {
      "conversationId": "b2mD4kL8pQ1sT6vX",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

Un JSON malformé renvoie 400 VALIDATION_INVALID_JSON. Un corps invalide renvoie 400 VALIDATION_INVALID_BODY. Consultez CHAT_RETRY_MESSAGE_NOT_FOUND, CHAT_RETRY_NO_USER_MESSAGE, RESOURCE_NOT_FOUND et INTERNAL_SERVER_ERROR dans le catalogue des erreurs.

Soumettre un résultat d’outil

Chemin : /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

POST /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

Authentification : clé API Bearer ayant accès à {agentId}.

{
  "toolCallId": "call_123",
  "output": { "available": true }
}

Réponse : une action en attente correspondante est réclamée une seule fois et la continuation est renvoyée en text/event-stream. Les appels inconnus ou expirés renvoient 404 ; les résultats concurrents ou contradictoires renvoient 409.

Définir ou effacer l’évaluation d’un message

Chemin : /api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

PATCH /api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

Authentification : clé API Bearer ayant accès à {agentId}. La conversation doit être une conversation API v2.

{messageId} doit se convertir en un entier positif et identifier un message de l’assistant IA dans la conversation spécifiée.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/b2mD4kL8pQ1sT6vX/messages/123/feedback' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"feedback":"positive"}'

Succès : 200 OK

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Please share your order number." }],
    "createdAt": 1784332860,
    "feedback": "positive",
    "metadata": null
  }
}

Un JSON malformé renvoie 400 VALIDATION_INVALID_JSON ; un corps invalide renvoie 400 VALIDATION_INVALID_BODY ; une conversation introuvable renvoie 404 RESOURCE_NOT_FOUND ; un message introuvable renvoie 404 RESOURCE_MESSAGE_NOT_FOUND ; et une cible qui n’est pas un message de l’assistant IA renvoie 422 RESOURCE_MESSAGE_NOT_ASSISTANT.

Lister les conversations d’un utilisateur

Chemin : /api/v2/agents/{agentId}/users/{userId}/conversations

GET /api/v2/agents/{agentId}/users/{userId}/conversations

Authentification : clé API Bearer ayant accès à {agentId}.

{userId} doit comporter de 1 à 128 caractères et ne peut contenir que des lettres, des chiffres, ., _ et -.

Seul le chat API v2 écrit userId, ce point de terminaison ne renvoie donc que des conversations API v2. Sa réponse de succès est la même enveloppe paginée de résumés de conversation que Lister les conversations.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/users/customer_123/conversations' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Succès : 200 OK. Un ID utilisateur, une limite, un curseur, ou un usage de source invalide renvoient 400 VALIDATION_INVALID_BODY.

Référence associée

• Présentation de l’API v2 et du chat
• Catalogue des erreurs API v2
• Contacts et identité vérifiée