EDU-1469: Re-writes idempotent publishing section to improve clarity

content/channels/index.textile

@@ -753,56 +753,181 @@ channel.Publish(context.Background(), "action", "boom!")
 
 h3(#idempotency). Idempotent publish
 
-Idempotency ensures that multiple publishes of the same message cannot result in duplicate messages.
+Idempotent publishing ensures that multiple attempts to publish the same message do not result in duplicate messages. This feature is essential when network issues may cause a client to reattempt message publication without knowing if the initial attempt succeeded.
 
-It is possible that a client publishing a message using the REST interface may not receive acknowledgement of receipt from Ably, due to issues such as network failure outside of Ably's control. Clients will internally attempt to re-publish messages in these instances.
+h4. Automatic idempotency
 
-When idempotent publishing is enabled, the Ably SDK will internally assign a unique ID to each message which ensures that subsequent retry attempts cannot result in duplicate messages. Idempotent publishing is enabled by default in all latest Ably SDKs. It can be disabled by setting the @idempotentRestPublishing@ "@ClientOptions@":/api/rest-sdk#client-options to @false@.
+For versions 1.2 and later of the Ably library, idempotent publishing is enabled by default. This means the Ably SDK automatically assigns a unique ID to each message to prevent duplicates during retries. This functionality applies to both REST and realtime publishing.
+For older versions (before 1.2), this feature was not enabled by default for publishing. However, it could be activated using @idempotentRestPublishing@ in "@ClientOptions@":/api/rest-sdk#client-optionsidempotentRestPublishing.
 
-Note that Ably can only detect duplicate messages within a 2-minute window after the original message, with the same ID, is published. If a message with the same ID is published after this 2-minute window, it will be treated as a new message.
+h4. Client ID idempotency
 
-You can also specify message IDs externally. The following is an example of how you might do this:
+There are scenarios where specifying a client-supplied ID to achieve idempotency are necessary, such as:
 
-```[rest_javascript]
-const rest = new Ably.Rest('{{API_KEY}}');
-const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
-await channel.publish([{data: 'payload', id: 'unique123'}]);
+* Ensuring idempotency when a publisher instance might be restarted, and continuous activity cannot be guaranteed.
+* Integrating with an upstream system that uses its message IDs, ensuring idempotency across an entire message processing pipeline.
+
+In these cases, you can manually specify the message ID for REST and realtime publishing.
+
+The following example manually specifies a message ID:
+
+```[realtime_javascript]
+const realtime = new Ably.Realtime = '{{API_KEY}}';
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+const message = [{ data: 'payload', id: 'unique123' }];
 ```
 
-```[rest_go]
-rest, err := ably.NewREST(
+```[realtime_nodejs]
+const realtime = new Ably.Realtime = '{{API_KEY}}';
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+const message = [{ data: 'payload', id: 'unique123' }];
+```
+
+```[realtime_ruby]
+realtime = Ably::Realtime.new(key: '{{API_KEY}}')
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+channel.publish(name: 'example', data: 'payload', id: 'unique123')
+```
+
+```[realtime_python]
+realtime = AblyRealtime('{{API_KEY}}')
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+await channel.publish([{data: 'payload', id: 'unique123'}])
+```
+
+```[realtime_java]
+ClientOptions options = new ClientOptions('{{API_KEY}}');
+AblyRealtime ably = new AblyRealtime(options);
+Channel channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+Message message = new Message();
+message.data = "payload";
+message.id = "unique123";
+```
+
+```[realtime_csharp]
+ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"{{API_KEY}}"];
+ARTRealtimeChannel *channel = [realtime.channels get:@"{{RANDOM_CHANNEL_NAME}}"];
+channel publish:@"example" data:@"payload" id:@"unique123" callback:^(ARTErrorInfo *error)
+```
+
+```[realtime_swift]
+let realtime = ARTRealtime(key: "{{API_KEY}}")
+let channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}")
+channel.publish("example", data: "message data", id: "unique123")
+```
+
+```[realtime_objc]
+ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:("{{API_KEY}}"));
+ARTRealtimeChannel *channel = [realtime.channels get:("{{RANDOM_CHANNEL_NAME}}");
+[channel.publish("example", data: "message data", id: "unique123")];
+```
+
+```[realtime_flutter]
+final clientOptions = ably.ClientOptions(key: '{{API_KEY}}');
+final realtime = ably.Realtime(options: clientOptions);
+final channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+await message = ably.Message(data: 'payload', id: 'unique123');
+```
+
+```[realtime_go]
+realtime, err := ably.NewRealtime(
   ably.WithKey("{{API_KEY}}"))
 if err != nil {
   log.Fatalf("Error creating Ably client: %v", err)
 }
 
-channel := rest.Channels.Get("{{RANDOM_CHANNEL_NAME}}")
+channel := realtime.Channels.Get("{{RANDOM_CHANNEL_NAME}}")
 
 message := &ably.Message{
   Data: "payload",
   ID:   "unique123",
 }
+```
 
-// Publish the message to the channel
-err = channel.Publish(context.Background(), "eventName", message)
-if err != nil {
-  log.Fatalf("Error publishing message: %v", err)
-}
+```[rest_javascript]
+  const rest = new Ably.Rest = '{{API_KEY}}';
+  const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
+  const message = [{ data: 'payload', id: 'unique123' }];
+```
+
+```[rest_nodejs]
+  const rest = new Ably.Rest = '{{API_KEY}}';
+  const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
+  const message = [{ data: 'payload', id: 'unique123' }];
+```
+
+```[rest_ruby]
+rest = Ably::Rest.new(key: '{{API_KEY}}')
+channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}')
+channel.publish(name: 'example', data: 'payload', id: 'unique123')
+```
+
+```[rest_python]
+rest = AblyRest('{{API_KEY}}')
+channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}')
+await channel.publish([{data: 'payload', id: 'unique123'}])
+```
+
+```[rest_php]
+$rest = new Ably\AblyRest('{{API_KEY}}');
+$channel = $rest->channels->get('{{RANDOM_CHANNEL_NAME}}')
+$channel->publish([{data: 'payload', id: 'unique123'}]);
 ```
 
 ```[rest_java]
-ClientOptions options = new ClientOptions("{{API_KEY}}");
-AblyRealtime ably = new AblyRealtime(options);
-Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+ClientOptions options = new ClientOptions('{{API_KEY}}');
+AblyRest ably = new AblyRest(options);
+Channel channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}');
 
 Message message = new Message();
 message.data = "payload";
 message.id = "unique123";
+```
 
-channel.publish(new Message[]{message});
+```[rest_csharp]
+ARTRealtime *rest = [[ARTRealtime alloc] initWithKey:@"{{API_KEY}}"];
+ARTRealtimeChannel *channel = [rest.channels get:@"{{RANDOM_CHANNEL_NAME}}"];
+channel publish:@"example" data:@"payload" id:@"unique123" callback:^(ARTErrorInfo *error)
 ```
 
-If manually specifying message IDs, it is important to be aware of how messages are published when calling the "publish()":/api/rest-sdk/channels#publish method with an array of messages. See this "FAQ":https://faqs.ably.com/client-specified-message-id-restrictions-for-multiple-messages-published-atomically for further information.
+```[rest_swift]
+let rest = ARTRest(key: "{{API_KEY}}")
+var channel = rest.channels.get("{{RANDOM_CHANNEL_NAME}}")
+channel.publish("example", data: "message data", id: "unique123")
+```
+
+```[rest_objc]
+ARTRest *rest = [[ARTRest alloc] initWithKey:("{{API_KEY}}"));
+ARTRestChannel *channel = [rest.channels get:("{{RANDOM_CHANNEL_NAME}}");
+[channel.publish("example", data: "message data", id: "unique123")];
+```
+
+```[rest_flutter]
+final clientOptions = ably.ClientOptions(key: '{{API_KEY}}');
+final rest = ably.Rest(options: clientOptions);
+final channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
+await message = ably.Message(data: 'payload', id: 'unique123');
+```
+
+```[rest_go]
+rest, err := ably.NewREST(
+  ably.WithKey("{{API_KEY}}"))
+if err != nil {
+  log.Fatalf("Error creating Ably client: %v", err)
+}
+
+channel := rest.Channels.Get("{{RANDOM_CHANNEL_NAME}}")
+
+message := &ably.Message{
+  Data: "payload",
+  ID:   "unique123",
+}
+```
+
+h4. Restrictions and considerations
+
+When specifying custom message IDs, particularly when attempting to "@publish()@":/api/rest-sdk/channels#publish multiple messages atomically with idempotency, ensure that the IDs adhere to the format restrictions. For more details on these restrictions, refer to the "FAQ":https://faqs.ably.com/client-specified-message-id-restrictions-for-multiple-messages-published-atomically.
 
 h3(#publish-on-behalf). Use the REST interface to publish on behalf of a realtime connection