REST-API-Referenz

Die SilentChat REST-API ermöglicht den programmatischen Zugriff auf und die Verwaltung aller Plattformressourcen. Alle Endpunkte sind versioniert und geben JSON zurück.

Übersicht

Basis-URL

https://api.silentchat.de/api

Versionierung

Alle Endpunkte liegen unter /api/v1/. Wenn Breaking Changes eingeführt werden, wird ein neues Versionspräfix veröffentlicht und die alte Version mit sechs Monaten Vorlaufzeit abgekündigt.

Content-Type

Senden Sie alle Anfrage-Bodies als JSON mit dem Header Content-Type: application/json.

Authentifizierung

Vollständige Details finden Sie im Authentifizierungshandbuch. Jeder Endpunkt (sofern nicht als öffentlich markiert) erfordert entweder ein gültiges JWT-Bearer-Token oder einen X-API-Key-Header.

Authentifizierung

Method	Path	Description
`POST`	`/v1/auth/register`	Authentifizierung mit E-Mail und Passwort. Gibt Access- und Refresh-Token zurück.
`POST`	`/v1/auth/login`	Authentifizierung mit E-Mail und Passwort. Gibt Access- und Refresh-Token zurück.
`POST`	`/v1/auth/refresh`	Tauscht ein Refresh-Token gegen ein neues Access-Token.
`POST`	`/v1/auth/logout`	Invalidiert das aktuelle Refresh-Token.
`POST`	`/v1/auth/verify-email`	Gibt das Profil des authentifizierten Benutzers zurück.
`POST`	`/v1/auth/forgot-password`	Gibt das Profil des authentifizierten Benutzers zurück.
`POST`	`/v1/auth/reset-password`	Gibt das Profil des authentifizierten Benutzers zurück.

Tenants

Method	Path	Description
`POST`	`/v1/tenants`	Gibt die Tenant-Details des authentifizierten Benutzers zurück.
`GET`	`/v1/tenants/:id`	Gibt die Tenant-Details des authentifizierten Benutzers zurück.
`PATCH`	`/v1/tenants/:id`	Aktualisiert Tenant-Einstellungen (Name, Zeitzone usw.).
`GET`	`/v1/tenants/:id/members`	Gibt die Tenant-Details des authentifizierten Benutzers zurück.
`POST`	`/v1/tenants/:id/members`	Aktualisiert Tenant-Einstellungen (Name, Zeitzone usw.).
`DELETE`	`/v1/tenants/:id/members/:userId`	Aktualisiert Tenant-Einstellungen (Name, Zeitzone usw.).

Unterhaltungen

Method	Path	Description
`GET`	`/v1/conversations`	Listet Unterhaltungen für den Tenant mit optionalen Filtern und Cursor-Paginierung auf.
`GET`	`/v1/conversations/:id`	Gibt eine einzelne Unterhaltung anhand der ID zurück.
`PUT`	`/v1/conversations/:id`	Ändert Status, Priorität oder Betreff. Status „closed“ schließt die Unterhaltung wie /close, „open“ öffnet eine geschlossene wieder wie /reopen.
`POST`	`/v1/conversations/:id/assign`	Weist die Unterhaltung einem Mitglied Ihres Teams zu.
`POST`	`/v1/conversations/:id/transfer`	Übergibt eine offene Unterhaltung an eine Kollegin, einen Kollegen oder eine Abteilung.
`POST`	`/v1/conversations/:id/close`	Schließt eine Unterhaltung (Systemnachricht, Zufriedenheitsabfrage, Workflows). Nachrichten bleiben erhalten.
`POST`	`/v1/conversations/:id/reopen`	Öffnet eine geschlossene Unterhaltung wieder — offen und nicht zugewiesen.

Übergeben und wieder öffnen

Beide Aktionen brauchen ein Nutzer-Token (JWT) mit Schreibrecht auf Unterhaltungen. Mit einem API-Schlüssel werden sie abgewiesen, ebenso für Lite-Sitze.

Übergeben

Im Body genau ein Ziel: user_id (Person) oder department_id (Abteilung). Bei einer Abteilung wählt SilentChat ein aktives Mitglied, bevorzugt eines, das gerade online ist. note ist optional (höchstens 2.000 Zeichen) und wird als interne Notiz gespeichert. Die Unterhaltung steht danach auf „assigned“; die Empfängerin oder der Empfänger wird benachrichtigt, der Besucher erhält einen kurzen Hinweis ohne Namen.

POST /api/v1/conversations/:id/transfer
Authorization: Bearer <token>
Content-Type: application/json

{ "user_id": "<uuid>", "note": "…" }
// oder / or: { "department_id": "<uuid>" }

200 → { "message": "Conversation transferred", "conversation": { … } }

Wieder öffnen

Ohne Body. Die Unterhaltung steht danach auf „open“ und ist nicht zugewiesen; der Zustand des KI-Bots bleibt unverändert. Der Besucher erhält einen kurzen Hinweis.

POST /api/v1/conversations/:id/reopen
Authorization: Bearer <token>

200 → { "conversation": { "status": "open", "assigned_user_id": null, … } }

Fehlercodes

