Added docs section for handling self published message to messages.kt

Author: sacOO7

src/pages/docs/chat/rooms/messages.mdx

@@ -228,6 +228,146 @@ fun MyComponent(room: Room) {
 ```
 </Code>
 
+### Handle self-published messages <a id="self-published-messages"/>
+
+<Aside data-type='important'>
+When you send a message using `send()`, the server echoes it back to all subscribers in the room, including the sender. If your application adds the message to the UI immediately after calling `send()` and also appends it when received via `subscribe()`, the message will appear twice.
+
+To avoid this, use one of the following approaches:
+
+**Approach 1: Only render messages from the subscription.** Do not add the message to the UI when calling `send()`. Instead, rely solely on the subscription listener to display all messages, including your own. This is the simplest approach and ensures consistency with the server's message ordering and `serial` assignment.
+
+**Approach 2: Use `serial` to deduplicate.** If you want optimistic UI updates (displaying the message immediately on send for a more responsive experience), use the `serial` property of the message returned by `send()` to filter out the duplicate when it arrives via the subscription. When a new message event is received, check whether a message with the same `serial` already exists in your local list before adding it.
+</Aside>
+
+The following example demonstrates approach 2, using `serial`-based deduplication to prevent duplicate messages:
+
+<Code>
+```javascript
+import { ChatMessageEventType } from '@ably/chat';
+const messages = [];
+
+// Subscribe to incoming messages
+room.messages.subscribe((event) => {
+  if (event.type === ChatMessageEventType.Created) {
+    // Only add the message if it doesn't already exist in the list
+    const exists = messages.some((msg) => msg.serial === event.message.serial);
+    if (!exists) {
+      messages.push(event.message);
+    }
+  }
+});
+
+// Send a message and optimistically add it to the list
+const message = await room.messages.send({ text: 'hello' });
+messages.push(message);
+```
+
+```react
+import { useState, useCallback } from 'react';
+import { ChatMessageEventType } from '@ably/chat';
+import { useMessages } from '@ably/chat/react';
+
+const MyComponent = () => {
+  const [messages, setMessages] = useState([]);
+
+  const { sendMessage } = useMessages({
+    listener: (event) => {
+      if (event.type === ChatMessageEventType.Created) {
+        setMessages((prev) => {
+          // Only add the message if it doesn't already exist in the list
+          if (prev.some((msg) => msg.serial === event.message.serial)) {
+            return prev;
+          }
+          return [...prev, event.message];
+        });
+      }
+    },
+  });
+
+  const handleSend = useCallback(async () => {
+    const message = await sendMessage({ text: 'hello' });
+    setMessages((prev) => [...prev, message]);
+  }, [sendMessage]);
+
+  return <div>...</div>;
+};
+```
+
+```swift
+var messages: [Message] = []
+let messagesSubscription = try await room.messages.subscribe()
+
+// Subscribe to incoming messages
+Task {
+    for await message in messagesSubscription {
+        // Only add the message if it doesn't already exist in the list
+        if !messages.contains(where: { $0.serial == message.serial }) {
+            messages.append(message)
+        }
+    }
+}
+
+// Send a message and optimistically add it to the list
+let sentMessage = try await room.messages.send(withParams: .init(text: "hello"))
+messages.append(sentMessage)
+```
+
+```kotlin
+val messages = mutableListOf<Message>()
+
+// Subscribe to incoming messages
+val subscription = room.messages.subscribe { event ->
+    if (event.type == ChatMessageEventType.Created) {
+        // Only add the message if it doesn't already exist in the list
+        val exists = messages.any { it.serial == event.message.serial }
+        if (!exists) {
+            messages.add(event.message)
+        }
+    }
+}
+
+// Send a message and optimistically add it to the list
+val sentMessage = room.messages.send(text = "hello")
+messages.add(sentMessage)
+```
+
+```android
+import androidx.compose.runtime.*
+import com.ably.chat.ChatMessageEventType
+import com.ably.chat.Message
+import com.ably.chat.Room
+import com.ably.chat.asFlow
+import kotlinx.coroutines.launch
+
+@Composable
+fun MyComponent(room: Room) {
+  var messages by remember { mutableStateOf<List<Message>>(emptyList()) }
+  val coroutineScope = rememberCoroutineScope()
+
+  // Subscribe to incoming messages
+  LaunchedEffect(room) {
+    room.messages.asFlow().collect { event ->
+      if (event.type == ChatMessageEventType.Created) {
+        // Only add the message if it doesn't already exist in the list
+        if (messages.none { it.serial == event.message.serial }) {
+          messages = messages + event.message
+        }
+      }
+    }
+  }
+
+  // Send a message and optimistically add it to the list
+  fun sendMessage(text: String) {
+    coroutineScope.launch {
+      val sentMessage = room.messages.send(text = text)
+      messages = messages + sentMessage
+    }
+  }
+}
+```
+</Code>
+
 ## Get a single message <a id="get-by-serial"/>
 
 <If lang="javascript,swift,kotlin,android">