From f1c2dddafb2a1c1f3b83f63abded5dc8aebaa0cb Mon Sep 17 00:00:00 2001
From: abc3 <sts@abc3.dev>
Date: Mon, 13 Feb 2023 20:27:05 +0100
Subject: [PATCH] add presence description

---
 apps/docs/pages/guides/realtime/protocol.mdx | 60 ++++++++++++++++----
 1 file changed, 49 insertions(+), 11 deletions(-)

diff --git a/apps/docs/pages/guides/realtime/protocol.mdx b/apps/docs/pages/guides/realtime/protocol.mdx
index 3d211079aa8..2812ddc0165 100644
--- a/apps/docs/pages/guides/realtime/protocol.mdx
+++ b/apps/docs/pages/guides/realtime/protocol.mdx
@@ -3,10 +3,14 @@ import Layout from '~/layouts/DefaultGuideLayout'
 export const meta = {
   id: 'protocol',
   title: 'Realtime Protocol',
-  description: "Understanding Realtime Protocol",
+  description: 'Understanding Realtime Protocol',
 }
 
-The Realtime Protocal is a set of message formats that you send and receive from the Realtime server.
+## Introduction
+
+The Realtime Protocol is a set of message formats used for communication between a Realtime client and server. These messages are used to initiate a connection, update access tokens, receive system status updates, and receive real-time updates from the Postgres database.
+
+The Realtime Protocol is a set of message formats that you send and receive from the Realtime server.
 
 ## Connection
 
@@ -70,7 +74,7 @@ The body of the `payload.message` can be "Subscribed to PostgreSQL" or "Subscrib
 ```typescript
 {
    "event": "system",
-   "topic": string,   
+   "topic": string,
    "payload":{
       "channel": "any",
       "extension": "postgres_changes",
@@ -87,7 +91,7 @@ The heartbeat message should be sent every 60 seconds to avoid a connection time
 
 ```typescript
 {
-   "event": "heartbeat",   
+   "event": "heartbeat",
    "topic": "phoenix",
    "payload": {},
    "ref": string
@@ -98,10 +102,9 @@ The heartbeat message should be sent every 60 seconds to avoid a connection time
 
 To update the access token, you need to send to the server a message specifying a new token in the `payload.access_token` value.
 
-
 ```typescript
 {
-   "event": "access_token",   
+   "event": "access_token",
    "topic": string,
    "payload":{
       "access_token": string
@@ -117,14 +120,14 @@ Realtime sends a message with the following structure
 ```typescript
 {
    "event": "postgres_changes",
-   "topic": string,   
+   "topic": string,
    "payload": {
-      "data": { 
+      "data": {
          "columns": Array<{name: string, type: string}>,
          "commit_timestamp": string,
          "errors": null | string,
-         "old_record": {"id": number | string}, 
-         "record": {[key: string]: boolean | number | string | null}, 
+         "old_record": {"id": number | string},
+         "record": {[key: string]: boolean | number | string | null},
          "type": "*" | "INSERT" | "UPDATE" | "DELETE",
          "schema": string,
          "table": string
@@ -150,4 +153,39 @@ Structure of the broadcast event
    },
    "ref": null
 }
-```
\ No newline at end of file
+```
+
+## Presence message
+
+The Presence events allow clients to monitor the online status of other clients in real-time.
+
+### State Update
+
+After joining, the server sends a `presence_state` message to a client with presence information. The payload field contains keys in UUID format, where each key represents a client and its value is a JSON object containing information about that client.
+
+```typescript
+{
+   "event": "presence_state",
+   "topic": string,
+   "payload": {
+      [key: string]: {metas: Array<{phx_ref: string, name: string, t: float}>}
+   },
+   "ref": null
+}
+```
+
+### Diff Update
+
+After a change to the presence state, such as a client joining or leaving, the server sends a presence_diff message to update the client's view of the presence state. The payload field contains two keys, `joins` and `leaves`, which represent clients that have joined and left, respectively. The values associated with each key are UUIDs of the clients.
+
+```typescript
+{
+   "event": "presence_diff",
+   "topic": string,
+   "payload": {
+      "joins": {metas: Array<{phx_ref: string, name: string, t: float}>},
+      "leaves": {metas: Array<{phx_ref: string, name: string, t: float}>}
+   },
+   "ref": null
+}
+```