Team-Chat-API

Mit dem Team-Chat schreiben sich Ihre Mitarbeiter direkt oder in Gruppen — mit Dateien, Erwähnungen und Bezug auf ein Kundengespräch. Das Dashboard und unsere App nutzen genau die Endpunkte auf dieser Seite. Basis-URL wie bei der übrigen API: https://api.silentchat.de/api

Zugang

• Ab dem ersten bezahlten Tarif enthalten. Ohne Team-Chat im Tarif antwortet jeder Endpunkt mit 403 ERR_FEATURE_NOT_AVAILABLE.
• Nur mit dem Zugangstoken eines angemeldeten Nutzers (Authorization: Bearer …). API-Schlüssel werden abgewiesen, denn der Team-Chat gehört immer einer Person.
• Lite-Sitze dürfen lesen und ihren Lesestand setzen, aber nicht schreiben, anlegen oder verwalten.
• Einen Chat sieht nur, wer Mitglied ist — auch Administratoren lesen keine fremden Direktnachrichten. Für alle anderen antwortet ein Chat wie ein nicht vorhandener (404).

Endpunkte

Alle Pfade relativ zur Basis-URL. Personen erscheinen in Antworten nur als { id, display_name, avatar_url }.

Blättern

Listen liefern data und pagination. Solange hasMore wahr ist, holen Sie die nächste Seite mit cursor aus der letzten Antwort. Ein manipulierter Cursor ergibt 400 ERR_INVALID_CURSOR.

GET /api/v1/team-chat/channels/:id/messages?limit=50&cursor=<token>

200 → {
  "data": [ { "id": "…", "content": "…", "created_at": "2026-09-17T09:04:00Z", … } ],
  "pagination": { "cursor": "eyJhdCI6…", "hasMore": true }
}

Nachrichten

Eine Nachricht braucht Text, Anhänge oder einen Bezug auf ein Kundengespräch — mindestens eines davon. Text ist höchstens 10.000 Zeichen lang.

POST /api/v1/team-chat/channels/:id/messages
{
  "content": "<@5f0c6b1e-3a1d-4c55-9a1e-2b7d0c1e4f10> can you take this one?",
  "conversation_id": "…",   // optional
  "file_ids": ["…"]         // optional, max. 10
}

201 → { "message": { "id": "…", "mentions": ["5f0c6b1e-…"], "attachments": [ … ], … } }

• Erwähnungen stehen im Text als <@nutzer-id>. Gezählt werden nur Mitglieder des Chats; die Antwort nennt sie in mentions. Anzeigen sollten Sie den Namen der Person.
• conversation_id verweist auf ein Kundengespräch Ihres Kontos; ein fremdes ergibt 400 ERR_INVALID_CONVERSATION.
• Bearbeiten geht 15 Minuten lang, Löschen jederzeit. Gelöschte Nachrichten liefern removed_at und keinen Inhalt mehr.
• Text wird nie als HTML ausgewertet. Zeigen Sie ihn als reinen Text an.

Anhänge

1. Upload anfordern: POST /api/v1/files/upload mit Dateiname, Typ und Größe — ohne conversation_id.
2. Die Datei per PUT an die zurückgegebene upload_url schicken.
3. Beim Senden die file_ids mitgeben (höchstens 10). Erst jetzt prüfen wir den tatsächlichen Inhalt gegen den angegebenen Typ; höchstens 20 MB je Datei.
4. Zum Anzeigen oder Herunterladen einen Link über GET /api/v1/team-chat/files/:id holen. Er gilt knapp eine Stunde (expires_at).

POST /api/v1/files/upload
{ "filename": "screenshot.png", "mime_type": "image/png", "size": 48213 }
201 → { "file": { "id": "…" }, "upload_url": "https://…" }

PUT <upload_url>            (Content-Type: image/png, body = file)

POST /api/v1/team-chat/channels/:id/messages
{ "content": "", "file_ids": ["…"] }

GET /api/v1/team-chat/files/:file_id?download=true
200 → { "file": { "url": "https://…", "expires_at": "…", "filename": "…", "mime_type": "…", "size": 48213 } }

Der allgemeine Endpunkt /api/v1/files/:id/download liefert Team-Anhänge nicht aus. Hochgeladene Dateien, die binnen 24 Stunden an keine Nachricht gehängt werden, räumen wir weg.

Echtzeit

Über die WebSocket-Verbindung des Dashboards (Nutzertoken) treten Sie dem Raum team:<id> bei — nur als Mitglied. Neue Chats und Ungelesen-Stände kommen zusätzlich über Ihren persönlichen Nutzerraum.

Benachrichtigungen

Direktnachrichten und Erwähnungen in Gruppen lösen das Ereignis team.message aus — als Eintrag in der Glocke, als Einblendung und als Browser-Push, je nach den Einstellungen der Person (GET/PUT /api/v1/me/notification-preferences). Die Metadaten enthalten channel_id und message_id, bei Erwähnungen mention: "true".

Fehlercodes

Alle Fehler folgen dem üblichen Format { "error": …, "code": … } — siehe Fehlercodes.