API v2

L’API v2 est une API REST structurée pour gérer les agents et créer des expériences de chat personnalisées. Elle ajoute la gestion des agents, le chat en streaming, l’historique des conversations, l’évaluation des messages, les contacts, les leads, les sources, les paramètres et les points de terminaison d’entraînement.

L’accès à l’API nécessite un forfait Hobby ou supérieur, avec une facturation active.

URL de base

https://your-domain.com/api/v2

Authentification

À l’exception du bilan de santé, envoyez la clé API de votre espace de travail comme jeton Bearer :

Authorization: Bearer YOUR_API_KEY

Créez et révoquez des clés API depuis Paramètres > Clés API.

Format de réponse

La plupart des réponses réussies renvoient soit un objet ressource, soit une enveloppe data :

{
  "data": []
}

Les points de terminaison de liste incluent une pagination par curseur :

{
  "data": [],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 0
  }
}

Les erreurs utilisent un objet error structuré :

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Chaque réponse v2 inclut un en-tête x-request-id. Indiquez-le lorsque vous contactez le support au sujet d’une requête API.

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.

Bilan de santé

GET /api/v2/health

Le bilan de santé ne nécessite pas d’authentification.

Succès : 200 OK

{
  "status": "ok",
  "timestamp": 1784332800
}

timestamp correspond à l’horodatage Unix actuel en secondes.

Chat

POST /api/v2/agents/{agentId}/chat

Requête :

{
  "message": "What plans do you offer?",
  "conversationId": "optional-existing-conversation-id",
  "userId": "optional-user-id",
  "stream": true
}

Les réponses en streaming utilisent des événements envoyés par le serveur (Server-Sent Events). Le flux inclut les événements message-start, text-start, text-delta, text-end, message-metadata, finish, et [DONE]. Un échec du flux ou du hook de complétion émet un événement error avec error.code défini sur CHAT_STREAMING_ERROR ; ce code de protocole propre au SSE est distinct du catalogue des erreurs REST structuré. message-metadata contient l’ID du message de l’assistant lorsque la persistance réussit, ainsi que l’ID de conversation, l’ID utilisateur, le motif de fin et l’utilisation. Son messageId vaut null lorsqu’aucun message d’assistant n’a été persisté. Lorsque la réponse est mise en pause sur une action côté client, le flux émet également un événement tool-call avec { "id", "name", "arguments" } ; soumettez le résultat au point de terminaison tool-result pour reprendre la conversation — la réponse à cette requête diffuse la suite.

Les réponses non-streaming renvoient :

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "..." }],
    "pendingToolCall": null,
    "metadata": {
      "userMessageId": "122",
      "conversationId": "abc123",
      "userId": "user_123",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

En mode non-streaming, les valeurs data.id et metadata.userMessageId sont des ID de message numériques sérialisés sous forme de chaînes, ou null lorsque le message correspondant n’a pas été persisté. metadata.userId correspond à l’ID utilisateur fourni ou stocké, ou à null. pendingToolCall vaut null, sauf si la réponse s’est interrompue sur un appel d’outil côté client ; dans ce cas, il contient { "id", "name", "arguments" } pour le endpoint de résultat d’outil.

Résumé des points de terminaison

Évaluation

Utilisez l’évaluation pour marquer les messages de l’assistant API v2 comme positive, negative, ou null. Consultez Conversations, messages et évaluations pour connaître le schéma de requête, la réponse et le comportement en cas d’erreur.

Pagination

Traitez les curseurs comme des jetons opaques renvoyés par l’API. Réutilisez la valeur pagination.cursor telle quelle lors de la requête suivante ; ne la construisez pas et ne la décodez pas.

Les contacts acceptent aussi search. Les leads acceptent les filtres de date-heure ISO 8601 inclusifs createdAfter et createdBefore. Les sources acceptent sourceType avec web_crawl, file_upload, text_snippet, ou qna_entry.

Les formats de curseur sont un détail d’implémentation interne. Les clients doivent traiter chaque curseur comme opaque et le réutiliser tel quel, sans le construire ni le décoder.

Erreurs courantes

Consultez le catalogue complet des erreurs API v2 pour connaître les 27 codes déclarés, les statuts HTTP, les déclencheurs, et les codes réservés.

Référence

• Catalogue des erreurs
• Agents et paramètres
• Conversations, messages, relances et évaluations
• Sources et entraînement
• Contacts et leads
• Canal Instagram

Étapes suivantes

• Créer une clé API
• Configurer la vérification d’identité
• Consulter les erreurs API v2
• Gérer les agents et paramètres
• Travailler avec les conversations
• Gérer les sources et l’entraînement
• Gérer les contacts et les leads
• Gérer le canal Instagram