Realtime-eventcontract

Authenticatiegrens

Socket.IO is het transport voor browser en mobiele apps, geen API-key-endpoint. Bearer-API-keys worden geweigerd. Agents gebruiken hun sessie; bezoekers het door de widget uitgegeven bezoekerstoken. Origin en organisatie-/gesprekstoegang worden gecontroleerd bij verbinden en abonneren. Gebruik de REST-integratie-API voor serverintegraties; gebruik een bezoekerstoken nooit als agentcredential.

Client-events

site.subscribe ontvangt een widget-/historisch website-ID en bevestigt { ok: true } of { ok: false }. Alleen agentsessies; abonneert op de widgetaliassen van de organisatie. site.unsubscribe verwijdert dat abonnement.

conversation.subscribe ontvangt een gesprek-ID en bevestigt { ok: true } of { ok: false }. Bezoekers kunnen alleen op hun eigen gesprek abonneren; agents hebben organisatietoegang nodig. conversation.unsubscribe ontvangt hetzelfde ID.

presence.subscribe ontvangt maximaal 100 gesprek-ID’s, vervangt het vorige presence-abonnement en bevestigt { ok: true } of { ok: false }. Alleen agentsessies; elk gesprek wordt geautoriseerd.

typing ontvangt { conversationId, typing: boolean }. Geautoriseerde ontvangers krijgen { conversationId, kind: "agent" | "visitor", typing: boolean }. Voor typing is geen duurzame aflevering beloofd.

Server-events

message.created levert de berichtweergave; conversation.updated de geautoriseerde gespreksweergave. Privénotities gaan uitsluitend naar agentrooms en bezoekersweergaven bevatten geen interne AI-velden. presence bevat beschikbaarheid van agents; conversation.presence bevat bezoekerpresence voor het gesprek. Presence is tijdelijk en gebaseerd op leases, geen bewijs dat een klant een bericht heeft gelezen.

Opnieuw verbinden en herstellen

Herstel abonnementen na opnieuw verbinden en laad opgeslagen berichten via de geauthenticeerde HTTP-API. Ga niet uit van precies één aflevering: ontdubbel op bericht-ID en synchroniseer gespreksstatus. Een geweigerd abonnement is geen leeg gesprek. Intrekken van een sessie of verlies van toegang verbreekt de socket. Log nooit sessiecookies of bezoekerstokens.

Payloadvelden

message.created bevat _id, conversationId, senderType, body, internal en createdAt, plus attachments met id, filename, contentType en size. conversation.created en conversation.updated bevatten _id, status en lastMessageAt; agentweergaven kunnen contact, tags, assigneeId en unreadCount bevatten. Behandel optionele velden als optioneel en negeer nieuwe velden.

conversation.read en conversation.delivered bevatten conversationId, kind en deliveredAt; read-events bevatten ook readAt. Tijden zijn ISO-tijdstempels wanneer aanwezig. presence bevat websiteId, status (online/offline/unknown), online (boolean of null) en optioneel lastSeenAt. conversation.presence heeft dezelfde presencevelden met conversationId in plaats van websiteId. Aflever- en leesbevestigingen staan los van socketverbinding en typestatus.