From 81eedc9cf118261ea859f5d798ddf9fee9a7e1ba Mon Sep 17 00:00:00 2001
From: Greg Holmes <iam@gregholmes.co.uk>
Date: Tue, 21 Oct 2025 11:45:59 +0100
Subject: [PATCH] Migrate Realtime SDK API spec Messages page to MDX

---
 content/api/realtime-sdk/messages.textile    |  32 ------
 src/pages/docs/api/realtime-sdk/messages.mdx | 109 +++++++++++++++++++
 2 files changed, 109 insertions(+), 32 deletions(-)
 delete mode 100644 content/api/realtime-sdk/messages.textile
 create mode 100644 src/pages/docs/api/realtime-sdk/messages.mdx

diff --git a/content/api/realtime-sdk/messages.textile b/content/api/realtime-sdk/messages.textile
deleted file mode 100644
index c4519ed736..0000000000
--- a/content/api/realtime-sdk/messages.textile
+++ /dev/null
@@ -1,32 +0,0 @@
----
-title: Messages
-meta_description: "Realtime Client Library SDK API reference section for the message object."
-meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, message, messages"
-section: api
-languages:
-  - javascript
-  - nodejs
-  - ruby
-  - java
-  - swift
-  - objc
-  - csharp
-  - flutter
-redirect_from:
-  - /docs/api/versions/v1.1/realtime-sdk/messages
-  - /docs/api/versions/v1.0/realtime-sdk/messages
-  - /docs/api/versions/v0.8/realtime-sdk/messages
----
-
-h2(#properties).
-  default: Properties
-  java:    Members
-  ruby:    Attributes
-  python:  Attributes
-
-<%= partial partial_version('types/_message') %>
-
-h2(#message-annotations).
-  default: MessageAnnotations
-
-<%= partial partial_version('types/_message_annotations') %>
diff --git a/src/pages/docs/api/realtime-sdk/messages.mdx b/src/pages/docs/api/realtime-sdk/messages.mdx
new file mode 100644
index 0000000000..7b04a32388
--- /dev/null
+++ b/src/pages/docs/api/realtime-sdk/messages.mdx
@@ -0,0 +1,109 @@
+---
+title: Messages
+meta_description: "Realtime Client Library SDK API reference section for the message object."
+meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, message, messages"
+redirect_from:
+  - /docs/api/versions/v1.1/realtime-sdk/messages
+  - /docs/api/versions/v1.0/realtime-sdk/messages
+  - /docs/api/versions/v0.8/realtime-sdk/messages
+---
+
+## <If lang="javascript,nodejs,flutter,csharp,objc,swift">Properties</If><If lang="ruby">Attributes</If><If lang="java">Members</If> <a id="#properties" />
+
+A `Message` represents an individual message that is sent to or received from Ably.
+
+### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">name</If><If lang="csharp">Name</If> <a id="#name" />
+
+The event name, if provided. <br />_Type: `String`_
+
+### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">data</If><If lang="csharp">Data</If> <a id="#data" />
+
+The message payload, if provided.<br />_Type: <If lang="javascript,nodejs">`String`, `StringBuffer`, `JSON Object`</If><If lang="java">`String`, `ByteArray`, `JSONObject`, `JSONArray`</If><If lang="csharp">`String`, `byte[]`, `plain C# object that can be serialized to JSON`</If><If lang="ruby">`String`, `Binary` (ASCII-8BIT String), `Hash`, `Array`</If><If lang="objc">`NSString *`, `NSData *`, `NSDictionary *`, `NSArray *`</If><If lang="swift">`String`, `NSData`, `Dictionary`, `Array`</If><If lang="flutter">`String`, `Map`, `List`</If>_
+
+### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">extras</If><If lang="csharp">Extras</If> <a id="#extras" />
+
+Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), [`headers`](/docs/channels#metadata) (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/webhooks#skipping).<br />_Type: <If lang="java">`JSONObject`, `JSONArray`</If><If lang="csharp">plain C# object that can be converted to JSON</If><If lang="javascript,nodejs">`JSON Object`</If><If lang="ruby">`Hash`, `Array`</If><If lang="swift">`Dictionary`, `Array`</If><If lang="objc">`NSDictionary *`, `NSArray *`</If>_
+
+### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">id</If><If lang="csharp">Id</If> <a id="#id" />
+
+A Unique ID assigned by Ably to this message.<br />_Type: `String`_
+
+### <If lang="javascript,nodejs,flutter,objc,swift,java">clientId</If><If lang="csharp">ClientId</If><If lang="ruby,python">client_id</If> <a id="#client-id" />
+
+The client ID of the publisher of this message.<br />_Type: `String`_
+
+### <If lang="javascript,nodejs,flutter,objc,swift,java">connectionId</If><If lang="csharp">ConnectionId</If><If lang="ruby,python">connection_id</If> <a id="#connection-id" />
+
+The connection ID of the publisher of this message.<br />_Type: `String`_
+
+### <If lang="javascript,nodejs,flutter,objc,swift,java">connectionKey</If><If lang="csharp,go">ConnectionKey</If><If lang="ruby,python">connection_key</If> <a id="#connection-key" />
+
+A connection key, which can optionally be included for a REST publish as part of the [publishing on behalf of a realtime client functionality](/docs/pub-sub/advanced#publish-on-behalf).<br />_Type: `String`_
+
+### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">timestamp</If><If lang="csharp">Timestamp</If> <a id="#timestamp" />
+
+Timestamp when the message was first received by the Ably, as <If lang="javascript,nodejs,flutter,swift,csharp,objc,java">milliseconds since the epoch</If><If lang="ruby">a `Time` object</If>.<br />_Type: <If lang="javascript,nodejs,flutter">`Integer`</If><If lang="java">`Long Integer`</If><If lang="csharp">`DateTimeOffset`</If><If lang="ruby">`Time`</If><If lang="objc,swift">`NSDate`</If>_
+
+### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">encoding</If><If lang="csharp">Encoding</If> <a id="#encoding" />
+
+This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.<br />_Type: `String`_
+
+<If lang="javascript,nodejs">
+
+### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">action</If> <a id="#action" />
+
+The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values.<br />_Type: `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }`_
+
+### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">serial</If> <a id="#serial" />
+
+A server-assigned identifier that will be the same in all future updates of this message. It  can be used to add annotations to a message. Serial will only be set if you enable annotations in [channel rules](/docs/channels#rules).<br />_Type: `String`_
+
+### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">annotations</If> <a id="#annotations" />
+
+An object containing information about annotations that have been made to the object.<br />_Type: [`MessageAnnotations`](/docs/api/realtime-sdk/types#message-annotations)_
+
+</If>
+
+### Message constructors <a id="constructors" />
+
+#### <If lang="javascript,nodejs,flutter,csharp,objc,swift,ruby,java">Message.fromEncoded</If> <a id="#message-from-encoded" />
+
+`Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message`
+
+A static factory method to create a [`Message`](/docs/api/realtime-sdk/types#message) from a deserialized `Message`-like object encoded using Ably's wire protocol.
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| encodedMsg | A `Message`-like deserialized object. | `Object` |
+| channelOptions | An optional [`ChannelOptions`](/docs/api/realtime-sdk/types#channel-options). If you have an encrypted channel, use this to allow the library can decrypt the data. | `Object` |
+
+##### Returns
+
+A [`Message`](/docs/api/realtime-sdk/types#message) object
+
+#### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">Message.fromEncodedArray</If> <a id="#message-from-encoded-array" />
+
+`Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[]`
+
+A static factory method to create an array of [`Messages`](/docs/api/realtime-sdk/types#message) from an array of deserialized `Message`-like object encoded using Ably's wire protocol.
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| encodedMsgs | An array of `Message`-like deserialized objects. | `Array` |
+| channelOptions | An optional [`ChannelOptions`](/docs/api/realtime-sdk/types#channel-options). If you have an encrypted channel, use this to allow the library can decrypt the data. | `Object` |
+
+##### Returns
+
+An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects
+
+## MessageAnnotations <a id="#message-annotations" />
+
+#### <If lang="javascript,nodejs,flutter,objc,csharp,swift">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>
+
+| Property | Description | Type |
+|----------|-------------|------|
+| summary | An object whose keys are annotation types, and the values are aggregated summaries for that annotation type | `Record<String, JsonObject>` |