Code	Description
`ERR_TRANSFER_TARGET`	Kein oder mehr als ein Ziel angegeben.
`ERR_USER_NOT_IN_TENANT`	Die Person ist kein aktives Mitglied Ihres Teams.
`ERR_ASSIGNEE_LITE_SEAT`	Die gewählte Person hat einen Lite-Zugang und darf keine Gespräche bearbeiten (assign und transfer).
`ERR_INVALID_DEPARTMENT`	Die Abteilung gehört nicht zu Ihrem Konto.
`ERR_DEPARTMENT_NO_AGENTS`	In der Abteilung ist niemand, der übernehmen kann (409).
`ERR_CONVERSATION_CLOSED`	Die Unterhaltung ist geschlossen — erst wieder öffnen (409).
`ERR_CONVERSATION_NOT_CLOSED`	Nur eine geschlossene Unterhaltung kann wieder geöffnet werden (409).

Echtzeit-Ereignisse über den WebSocket: conversation.transferred (conversation_id, assigned_user_id, department_id) und conversation.reopened (conversation_id). Für eine Auswahlliste liefert GET /api/v1/team/members?include=presence je Mitglied zusätzlich presence (online, away, offline) und open_conversations.

Nachrichten

Method	Path	Description
`GET`	`/v1/messages/:conversation_id`	Listet die Nachrichten einer Unterhaltung auf (seitenweise).
`POST`	`/v1/messages`	Sendet eine Nachricht in eine Unterhaltung (conversation_id und content im Body).
`POST`	`/v1/messages/:conversation_id/read`	Markiert die Nachrichten einer Unterhaltung als gelesen.

Besucher

Method	Path	Description
`GET`	`/v1/visitors`	Listet Besucher auf, die sich aktuell auf überwachten Domains befinden.
`GET`	`/v1/visitors/:id`	Gibt Details zu einem einzelnen Besucher zurück.

Kontakte

Method	Path	Description
`GET`	`/v1/contacts`	Listet Kontakte mit optionaler Suche und Cursor-Paginierung auf.
`POST`	`/v1/contacts`	Erstellt einen neuen Kontakt.
`GET`	`/v1/contacts/:id`	Gibt einen einzelnen Kontakt anhand der ID zurück.
`PATCH`	`/v1/contacts/:id`	Aktualisiert Kontaktdaten.
`DELETE`	`/v1/contacts/:id`	Löscht einen Kontakt.

Widgets

Method	Path	Description
`GET`	`/v1/widgets`	Listet alle Widgets des Tenants auf.
`POST`	`/v1/widgets`	Erstellt ein neues Widget.
`GET`	`/v1/widgets/:id`	Gibt ein einzelnes Widget anhand der ID zurück.
`PATCH`	`/v1/widgets/:id`	Aktualisiert Widget-Einstellungen.
`DELETE`	`/v1/widgets/:id`	Löscht ein Widget.

Domains

Method	Path	Description
`GET`	`/v1/domains`	Listet die für ein Widget erlaubten Domains auf.
`POST`	`/v1/domains`	Fügt eine neue erlaubte Domain zu einem Widget hinzu.
`DELETE`	`/v1/domains/:id`	Entfernt eine erlaubte Domain von einem Widget.

Gespeicherte Antworten

Method	Path	Description
`GET`	`/v1/canned-responses`	Listet gespeicherte Antworten auf.
`POST`	`/v1/canned-responses`	Erstellt eine neue gespeicherte Antwort.
`PATCH`	`/v1/canned-responses/:id`	Aktualisiert eine gespeicherte Antwort.
`DELETE`	`/v1/canned-responses/:id`	Löscht eine gespeicherte Antwort.

Dateien

Method	Path	Description
`POST`	`/v1/files`	Lädt einen Dateianhang hoch (max. 20 MB).
`GET`	`/v1/files/:id`	Gibt eine vorausgehend signierte Download-URL für eine Datei zurück.

Abrechnung

Method	Path	Description
`GET`	`/v1/billing/subscription`	Gibt das aktuelle Abonnement und die Nutzung zurück.
`POST`	`/v1/billing/checkout`	Erstellt eine Stripe-Abrechnungsportal-Sitzungs-URL.
`POST`	`/v1/billing/portal`	Erstellt eine Stripe-Abrechnungsportal-Sitzungs-URL.
`GET`	`/v1/billing/invoices`	Gibt das aktuelle Abonnement und die Nutzung zurück.
`GET`	`/v1/billing/usage`	Gibt das aktuelle Abonnement und die Nutzung zurück.

Beispielanfrage & Antwort

Die SilentChat REST-API ermöglicht den programmatischen Zugriff auf und die Verwaltung aller Plattformressourcen. Alle Endpunkte sind versioniert und geben JSON zurück.

Anfrage

GET /v1/conversations?status=open&limit=10 HTTP/1.1
Host: api.silentchat.de
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
X-Tenant-ID: tn_abc123

Antwort

{
  "data": [
    {
      "id": "conv_01HXYZ",
      "status": "open",
      "visitor_id": "vis_9f2c4e1a",
      "assigned_to": "usr_d4e5f6",
      "last_message": "Hi, I have a question about pricing.",
      "last_message_at": "2025-10-12T14:32:00Z",
      "created_at": "2025-10-12T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}