Echtzeit-Ereignisvertrag
Socket.IO-Abonnements, Autorisierung und Wiederverbindung.
Zuletzt aktualisiert · 23.10.2026
Authentifizierungsgrenze
Socket.IO ist der Transport für Browser und mobile Apps, kein API-Schlüssel-Endpunkt. Bearer-API-Schlüssel werden abgewiesen. Agenten verwenden ihre Sitzung; Besucher das vom Widget ausgegebene Besuchertoken. Origin und Organisations-/Gesprächszugriff werden beim Verbinden und Abonnieren geprüft. Nutze für Serverintegrationen die REST-Integrations-API; ein Besuchertoken ist niemals ein Agentenzugang.
Client-Ereignisse
site.subscribe erhält eine Widget-/historische Website-ID und bestätigt { ok: true } oder { ok: false }. Nur Agentensitzungen; abonniert die Widget-Aliasse der Organisation. site.unsubscribe entfernt dieses Abonnement.
conversation.subscribe erhält eine Gesprächs-ID und bestätigt { ok: true } oder { ok: false }. Besucher dürfen nur ihr eigenes Gespräch abonnieren; Agenten benötigen Organisationszugriff. conversation.unsubscribe erhält dieselbe ID.
presence.subscribe erhält höchstens 100 Gesprächs-IDs, ersetzt das vorherige Presence-Abonnement und bestätigt { ok: true } oder { ok: false }. Nur Agentensitzungen; jedes Gespräch wird autorisiert.
typing erhält { conversationId, typing: boolean }. Autorisierte Empfänger erhalten { conversationId, kind: "agent" | "visitor", typing: boolean }. Für typing wird keine dauerhafte Zustellung versprochen.
Server-Ereignisse
message.created liefert die Nachrichtenansicht; conversation.updated die autorisierte Gesprächsansicht. Private Notizen gehen nur an Agentenräume; Besucheransichten enthalten keine internen KI-Felder. presence enthält Agentenverfügbarkeit; conversation.presence den Besucherstatus für das Gespräch. Presence ist vorübergehend und leasebasiert, kein Nachweis, dass ein Kunde eine Nachricht gelesen hat.
Wiederverbindung und Wiederherstellung
Abonniere nach einer Wiederverbindung erneut und lade gespeicherte Nachrichten über die authentifizierte HTTP-API. Gehe nicht von exakt einer Zustellung aus: Dedupliziere nach Nachrichten-ID und gleiche den Gesprächsstatus ab. Ein abgewiesenes Abonnement ist kein leeres Gespräch. Sitzungswiderruf oder Zugriffsverlust trennt den Socket. Protokolliere niemals Sitzungscookies oder Besuchertokens.
Payload-Felder
message.created enthält _id, conversationId, senderType, body, internal und createdAt sowie attachments mit id, filename, contentType und size. conversation.created und conversation.updated enthalten _id, status und lastMessageAt; Agentenansichten können contact, tags, assigneeId und unreadCount enthalten. Behandle optionale Felder als optional und ignoriere neue Felder.
conversation.read und conversation.delivered enthalten conversationId, kind und deliveredAt; read-Ereignisse enthalten zusätzlich readAt. Zeiten sind ISO-Zeitstempel, sofern vorhanden. presence enthält websiteId, status (online/offline/unknown), online (boolean oder null) und optional lastSeenAt. conversation.presence hat dieselben Presence-Felder mit conversationId statt websiteId. Zustell- und Lesebestätigungen sind unabhängig von Socket-Verbindung und Tippstatus.