Chat: Update typing indicator API documentation

content/chat/rooms/typing.textile

@@ -72,13 +72,20 @@ The following is the structure of a typing event:
     "clemons",
     "zoranges",
   },
+  "change": {
+    "type": "typing.started",
+    "clientId": "clemons"
+  }
 }
 ```
 
 The following are the properties of a typing event:
 
 |_. Property |_. Description |_. Type |
 | currentlyTyping | A set of all users currently typing. | Set |
+| change | The single change that resulted in the event. | Object |
+| | type: The type of change that occurred. | String |
+| | clientId: The @clientId@ of the user that triggered the change. | String |
 
 You can use the size of the @currentlyTyping@ set to decide whether to display individual user names, or that multiple people are typing in your user interface.
 
@@ -100,7 +107,7 @@ blang[javascript,kotlin].
   ```[javascript]
   // Initial subscription
   const { unsubscribe } = room.typing.subscribe((event) => {
-    console.log(`${event.clientId} is currently typing...`);
+    console.log('Typing event received: ', event);
   });
 
   // To remove the listener
@@ -130,7 +137,15 @@ blang[javascript,swift,kotlin].
 blang[react].
   Use the "@start()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseTypingResponse.html#start method available from the response of the @useTyping@ hook to emit an event when a user has started typing.
 
-There is a timeout associated with start events. A stop event will be automatically emitted after it expires if one isn't received before the timeout. The length of this timeout is customizable using the @timeoutMs@ parameter that can be configured in the @RoomOptions@ that you set when you "create a room":/docs/chat/rooms#create. The default is 10000ms.
+There is a timeout associated with start events. On first calling `start()`, this timer is set, subsequent calls to `start()` before the timer expires will result in a no-op. The length of this timeout is customizable using the @heartbeatThrottleMs@ parameter that can be configured in the @RoomOptions@ that you set when you "create a room":/docs/chat/rooms#create. The default is 10000ms.
+
+Consequently, if you want to keep the typing indicator active, you should call `start()` with each key press to ensure a new typing event is emitted after the timeout has expired.
+
+For a client receiving typing events, the typing indicator they have received will remain active for the duration of the timeout, plus a predefined grace period of 2000ms. If a new typing event is received for the same user before the grace period has expired, the typing indicator will be reset to the full duration of the timeout. For example, if the timeout is 15000ms, the typing indicator will remain active for 12000ms.
+
+<aside data-type='note'>
+<p>It is important for all clients in a room to have the same timeout value set, otherwise the typing indicators may not be displayed correctly.</p>
+</aside>
 
 ```[javascript]
 await room.typing.start();
@@ -205,11 +220,11 @@ blang[javascript,swift,kotlin].
   Use the <span lang="javascript">"@typing.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#get</span><span lang="swift">"@typing.get()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing/get%28%29</span><span lang="kotlin">"@typing.get()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-typing/get.html</span> method to retrieve a set of @clientId@s for all users that are currently typing in the room:
 
   ```[javascript]
-  const currentlyTypingClientIds = await room.typing.get();
+  const currentlyTypingClientIds = room.typing.get();
   ```
 
   ```[swift]
-  let currentlyTypingClientIds = try await room.typing.get()
+  let currentlyTypingClientIds = try room.typing.get()
   ```
 
   ```[kotlin]