Chat-Assistent über die API

Zuletzt aktualisiert: 2026-10-034 Min. Lesezeit

Derselbe Berater, der im Kabinett arbeitet, ist aus Ihrer Anwendung erreichbar. Sie legen eine Sitzung an, öffnen den Strom, senden eine Nachricht und erhalten die Antwort in Teilen. Braucht den Bereich tools:chat.

So funktioniert es

Eine Sitzung anlegen - sie hält den Gesprächskontext.
Den Ereignisstrom der Sitzung öffnen.
Eine Nachricht senden.
Die Antwort kommt in Teilen über den Strom, bis sie vollständig ist.

Öffnen Sie den Strom bevor Sie die Nachricht senden, sonst verpassen Sie die ersten Teile der Antwort.

Sitzungen

Anfrage	Was sie tut
`POST /chat/sessions`	eine Sitzung anlegen
`GET /chat/sessions`	Ihre Sitzungen: `limit` 1-50 (Standard 20, mehr ist `400`), `cursor`, `q` (Suche in Titeln), `projectId`, `archivedOnly`, `sort` (`recent`, `title`)
`PATCH /chat/sessions/{id}`	eine Sitzung ändern; mindestens ein Feld
`DELETE /chat/sessions/{id}`	archivieren

Body von POST /chat/sessions (alles optional):

Feld	Beschreibung
`title`	Name der Sitzung, bis 200 Zeichen
`projectId`	Projekt, zu dem die Sitzung gehört
`mode`	`chat_consult` (Standard); jeder andere Wert wird durch `chat_consult` ersetzt

Felder von PATCH /chat/sessions/{id}:

Feld	Beschreibung
`title`	neuer Name, bis 200 Zeichen
`projectId`	in ein Projekt verschieben; `null` - aus dem Projekt nehmen
`isPinned`	anheften oder lösen
`isUnread`	als ungelesen oder gelesen markieren
`isArchived`	nur `false` - eine archivierte Sitzung wiederherstellen; archivieren mit `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":"Kundenfrage zur Hypothek"}'

Die Antwort enthält sessionId - übergeben Sie sie bei jedem folgenden Aufruf. Zum Anlegen einer Sitzung muss das Kontoprofil ausgefüllt sein; sonst - 400.

Die API bietet den allgemeinen Beratermodus. Der Modus Auto-Antwort, der im CRM des Kabinetts arbeitet, lässt sich von außen nicht einschalten.

Eine Nachricht senden

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":"Was kostet eine 2-Zimmer-Wohnung in Podil?","clientMessageId":"msg-0001"}'

clientMessageId - Ihre Pflicht-ID der Nachricht. Dieselbe ID wird einmal beantwortet und einmal berechnet - verwenden Sie sie bei Wiederholungen erneut; das ist der Idempotency-Key des Chats.
style (optional) - Antwortlänge: short, normal oder detailed.

Die Antwort ist nur eine Bestätigung; die Antwort des Assistenten kommt über den Strom.

Antwortstrom

GET /chat/stream?sessionId=SESSION_ID
Authorization: Bearer gsk_live_xxx
Accept: text/event-stream

Die Verbindung ist langlebig; Ereignisse kommen, während die Antwort entsteht:

Ereignis	Bedeutung
`assistant.started`	der Assistent hat mit der Antwort begonnen
`assistant.delta`	das nächste Textstück, in `delta`
`assistant.done`	die Antwort ist vollständig, der ganze Text steht in `text`

Bricht die Verbindung ab, verbinden Sie sich mit derselben sessionId neu: Der Server spielt die aktuelle Antwort von vorn ab. Leeren Sie deshalb bei assistant.started den für diese Nachricht gesammelten Text, sonst verdoppelt er sich.

Verlauf

GET /chat/history?sessionId=SESSION_ID&limit=50 - die gespeicherten Nachrichten der Sitzung, älteste zuerst. limit 1 bis 200 (Standard 50); die nächste Seite - cursor mit nextCursor aus der vorherigen Antwort. Damit stellen Sie das Gespräch nach einem Neuladen Ihrer Oberfläche wieder her.

Abrechnung

Aktion	Berechnung
`POST /chat/messages`	API-Aufruf + Nachrichtenpreis
`POST`, `PATCH`, `DELETE` auf Sitzungen	API-Aufruf
`GET` Liste, Verlauf, Strom	kostenlos

Im Tarif Free gilt ein Tageslimit für Nachrichten. Danach kommt 429 - machen Sie morgen weiter oder wechseln Sie den Tarif. Die Antwort enthält code: free_daily_limit und Retry-After bis 00:00 UTC, wenn das Limit zurückgesetzt wird.