Overview
The WebSocket transport binding is the primary real-time transport for TCF. It uses a simple newline-delimited JSON framing protocol over standard WebSocket connections (ws:// or wss://).
WebSocket Transport v1.0
Connection Handshake
Upon connection, the client sends a connect message:
// Client → Server
{
"type": "connect",
"auth_token": "eyJhbGciOi...",
"supported_versions": ["0.3", "0.4"],
"client_id": "tcf-js-sdk/0.4.0"
}
// Server → Client
{
"type": "connect_ack",
"server_id": "tcf-gateway-prod-01",
"negotiated_version": "0.4",
"session_id": "sess_01JEXM...",
"heartbeat_interval_ms": 30000
}
{
"type": "connect",
"auth_token": "eyJhbGciOi...",
"supported_versions": ["0.3", "0.4"],
"client_id": "tcf-js-sdk/0.4.0"
}
// Server → Client
{
"type": "connect_ack",
"server_id": "tcf-gateway-prod-01",
"negotiated_version": "0.4",
"session_id": "sess_01JEXM...",
"heartbeat_interval_ms": 30000
}
Message Framing
Each TCF message is serialized as a single line of JSON (no pretty printing). Messages are separated by \n (newline). The newline character must not appear within the JSON payload (it must be properly escaped).
// Wire format example
{"tcf_version":"0.4","message_id":"...","content":{"type":"text","body":"Hello"}}
{"tcf_version":"0.4","message_id":"...","content":{"type":"text","body":"World"}}
{"tcf_version":"0.4","message_id":"...","content":{"type":"text","body":"Hello"}}
{"tcf_version":"0.4","message_id":"...","content":{"type":"text","body":"World"}}
Heartbeat / Ping-Pong
Servers may send ping frames. Clients must respond with pong within the heartbeat interval. Failure to respond results in connection termination.
// Server → Client
{"type": "ping", "timestamp": "2026-06-01T12:00:00Z"}
// Client → Server
{"type": "pong", "timestamp": "2026-06-01T12:00:00Z"}
{"type": "ping", "timestamp": "2026-06-01T12:00:00Z"}
// Client → Server
{"type": "pong", "timestamp": "2026-06-01T12:00:00Z"}
Reconnection
Clients should implement exponential backoff reconnection. After reconnecting, the client sends a new connect message with the previous session_id to resume the session and recover missed messages.