Le même consultant que celui de l'espace personnel est disponible depuis votre application. Vous créez une session, ouvrez le flux, envoyez un message et recevez la réponse par morceaux. Nécessite le scope tools:chat.
Fonctionnement
- Créez une session - elle conserve le contexte de la conversation.
- Ouvrez le flux d'événements de la session.
- Envoyez un message.
- La réponse arrive dans le flux par morceaux jusqu'à ce qu'elle soit complète.
Ouvrez le flux avant d'envoyer le message, sinon les premiers morceaux de la réponse vous échapperont.
Sessions
| Requête | Ce qu'elle fait |
|---|---|
POST /chat/sessions | créer une session |
GET /chat/sessions | vos sessions : limit 1-50 (20 par défaut, au-delà 400), cursor, q (recherche dans les titres), projectId, archivedOnly, sort (recent, title) |
PATCH /chat/sessions/{id} | modifier une session ; au moins un champ |
DELETE /chat/sessions/{id} | archiver |
Corps de POST /chat/sessions (tout est facultatif) :
| Champ | Description |
|---|---|
title | nom de la session, jusqu'à 200 caractères |
projectId | projet auquel appartient la session |
mode | chat_consult (par défaut) ; toute autre valeur est remplacée par chat_consult |
Champs de PATCH /chat/sessions/{id} :
| Champ | Description |
|---|---|
title | nouveau nom, jusqu'à 200 caractères |
projectId | déplacer vers un projet ; null - retirer du projet |
isPinned | épingler ou désépingler |
isUnread | marquer comme non lu ou lu |
isArchived | uniquement false - restaurer une session archivée ; pour archiver, utilisez DELETE |
curl -X POST https://developers.grem.capital/api/v1/chat/sessions \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{"title":"Client question about a mortgage"}'
La réponse contient sessionId - transmettez-le à chacun des appels suivants. La création d'une session nécessite un profil de compte complété ; sinon - 400.
L'API propose le mode consultant général. Le mode répondeur automatique qui fonctionne dans le CRM de l'espace personnel ne peut pas être activé de l'extérieur.
Envoyer un message
curl -X POST https://developers.grem.capital/api/v1/chat/messages \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{"sessionId":"SESSION_ID","text":"How much is a 2-room flat in Podil?","clientMessageId":"msg-0001"}'
clientMessageId- votre identifiant de message obligatoire. Un même identifiant reçoit une seule réponse et n'est facturé qu'une fois - réutilisez-le lors d'une nouvelle tentative ; c'est l'Idempotency-Keydu chat.style(facultatif) - longueur de la réponse :short,normaloudetailed.
La réponse n'est qu'un accusé de réception ; la réponse de l'assistant arrive par le flux.
Réponse en streaming
GET /chat/stream?sessionId=SESSION_ID
Authorization: Bearer gsk_live_xxx
Accept: text/event-stream
La connexion est de longue durée ; les événements arrivent au fur et à mesure de la génération de la réponse :
| Événement | Signification |
|---|---|
assistant.started | l'assistant a commencé à répondre |
assistant.delta | le morceau de texte suivant, dans delta |
assistant.done | la réponse est complète, le texte intégral se trouve dans text |
Si la connexion est coupée, reconnectez-vous avec le même sessionId : le serveur renvoie la réponse en cours depuis le début. Donc, à la réception de assistant.started, effacez le texte accumulé pour ce message, sinon il sera dupliqué.
Historique
GET /chat/history?sessionId=SESSION_ID&limit=50 - les messages enregistrés de la session, du plus ancien au plus récent. limit de 1 à 200 (50 par défaut) ; pour la page suivante - cursor avec le nextCursor de la réponse précédente. Utilisez-le pour restaurer la conversation après un rechargement de votre interface.
Facturation
| Action | Facturation |
|---|---|
POST /chat/messages | appel d'API + prix du message |
POST, PATCH, DELETE sur les sessions | appel d'API |
GET liste, historique, flux | gratuit |
Le forfait Free comporte une limite quotidienne de messages. Une fois atteinte, vous recevez 429 - continuez demain ou changez de forfait. La réponse contient code: free_daily_limit et Retry-After jusqu'à 00:00 UTC, heure à laquelle la limite est réinitialisée.
Voir aussi
- SDK TypeScript - un client prêt à l'emploi qui prend en charge le flux.
- Limites et facturation
- Erreurs