From 724bd24b4f17975f935e4fabe0ad7dbff9593d56 Mon Sep 17 00:00:00 2001
From: benya <benya@daemonlord.ru>
Date: Sun, 8 Mar 2026 20:02:07 +0300
Subject: [PATCH] docs(api): add full realtime websocket protocol section

---
 docs/api-reference.md | 94 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 91 insertions(+), 3 deletions(-)

diff --git a/docs/api-reference.md b/docs/api-reference.md
index 2f45c4b..1660ae9 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -1046,14 +1046,102 @@ Response: `200` + `ChatAttachmentRead[]`
 Auth required.  
 Response: `200` + `NotificationRead[]`
 
-## 11. Global search
+## 11. Realtime WebSocket
+
+### Endpoint
+
+`GET /api/v1/realtime/ws?token=<access_jwt>` (WebSocket upgrade)
+
+Auth:
+
+- token is required in query string
+- invalid/expired token: socket closed with policy violation
+
+### Client -> Server events
+
+```json
+{ "event": "ping", "payload": {} }
+```
+
+```json
+{
+  "event": "send_message",
+  "payload": {
+    "chat_id": 10,
+    "type": "text",
+    "text": "Hello",
+    "client_message_id": "uuid",
+    "reply_to_message_id": null
+  }
+}
+```
+
+```json
+{ "event": "typing_start", "payload": { "chat_id": 10 } }
+```
+
+```json
+{ "event": "typing_stop", "payload": { "chat_id": 10 } }
+```
+
+```json
+{ "event": "recording_voice_start", "payload": { "chat_id": 10 } }
+```
+
+```json
+{ "event": "recording_voice_stop", "payload": { "chat_id": 10 } }
+```
+
+```json
+{ "event": "recording_video_start", "payload": { "chat_id": 10 } }
+```
+
+```json
+{ "event": "recording_video_stop", "payload": { "chat_id": 10 } }
+```
+
+```json
+{ "event": "message_delivered", "payload": { "chat_id": 10, "message_id": 123 } }
+```
+
+```json
+{ "event": "message_read", "payload": { "chat_id": 10, "message_id": 123 } }
+```
+
+### Server -> Client envelope
+
+```json
+{
+  "event": "receive_message",
+  "payload": {},
+  "timestamp": "2026-03-08T10:00:00Z"
+}
+```
+
+Common server events:
+
+- `connect`, `pong`, `error`
+- `receive_message`, `message_updated`, `message_deleted`
+- `typing_start`, `typing_stop`
+- `recording_voice_start`, `recording_voice_stop`
+- `recording_video_start`, `recording_video_stop`
+- `message_delivered`, `message_read`
+- `user_online`, `user_offline`
+- `chat_updated`, `chat_deleted`
+
+Notes:
+
+- on disconnect, server auto-emits activity stop events (`typing_stop`, `recording_*_stop`) for active chat indicators.
+- after revoke-all sessions, realtime connections are force-closed; web client should treat this as logout.
+
+## 12. Global search
 
 ### GET `/api/v1/search?query=<text>&users_limit=10&chats_limit=10&messages_limit=10`
 
 Auth required.  
 Response: `200` + `GlobalSearchRead`
 
-## 12. Rate limits
+## 13. Rate limits
 
 Configured via env vars:
 
@@ -1071,7 +1159,7 @@ Configured via env vars:
 }
 ```
 
-## 13. Notes
+## 14. Notes
 
 - `public_id` is returned for chats and should be used by clients as stable public identifier.
 - Invite links are generated for group/channel chats.