Anfrage-Referenz
Felder, Antworten und Statuscodes für die Session- und Chat-Endpunkte.
Beide Endpunkte werden in Anwendungs-Endpunkte erzählerisch beschrieben; diese Seite ist die überfliegbare Referenz für ihre genauen Felder und Statuscodes.
Eine Session erstellen
Request-Body
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
userId | string | Ja | Deine eigene Kennung für diese Session. Wird nirgends nachgeschlagen. |
Antwort — 201 Created
| Feld | Typ | Beschreibung |
|---|---|---|
sessionId | string | Identifiziert die Session. Wird in jedem folgenden Chat-Aufruf verwendet. |
userId | string | Gibt die gesendete userId zurück. |
sessionSecret | string | Erforderlicher Header-Wert für jeden Chat-Aufruf dieser Session. |
createdAt | string | ISO-8601-Zeitstempel. |
initialMessage | string | Die konfigurierte Initial Message der Anwendung. |
Statuscodes
| Status | Bedeutung |
|---|---|
201 | Session erstellt. |
400 | userId fehlt im Request-Body. |
401 | Weder Authorization noch X-Api-Key wurde gesendet, oder der API-Schlüssel ist unbekannt. |
404 | Der API-Schlüssel ist gültig, gehört aber nicht zum Konto dieser Anwendung. |
Eine Chat-Nachricht senden
Request-Body
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
sessionId | string | Ja | Aus der Antwort des Session-Endpunkts. |
message | string | Ja | Die Nachricht des Nutzers. |
Header
Siehe Authentifizierung
für Authorization/X-Api-Key, und
Session-Endpunkt für
x-session-secret.
Antwort — 200 OK, Content-Type: text/event-stream
Ein Stream typisierter Ereignisse, siehe Der Antwort-Stream.
Statuscodes
| Status | Bedeutung |
|---|---|
200 | Der Stream hat begonnen. Fehler, die danach auftreten, kommen als error-Ereignis im Stream an, nicht als HTTP-Status. |
400 | sessionId oder message fehlt im Request-Body. |
401 | Weder Authorization noch X-Api-Key wurde gesendet, oder der API-Schlüssel ist unbekannt. |
404 | x-session-secret fehlt oder stimmt nicht mit der Session überein, oder die sessionId existiert nicht mehr oder ist abgelaufen. Derselbe Status deckt alle drei Fälle ab, absichtlich, damit eine Anfrage nicht genutzt werden kann, um nach gültigen Session-IDs zu suchen. |
Ein 404 vom Chat-Endpunkt unterscheidet absichtlich nicht zwischen einem
falschen Secret und einer abgelaufenen Session. Siehst du einen, ist die
sichere Wiederherstellung immer dieselbe: Rufe den Session-Endpunkt
erneut auf und starte eine neue Session.
Eine Session vorzeitig beenden
Sessions laufen von selbst nach 1 Stunde ab, du kannst aber eine schon vorher löschen:
Erfordert denselben Authorization-/X-Api-Key-Header wie die anderen
Endpunkte.
| Status | Bedeutung |
|---|---|
204 | Session gelöscht. |
401 | Weder Authorization noch X-Api-Key wurde gesendet, oder der API-Schlüssel ist unbekannt. |
404 | Die sessionId existiert nicht. |
Form der Fehlerantwort
Jeder Fehler, ob Authentifizierungsfehler, Validierungsfehler oder eine nicht gefundene Session, kommt mit derselben Form zurück:
Verwende den HTTP-Statuscode, um nach der Art des Fehlers zu unterscheiden,
und message für eine menschenlesbare Beschreibung.