Realtime Connections

Convor uses Centrifugo for realtime delivery. Realtime authentication is separate from normal REST authorization:

• a connection token identifies the client opening the realtime transport;
• a subscription token authorizes one private channel;
• server-side channel checks enforce organization and visitor ownership.

The official dashboard and widget implement this protocol. Prefer those clients unless you are building a reviewed first-party extension.

Operator connection flow

The dashboard uses its authenticated operator session to call:

GET /api/realtime/token

The response contains:

{
  "token": "<connection-jwt>",
  "url": "<configured-websocket-url>",
  "expiresIn": 3600
}

Connect to the returned url with the returned token. Do not hardcode a WebSocket host from documentation or infer it from api.convor.io; the runtime configuration is authoritative.

The operator connection token expires after one hour. Refresh it before expiry and reconnect using the replacement token.

Visitor connection flow

The widget obtains a one-hour visitor token from POST /api/auth/visitor-token. That token identifies the visitor and organization and is used as the realtime connection token as well as the bearer credential for visitor-scoped HTTP requests.

The official widget refreshes the visitor token shortly before expiry, reconnects with jitter after transient failures, and keeps the same anonymous visitor when a reusable visitor handle is available.

See Widget Bootstrap and Visitor Identity for the complete visitor trust flow.

Private channel subscriptions

Connection tokens do not grant every tenant channel. A client requests a channel-specific JWT from:

POST /api/realtime/subscribe-token

{
  "channelId": "org:<orgId>:conv:<conversationId>"
}

The returned JWT is bound to the requesting principal and exactly one channel. Convor verifies the channel belongs to the authenticated organization before issuing it.

Supported tenant channel families include:

Visitors can subscribe only to their own visitor and conversation channels. Operator-only channels reject visitor principals. A channel whose organization prefix does not match the authenticated organization is rejected.

Reconnection behavior

A resilient client should:

1. refresh the connection token before it expires;
2. reconnect with bounded exponential backoff and jitter;
3. request fresh subscription tokens after reconnecting;
4. resubscribe only to channels still required by the current UI state;
5. release subscriptions when the conversation, visitor, or component is no longer active;
6. treat authorization failures as terminal until identity or tenant state changes.

Do not put connection or subscription JWTs in URLs, analytics events, logs, or persistent browser storage.

Publishing, presence, and history

The server has authenticated realtime endpoints for publishing, presence, history, and subscription-token issuance. Their authorization rules are channel-specific and may return a safe empty fallback when Centrifugo presence or history is temporarily unavailable.

These routes support Convor's first-party clients and are not a replacement for the customer REST resources or outbound webhooks. For external automation, use the public API reference and outbound webhooks.

Centrifugo proxy callbacks

Routes under /api/centrifugo/*, including connect, disconnect, subscribe, publish, and refresh callbacks, are Centrifugo-to-Convor infrastructure callbacks. They validate lifecycle events and channel permissions for the realtime server.

They are not public customer API endpoints, must not appear in the generated customer reference, and should never be called directly by a browser, integration, or organization API-key client. Configure Centrifugo to call them through the deployment's trusted proxy configuration; application clients use connection and subscription tokens instead.