diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 28838f64..03abef99 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -340,16 +340,15 @@ Presence allows chat room users to indicate to others that they're online, as we * @(CHA-PR1)@ Presence for a Room is exposed on the realtime channel used for chat messages, in the format @::$chat::$chatMessages@. For example, if your room id is @my-room@ then the presence channel will be @my-room::$chat::$chatMessages@. * @(CHA-PR2)@ The presence payload for Chat is opinionated, so that we may add or change fields later without needing to consider how customers are using presence. -** @(CHA-PR2a)@ @[Testable]@ The presence data format is a JSON object as described below. Customers may specify content of an arbitrary type to be placed in the @userCustomData@ field. +** @(CHA-PR2a)@ @[Testable]@ The presence data format is a JSON object as described below. Customers may specify an arbitrary "JSON @value@":https://www.json.org to be placed in the @userCustomData@ field.
   {
-    "userCustomData": {
-      // Some user specified type, does not have to be object.
-    }
+    "userCustomData": // Any JSON `value`, does not have to be `object`. This field may be absent; see CHA-PR2b.
   }
 
+** @(CHA-PR2b)@ @[Testable]@ If the user performs a presence operation (@CHA-PR3a@, @CHA-PR10a@, or @CHA-PR4a@) without providing any custom data (which, for the sake of clarity, we emphasise is _not_ the same as providing the JSON @value@ of @null@ as custom data, which is handled like any other JSON @value@ per @CHA-PR2a@), then the @userCustomData@ field must be omitted from the @CHA-PR2a@ presence data that gets sent. * @(CHA-PR3)@ Users may enter presence. The behaviour depends on the current room status, as presence operations in a Realtime Client cause implicit attaches. ** @(CHA-PR3a)@ @[Testable]@ Users may choose to enter presence, optionally providing custom data to enter with. The overall presence data must retain the format specified in @CHA-PR2@. ** @(CHA-PR3b)@ This clause has been replaced by @CHA-PR3c - CHA-PR3g@. @@ -373,7 +372,7 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(CHA-PR10f)@ This specification point has been removed. It was superseded by @CHA-PR10h@. ** @(CHA-PR10g)@ This specification point has been removed. It was superseded by @CHA-PR10h@. * @(CHA-PR4)@ Users may leave presence. -** @(CHA-PR4a)@ @[Testable]@ Users may choose to leave presence, which results in them being removed from the Realtime presence set. +** @(CHA-PR4a)@ @[Testable]@ Users may choose to leave presence, which results in them being removed from the Realtime presence set. The user may optionally provide custom data to leave with. The overall presence data must retain the format specified in @CHA-PR2@. * @(CHA-PR5)@ @[Testable]@ It must be possible to query if a given clientId is in the presence set. * @(CHA-PR6)@ @[Testable]@ It must be possible to retrieve all the "@Members":#chat-structs-presence-member of the presence set. The behaviour depends on the current room status, as presence operations in a Realtime Client cause implicit attaches. ** @(CHA-PR6a)@ This clause has been replaced by @CHA-PR6b - CHA-PR6f@. @@ -887,7 +886,7 @@ h3(#chat-structs-presence-member). Presence Member "clientId": "who-sent-the-message", "action": "enter", "updatedAt": DateTime(), - "data": {}, // Whatever the user-provided data is. It must be destructured from the internal format we use. + "data": { … }, // A presence data object containing any user-provided data. The structure of this object is described by CHA-PR2. "extras": { "headers": { "baz": "qux" @@ -903,7 +902,7 @@ h3(#chat-structs-presence-event). Presence Event "clientId": "who-is-in-presence", "action": "enter", "timestamp": DateTime(), - "data": {}, // Whatever the user-provided data is. It must be destructured from the internal format we use. + "data": { … }, // A presence data object containing any user-provided data. The structure of this object is described by CHA-PR2. }