Authentication and presence

Agent authentication

Supply a valid agent-session JWT as auth.token on the /agent connection. The server also accepts an Authorization Bearer header where the client environment supports it. Browser clients should use auth.token. Tokens are validated against the agent’s workspace, suspension and token version.

A rejected connection reports connect_error. Possible messages include unauthorized, workspace_seat_required and onboarding_payment_required. Message Team can also report product_not_assigned. Obtain a fresh session through the supported sign-in flow when needed; do not place a privileged token in public code or a URL.

Availability is a separate setting

The agent’s saved status is independent of whether a socket is connected. Set available, away or offline explicitly. Presence is synchronized through agent:presence-snapshot and agent:status-change; use the server state when multiple tabs are open.

socket.on("agent:presence-snapshot", ({ agents }) => replacePresence(agents));
socket.on("agent:status-change", ({ agentId, status }) => updatePresence(agentId, status));
// Only after the person chooses their availability:
socket.emit("agent:status", { status: "available" });

Revocation and reconnects

Access checks are repeated for protected actions. Seat or product access can be revoked while the client is connected. Handle access:updated by refreshing permissions and stop retrying operations the person can no longer perform.

Use Socket.io’s reconnect support for transient network loss. After reconnecting, request a new queue snapshot and reopen the selected conversation. A server-initiated disconnect requires resolving its cause before reconnecting manually.

Visitor sessions

Website visitors use /widget and visitor:connect with the public site embed ID and their visitor token. Agent-session credentials must never be sent to the widget. Visitor tokens do not grant agent access or verify ownership of a customer account.