---
title: "Connect via WebSocket"
method: GET
path: "/api/realtime/websocket"
tags: ["Realtime"]
---

# Connect via WebSocket

`GET /api/realtime/websocket`

## Request

- Base URL: `https://core.blink.new`
- URL: `https://core.blink.new/api/realtime/websocket`
- Auth: none required

Establish a persistent WebSocket connection for real-time bi-directional
messaging. The HTTP GET request is upgraded to the WebSocket protocol (RFC 6455).

Pass `project_id` as a query parameter. Connections without a valid project ID are closed with code 1008.

All frames are JSON-encoded with a `type` and `payload` field. After connecting, the server sends a `connected` message.

**Client → Server message types:**
| type | description |
|------|-------------|
| `subscribe` | Subscribe to a channel. Payload: `{ channel, userId?, metadata?, lastMessageId? }` |
| `unsubscribe` | Unsubscribe from a channel. Payload: `{ channel }` |
| `publish` | Publish a message to a channel. Payload: `{ channel, type, data, userId?, metadata? }` (max 4 KB) |
| `presence_update` | Update presence metadata. Payload: `{ channel, userId, metadata? }` |
| `ping` | Keepalive — refreshes presence TTL. Server replies with `pong`. |

**Server → Client message types:**
| type | description |
|------|-------------|
| `connected` | Sent immediately after handshake with `{ socketId, projectId, timestamp }` |
| `subscribed` | Confirms channel subscription |
| `unsubscribed` | Confirms channel unsubscription |
| `published` | Confirms message was stored and broadcast |
| `message` | Incoming message from any subscriber of the channel |
| `presence` | Presence update — `data.users` contains the current user list |
| `presence_updated` | Confirms own presence update |
| `pong` | Response to `ping` |
| `error` | Error notification with `{ error, timestamp }` |

**Limits:** Max 50 channels per connection. Data payload max 4 KB.
High-frequency presence/stats/typing/cursor messages are coalesced over a
50 ms window; chat messages are always delivered in order.

## Query parameters

- `project_id` string, required

## Other responses

- `101`: WebSocket upgrade successful — connection is now open
- `400`: Missing or invalid `project_id` — connection closed with code 1008

---

[API](https://skmtc.dev/blink/apis/blink-apis.md) - [All operations](https://skmtc.dev/blink/apis/blink-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/blink/apis/blink-apis/revisions/4c59c706078e?raw)