diff --git a/README.md b/README.md
index c4a855b3..469abeb0 100644
--- a/README.md
+++ b/README.md
@@ -290,7 +290,7 @@ To stop listening to discontinuities, `unsubscribe` method on returned subscript
 To send a message, simply call `send` on the `room.messages` property, with the message you want to send.
 
 ```kotlin
-val message = room.messages.send(SendMessageParams(text = "text"))
+val message = room.messages.send(text = "text")
 ```
 
 ### Unsubscribing from incoming messages
@@ -312,7 +312,7 @@ The messages object also exposes the `get` method which can be used to request h
 to the given criteria. It returns a paginated response that can be used to request more messages.
 
 ```kotlin
-var historicalMessages = room.messages.get(QueryParams(orderBy = NewestFirst, limit = 50))
+var historicalMessages = room.messages.get(orderBy = NewestFirst, limit = 50)
 println(historicalMessages.items.toString())
 
 while (historicalMessages.hasNext()) {
@@ -551,17 +551,17 @@ To send room-level reactions, you must be [attached](#attaching-to-a-room) to th
 To send a reaction such as `"like"`:
 
 ```kotlin
-room.reactions.send(SendReactionParams(type = "like"))
+room.reactions.send(type = "like")
 ```
 
 You can also add any metadata and headers to reactions:
 
 ```kotlin
-room.reactions.send(SendReactionParams(
+room.reactions.send(
     type ="like",
-    metadata = mapOf("effect" to "fireworks"),
+    metadata = JsonObject().apply { addProperty("effect", "fireworks") },
     headers = mapOf("streamId" to "basketball-stream"),
-))
+)
 ```
 
 ### Subscribing to room reactions
diff --git a/chat-android/src/main/java/com/ably/chat/ChatApi.kt b/chat-android/src/main/java/com/ably/chat/ChatApi.kt
index 686fcd50..a2b09b4c 100644
--- a/chat-android/src/main/java/com/ably/chat/ChatApi.kt
+++ b/chat-android/src/main/java/com/ably/chat/ChatApi.kt
@@ -45,7 +45,7 @@ internal class ChatApi(
                     roomId = it.requireString("roomId"),
                     text = it.requireString("text"),
                     createdAt = it.requireLong("createdAt"),
-                    metadata = it.asJsonObject.get("metadata")?.toMap() ?: mapOf(),
+                    metadata = it.asJsonObject.get("metadata"),
                     headers = it.asJsonObject.get("headers")?.toMap() ?: mapOf(),
                     latestAction = action,
                 )
@@ -69,7 +69,7 @@ internal class ChatApi(
             }
             // (CHA-M3b)
             params.metadata?.let {
-                add("metadata", it.toJson())
+                add("metadata", it)
             }
         }
 
@@ -85,7 +85,7 @@ internal class ChatApi(
                 roomId = roomId,
                 text = params.text,
                 createdAt = it.requireLong("createdAt"),
-                metadata = params.metadata ?: mapOf(),
+                metadata = params.metadata,
                 headers = params.headers ?: mapOf(),
                 latestAction = MessageAction.MESSAGE_CREATE,
             )
@@ -94,7 +94,7 @@ internal class ChatApi(
 
     private fun validateSendMessageParams(params: SendMessageParams) {
         // (CHA-M3c)
-        if (params.metadata?.containsKey(RESERVED_ABLY_CHAT_KEY) == true) {
+        if ((params.metadata as? JsonObject)?.has(RESERVED_ABLY_CHAT_KEY) == true) {
             throw AblyException.fromErrorInfo(
                 ErrorInfo(
                     "Metadata contains reserved 'ably-chat' key",
@@ -204,8 +204,8 @@ private fun QueryOptions.toParams() = buildList {
         Param(
             "direction",
             when (orderBy) {
-                QueryOptions.MessageOrder.NewestFirst -> "backwards"
-                QueryOptions.MessageOrder.OldestFirst -> "forwards"
+                QueryOptions.ResultOrder.NewestFirst -> "backwards"
+                QueryOptions.ResultOrder.OldestFirst -> "forwards"
             },
         ),
     )
diff --git a/chat-android/src/main/java/com/ably/chat/Discontinuities.kt b/chat-android/src/main/java/com/ably/chat/Discontinuities.kt
index f9ac6cff..571b7ee6 100644
--- a/chat-android/src/main/java/com/ably/chat/Discontinuities.kt
+++ b/chat-android/src/main/java/com/ably/chat/Discontinuities.kt
@@ -9,8 +9,7 @@ import io.ably.lib.realtime.ChannelBase as AblyRealtimeChannel
  */
 interface HandlesDiscontinuity {
     /**
-     * A promise of the channel that this object is associated with. The promise
-     * is resolved when the feature has finished initializing.
+     * The channel that this object is associated with.
      */
     val channel: AblyRealtimeChannel
 
diff --git a/chat-android/src/main/java/com/ably/chat/Message.kt b/chat-android/src/main/java/com/ably/chat/Message.kt
index a8fc21e4..a0bbb1d6 100644
--- a/chat-android/src/main/java/com/ably/chat/Message.kt
+++ b/chat-android/src/main/java/com/ably/chat/Message.kt
@@ -3,12 +3,12 @@ package com.ably.chat
 import io.ably.lib.types.MessageAction
 
 /**
- * {@link Headers} type for chat messages.
+ * [Headers type for chat messages.
  */
 typealias MessageHeaders = Headers
 
 /**
- * {@link Metadata} type for chat messages.
+ * [Metadata] type for chat messages.
  */
 typealias MessageMetadata = Metadata
 
@@ -53,7 +53,7 @@ data class Message(
      * Do not use metadata for authoritative information. There is no server-side
      * validation. When reading the metadata treat it like user input.
      */
-    val metadata: MessageMetadata,
+    val metadata: MessageMetadata?,
 
     /**
      * The headers of a chat message. Headers enable attaching extra info to a message,
diff --git a/chat-android/src/main/java/com/ably/chat/Messages.kt b/chat-android/src/main/java/com/ably/chat/Messages.kt
index bf33332c..edaa0674 100644
--- a/chat-android/src/main/java/com/ably/chat/Messages.kt
+++ b/chat-android/src/main/java/com/ably/chat/Messages.kt
@@ -2,7 +2,7 @@
 
 package com.ably.chat
 
-import com.ably.chat.QueryOptions.MessageOrder.NewestFirst
+import com.ably.chat.QueryOptions.ResultOrder.NewestFirst
 import com.google.gson.JsonObject
 import io.ably.lib.realtime.AblyRealtime
 import io.ably.lib.realtime.ChannelState
@@ -19,7 +19,7 @@ typealias PubSubMessage = io.ably.lib.types.Message
  * This interface is used to interact with messages in a chat room: subscribing
  * to new messages, fetching history, or sending messages.
  *
- * Get an instance via {@link Room.messages}.
+ * Get an instance via [Room.messages].
  */
 interface Messages : EmitsDiscontinuities {
     /**
@@ -32,18 +32,26 @@ interface Messages : EmitsDiscontinuities {
     /**
      * Subscribe to new messages in this chat room.
      * @param listener callback that will be called
-     * @returns A response object that allows you to control the subscription.
+     * @return A response object that allows you to control the subscription.
      */
     fun subscribe(listener: Listener): MessagesSubscription
 
     /**
      * Get messages that have been previously sent to the chat room, based on the provided options.
      *
-     * @param options Options for the query.
-     * @returns A promise that resolves with the paginated result of messages. This paginated result can
-     * be used to fetch more messages if available.
+     * @param start The start of the time window to query from. See [QueryOptions.start]
+     * @param end The end of the time window to query from. See [QueryOptions.end]
+     * @param limit The maximum number of messages to return in the response. See [QueryOptions.limit]
+     * @param orderBy The order of messages in the query result. See [QueryOptions.orderBy]
+     *
+     * @return Paginated result of messages. This paginated result can be used to fetch more messages if available.
      */
-    suspend fun get(options: QueryOptions): PaginatedResult<Message>
+    suspend fun get(
+        start: Long? = null,
+        end: Long? = null,
+        limit: Int = 100,
+        orderBy: QueryOptions.ResultOrder = NewestFirst,
+    ): PaginatedResult<Message>
 
     /**
      * Send a message in the chat room.
@@ -54,13 +62,13 @@ interface Messages : EmitsDiscontinuities {
      * from the realtime channel. This means you may see the message that was just
      * sent in a callback to `subscribe` before the function resolves.
      *
-     * TODO: Revisit this resolution policy during implementation (it will be much better for DX if this behavior is deterministic).
+     * @param text The text of the message. See [SendMessageParams.text]
+     * @param metadata Optional metadata of the message. See [SendMessageParams.metadata]
+     * @param headers Optional headers of the message. See [SendMessageParams.headers]
      *
-     * @param params an object containing {text, headers, metadata} for the message
-     * to be sent. Text is required, metadata and headers are optional.
-     * @returns The message was published.
+     * @return The message was published.
      */
-    suspend fun send(params: SendMessageParams): Message
+    suspend fun send(text: String, metadata: MessageMetadata? = null, headers: MessageHeaders? = null): Message
 
     /**
      * An interface for listening to new messaging event
@@ -102,12 +110,12 @@ data class QueryOptions(
     /**
      * The order of messages in the query result.
      */
-    val orderBy: MessageOrder = NewestFirst,
+    val orderBy: ResultOrder = NewestFirst,
 ) {
     /**
      * Represents direction to query messages in.
      */
-    enum class MessageOrder {
+    enum class ResultOrder {
         /**
          * The response will include messages from the start of the time window to the end.
          */
@@ -292,9 +300,16 @@ internal class DefaultMessages(
         )
     }
 
-    override suspend fun get(options: QueryOptions): PaginatedResult<Message> = chatApi.getMessages(roomId, options)
+    override suspend fun get(start: Long?, end: Long?, limit: Int, orderBy: QueryOptions.ResultOrder): PaginatedResult<Message> =
+        chatApi.getMessages(
+            roomId,
+            QueryOptions(start, end, limit, orderBy),
+        )
 
-    override suspend fun send(params: SendMessageParams): Message = chatApi.sendMessage(roomId, params)
+    override suspend fun send(text: String, metadata: MessageMetadata?, headers: MessageHeaders?): Message = chatApi.sendMessage(
+        roomId,
+        SendMessageParams(text, metadata, headers),
+    )
 
     /**
      * Associate deferred channel serial value with the current channel's serial
@@ -370,7 +385,7 @@ internal class DefaultMessages(
 /**
  * Parsed data from the Pub/Sub channel's message data field
  */
-private data class PubSubMessageData(val text: String, val metadata: MessageMetadata)
+private data class PubSubMessageData(val text: String, val metadata: MessageMetadata?)
 
 private fun parsePubSubMessageData(data: Any): PubSubMessageData {
     if (data !is JsonObject) {
@@ -380,6 +395,6 @@ private fun parsePubSubMessageData(data: Any): PubSubMessageData {
     }
     return PubSubMessageData(
         text = data.requireString("text"),
-        metadata = data.get("metadata")?.toMap() ?: mapOf(),
+        metadata = data.get("metadata"),
     )
 }
diff --git a/chat-android/src/main/java/com/ably/chat/Metadata.kt b/chat-android/src/main/java/com/ably/chat/Metadata.kt
index 1135fb1a..dd57ffb5 100644
--- a/chat-android/src/main/java/com/ably/chat/Metadata.kt
+++ b/chat-android/src/main/java/com/ably/chat/Metadata.kt
@@ -1,5 +1,7 @@
 package com.ably.chat
 
+import com.google.gson.JsonElement
+
 /**
  * Metadata is a map of extra information that can be attached to chat
  * messages. It is not used by Ably and is sent as part of the realtime
@@ -13,4 +15,4 @@ package com.ably.chat
  * The key `ably-chat` is reserved and cannot be used. Ably may populate
  * this with different values in the future.
  */
-typealias Metadata = Map<String, String>
+typealias Metadata = JsonElement
diff --git a/chat-android/src/main/java/com/ably/chat/Occupancy.kt b/chat-android/src/main/java/com/ably/chat/Occupancy.kt
index c2afa229..c6ec1197 100644
--- a/chat-android/src/main/java/com/ably/chat/Occupancy.kt
+++ b/chat-android/src/main/java/com/ably/chat/Occupancy.kt
@@ -18,7 +18,7 @@ import kotlinx.coroutines.launch
  * This interface is used to interact with occupancy in a chat room: subscribing to occupancy updates and
  * fetching the current room occupancy metrics.
  *
- * Get an instance via {@link Room.occupancy}.
+ * Get an instance via [Room.occupancy].
  */
 interface Occupancy : EmitsDiscontinuities {
     /**
diff --git a/chat-android/src/main/java/com/ably/chat/Presence.kt b/chat-android/src/main/java/com/ably/chat/Presence.kt
index c7b8ed1c..7102be08 100644
--- a/chat-android/src/main/java/com/ably/chat/Presence.kt
+++ b/chat-android/src/main/java/com/ably/chat/Presence.kt
@@ -14,7 +14,7 @@ typealias PresenceData = JsonElement
  * This interface is used to interact with presence in a chat room: subscribing to presence events,
  * fetching presence members, or sending presence events (join,update,leave).
  *
- * Get an instance via {@link Room.presence}.
+ * Get an instance via [Room.presence].
  */
 interface Presence : EmitsDiscontinuities {
     /**
@@ -25,9 +25,11 @@ interface Presence : EmitsDiscontinuities {
 
     /**
      *  Method to get list of the current online users and returns the latest presence messages associated to it.
-     *  @param {Ably.RealtimePresenceParams} params - Parameters that control how the presence set is retrieved.
-     *  @throws {@link io.ably.lib.types.AblyException} object which explains the error.
-     *  @returns {List<PresenceMessage>}
+     *  @param waitForSync when false, the current list of members is returned without waiting for a complete synchronization.
+     *  @param clientId when provided, will filter array of members returned that match the provided `clientId` string.
+     *  @param connectionId when provided, will filter array of members returned that match the provided `connectionId`.
+     *  @throws [io.ably.lib.types.AblyException] object which explains the error.
+     *  @return list of the current online users
      */
     suspend fun get(waitForSync: Boolean = true, clientId: String? = null, connectionId: String? = null): List<PresenceMember>
 
@@ -40,22 +42,22 @@ interface Presence : EmitsDiscontinuities {
 
     /**
      * Method to join room presence, will emit an enter event to all subscribers. Repeat calls will trigger more enter events.
-     * @param {PresenceData} data - The users data, a JSON serializable object that will be sent to all subscribers.
-     * @throws {@link io.ably.lib.types.AblyException} object which explains the error.
+     * @param data The users data, a JSON serializable object that will be sent to all subscribers.
+     * @throws [io.ably.lib.types.AblyException] object which explains the error.
      */
     suspend fun enter(data: PresenceData? = null)
 
     /**
      * Method to update room presence, will emit an update event to all subscribers. If the user is not present, it will be treated as a join event.
-     * @param {PresenceData} data - The users data, a JSON serializable object that will be sent to all subscribers.
-     * @throws {@link io.ably.lib.types.AblyException} object which explains the error.
+     * @param data The users data, a JSON serializable object that will be sent to all subscribers.
+     * @throws [io.ably.lib.types.AblyException] object which explains the error.
      */
     suspend fun update(data: PresenceData? = null)
 
     /**
      * Method to leave room presence, will emit a leave event to all subscribers. If the user is not present, it will be treated as a no-op.
-     * @param {PresenceData} data - The users data, a JSON serializable object that will be sent to all subscribers.
-     * @throws {@link io.ably.lib.types.AblyException} object which explains the error.
+     * @param data The users data, a JSON serializable object that will be sent to all subscribers.
+     * @throws [io.ably.lib.types.AblyException] object which explains the error.
      */
     suspend fun leave(data: PresenceData? = null)
 
diff --git a/chat-android/src/main/java/com/ably/chat/Reaction.kt b/chat-android/src/main/java/com/ably/chat/Reaction.kt
index 8ab083d5..2303fdc2 100644
--- a/chat-android/src/main/java/com/ably/chat/Reaction.kt
+++ b/chat-android/src/main/java/com/ably/chat/Reaction.kt
@@ -1,12 +1,12 @@
 package com.ably.chat
 
 /**
- * {@link Headers} type for chat messages.
+ * [Headers] type for chat messages.
  */
 typealias ReactionHeaders = Headers
 
 /**
- * {@link Metadata} type for chat messages.
+ * [Metadata] type for chat messages.
  */
 typealias ReactionMetadata = Metadata
 
@@ -22,7 +22,7 @@ data class Reaction(
     /**
      * Metadata of the reaction. If no metadata was set this is an empty object.
      */
-    val metadata: ReactionMetadata = mapOf(),
+    val metadata: ReactionMetadata?,
 
     /**
      * Headers of the reaction. If no headers were set this is an empty object.
diff --git a/chat-android/src/main/java/com/ably/chat/Room.kt b/chat-android/src/main/java/com/ably/chat/Room.kt
index 92405710..d2d52eb5 100644
--- a/chat-android/src/main/java/com/ably/chat/Room.kt
+++ b/chat-android/src/main/java/com/ably/chat/Room.kt
@@ -30,7 +30,7 @@ interface Room {
     /**
      * Allows you to subscribe to presence events in the room.
      *
-     * @throws {@link ErrorInfo}} if presence is not enabled for the room.
+     * @throws [ErrorInfo] if presence is not enabled for the room.
      * @returns The presence instance for the room.
      */
     val presence: Presence
@@ -38,7 +38,7 @@ interface Room {
     /**
      * Allows you to interact with room-level reactions.
      *
-     * @throws {@link ErrorInfo} if reactions are not enabled for the room.
+     * @throws [ErrorInfo] if reactions are not enabled for the room.
      * @returns The room reactions instance for the room.
      */
     val reactions: RoomReactions
@@ -46,7 +46,7 @@ interface Room {
     /**
      * Allows you to interact with typing events in the room.
      *
-     * @throws {@link ErrorInfo} if typing is not enabled for the room.
+     * @throws [ErrorInfo] if typing is not enabled for the room.
      * @returns The typing instance for the room.
      */
     val typing: Typing
@@ -54,7 +54,7 @@ interface Room {
     /**
      * Allows you to interact with occupancy metrics for the room.
      *
-     * @throws {@link ErrorInfo} if occupancy is not enabled for the room.
+     * @throws [ErrorInfo] if occupancy is not enabled for the room.
      * @returns The occupancy instance for the room.
      */
     val occupancy: Occupancy
@@ -94,11 +94,11 @@ interface Room {
     /**
      * Attaches to the room to receive events in realtime.
      *
-     * If a room fails to attach, it will enter either the {@link RoomLifecycle.Suspended} or {@link RoomLifecycle.Failed} state.
+     * If a room fails to attach, it will enter either the [RoomLifecycle.Suspended] or [RoomLifecycle.Failed] state.
      *
      * If the room enters the failed state, then it will not automatically retry attaching and intervention is required.
      *
-     * If the room enters the suspended state, then the call to attach will reject with the {@link ErrorInfo} that caused the suspension. However,
+     * If the room enters the suspended state, then the call to attach will reject with the [ErrorInfo] that caused the suspension. However,
      * the room will automatically retry attaching after a delay.
      */
     suspend fun attach()
diff --git a/chat-android/src/main/java/com/ably/chat/RoomLifecycleManager.kt b/chat-android/src/main/java/com/ably/chat/RoomLifecycleManager.kt
index 25fe09e4..4da631bc 100644
--- a/chat-android/src/main/java/com/ably/chat/RoomLifecycleManager.kt
+++ b/chat-android/src/main/java/com/ably/chat/RoomLifecycleManager.kt
@@ -24,8 +24,7 @@ interface ContributesToRoomLifecycle : EmitsDiscontinuities, HandlesDiscontinuit
     val featureName: String
 
     /**
-     * Gets the channel on which the feature operates. This promise is never
-     * rejected except in the case where room initialization is canceled.
+     * The channel on which the feature operates
      */
     override val channel: AblyRealtimeChannel
 
@@ -285,10 +284,10 @@ internal class RoomLifecycleManager(
     /**
      * Try to attach all the channels in a room.
      *
-     * If the operation succeeds, the room enters the attached state and this promise resolves.
-     * If a channel enters the suspended state, then we reject, but we will retry after a short delay as is the case
+     * If the operation succeeds, the room enters the attached state.
+     * If a channel enters the suspended state, then we throw exception, but we will retry after a short delay as is the case
      * in the core SDK.
-     * If a channel enters the failed state, we reject and then begin to wind down the other channels.
+     * If a channel enters the failed state, we throw an exception and then begin to wind down the other channels.
      * Spec: CHA-RL1
      */
     @Suppress("ThrowsCount")
diff --git a/chat-android/src/main/java/com/ably/chat/RoomOptions.kt b/chat-android/src/main/java/com/ably/chat/RoomOptions.kt
index f30940da..b94d8952 100644
--- a/chat-android/src/main/java/com/ably/chat/RoomOptions.kt
+++ b/chat-android/src/main/java/com/ably/chat/RoomOptions.kt
@@ -6,26 +6,26 @@ package com.ably.chat
 data class RoomOptions(
     /**
      * The presence options for the room. To enable presence in the room, set this property. You may
-     * use {@link RoomOptionsDefaults.presence} to enable presence with default options.
+     * use [RoomOptionsDefaults.presence] to enable presence with default options.
      * @defaultValue undefined
      */
     val presence: PresenceOptions? = null,
 
     /**
      * The typing options for the room. To enable typing in the room, set this property. You may use
-     * {@link RoomOptionsDefaults.typing} to enable typing with default options.
+     * [RoomOptionsDefaults.typing] to enable typing with default options.
      */
     val typing: TypingOptions? = null,
 
     /**
      * The reactions options for the room. To enable reactions in the room, set this property. You may use
-     * {@link RoomOptionsDefaults.reactions} to enable reactions with default options.
+     * [RoomOptionsDefaults.reactions] to enable reactions with default options.
      */
     val reactions: RoomReactionsOptions? = null,
 
     /**
      * The occupancy options for the room. To enable occupancy in the room, set this property. You may use
-     * {@link RoomOptionsDefaults.occupancy} to enable occupancy with default options.
+     * [RoomOptionsDefaults.occupancy] to enable occupancy with default options.
      */
     val occupancy: OccupancyOptions? = null,
 ) {
@@ -48,7 +48,7 @@ data class RoomOptions(
 data class PresenceOptions(
     /**
      * Whether the underlying Realtime channel should use the presence enter mode, allowing entry into presence.
-     * This property does not affect the presence lifecycle, and users must still call {@link Presence.enter}
+     * This property does not affect the presence lifecycle, and users must still call [Presence.enter]
      * in order to enter presence.
      * @defaultValue true
      */
@@ -56,7 +56,7 @@ data class PresenceOptions(
 
     /**
      * Whether the underlying Realtime channel should use the presence subscribe mode, allowing subscription to presence.
-     * This property does not affect the presence lifecycle, and users must still call {@link Presence.subscribe}
+     * This property does not affect the presence lifecycle, and users must still call [Presence.subscribe]
      * in order to subscribe to presence.
      * @defaultValue true
      */
diff --git a/chat-android/src/main/java/com/ably/chat/RoomReactions.kt b/chat-android/src/main/java/com/ably/chat/RoomReactions.kt
index a5ce191b..761e67e5 100644
--- a/chat-android/src/main/java/com/ably/chat/RoomReactions.kt
+++ b/chat-android/src/main/java/com/ably/chat/RoomReactions.kt
@@ -11,30 +11,32 @@ import io.ably.lib.realtime.Channel as AblyRealtimeChannel
 /**
  * This interface is used to interact with room-level reactions in a chat room: subscribing to reactions and sending them.
  *
- * Get an instance via {@link Room.reactions}.
+ * Get an instance via [Room.reactions].
  */
 interface RoomReactions : EmitsDiscontinuities {
     /**
      * Returns an instance of the Ably realtime channel used for room-level reactions.
      * Avoid using this directly unless special features that cannot otherwise be implemented are needed.
      *
-     * @returns The Ably realtime channel instance.
+     * @return The Ably realtime channel instance.
      */
     val channel: AblyRealtimeChannel
 
     /**
-     * Send a reaction to the room including some metadata.
+     * Sends a reaction to the specified room along with optional metadata.
      *
-     * This method accepts parameters for a room-level reaction. It accepts an object
+     * This method allows you to send a reaction at the room level.
+     * It accepts parameters for defining the type of reaction, metadata, and additional headers.
      *
+     * @param type The type of the reaction. See [SendReactionParams.type].
+     * @param metadata Optional metadata to include with the reaction. Defaults to `null`. See [SendReactionParams.metadata]
+     * @param headers Additional headers to include with the reaction. Defaults to an empty map. See [SendReactionParams.headers]
      *
-     * @param params an object containing {type, headers, metadata} for the room
-     * reaction to be sent. Type is required, metadata and headers are optional.
-     * @returns The returned promise resolves when the reaction was sent. Note
-     * that it is possible to receive your own reaction via the reactions
-     * listener before this promise resolves.
+     * @return Unit when the reaction has been successfully sent. Note that it is
+     * possible to receive your own reaction via the reactions listener before
+     * this method completes.
      */
-    suspend fun send(params: SendReactionParams)
+    suspend fun send(type: String, metadata: ReactionMetadata? = null, headers: ReactionHeaders? = null)
 
     /**
      * Subscribe to receive room-level reactions.
@@ -120,14 +122,14 @@ internal class DefaultRoomReactions(
 
     // (CHA-ER3) Ephemeral room reactions are sent to Ably via the Realtime connection via a send method.
     // (CHA-ER3a) Reactions are sent on the channel using a message in a particular format - see spec for format.
-    override suspend fun send(params: SendReactionParams) {
+    override suspend fun send(type: String, metadata: ReactionMetadata?, headers: ReactionHeaders?) {
         val pubSubMessage = PubSubMessage().apply {
             name = RoomReactionEventType.Reaction.eventName
             data = JsonObject().apply {
-                addProperty("type", params.type)
-                params.metadata?.let { add("metadata", it.toJson()) }
+                addProperty("type", type)
+                metadata?.let { add("metadata", it) }
             }
-            params.headers?.let {
+            headers?.let {
                 extras = MessageExtras(
                     JsonObject().apply {
                         add("headers", it.toJson())
@@ -151,7 +153,7 @@ internal class DefaultRoomReactions(
                 type = data.requireString("type"),
                 createdAt = pubSubMessage.timestamp,
                 clientId = pubSubMessage.clientId,
-                metadata = data.get("metadata")?.toMap() ?: mapOf(),
+                metadata = data.get("metadata"),
                 headers = pubSubMessage.extras?.asJsonObject()?.get("headers")?.toMap() ?: mapOf(),
                 isSelf = pubSubMessage.clientId == room.clientId,
             )
diff --git a/chat-android/src/main/java/com/ably/chat/Rooms.kt b/chat-android/src/main/java/com/ably/chat/Rooms.kt
index 7c35d44a..5193ba5f 100644
--- a/chat-android/src/main/java/com/ably/chat/Rooms.kt
+++ b/chat-android/src/main/java/com/ably/chat/Rooms.kt
@@ -24,15 +24,15 @@ interface Rooms {
      *
      * Always call `release(roomId)` after the Room object is no longer needed.
      *
-     * If a call to `get` is made for a room that is currently being released, then the promise will resolve only when
+     * If a call to `get` is made for a room that is currently being released, then it will resolve only when
      * the release operation is complete.
      *
-     * If a call to `get` is made, followed by a subsequent call to `release` before the promise resolves, then the
-     * promise will reject with an error.
+     * If a call to `get` is made, followed by a subsequent call to `release` before it resolves, then `get` will
+     * throw an exception
      *
      * @param roomId The ID of the room.
      * @param options The options for the room.
-     * @throws {@link ErrorInfo} if a room with the same ID but different options already exists.
+     * @throws [io.ably.lib.types.ErrorInfo] if a room with the same ID but different options already exists.
      * @returns Room A new or existing Room object.
      * Spec: CHA-RC1f
      */
@@ -44,7 +44,7 @@ interface Rooms {
      * events.
      *
      * After calling this function, the room object is no-longer usable. If you wish to get the room object again,
-     * you must call {@link Rooms.get}.
+     * you must call [Rooms.get].
      *
      * Calling this function will abort any in-progress `get` calls for the same room.
      *
diff --git a/chat-android/src/main/java/com/ably/chat/Typing.kt b/chat-android/src/main/java/com/ably/chat/Typing.kt
index 14490978..916406f1 100644
--- a/chat-android/src/main/java/com/ably/chat/Typing.kt
+++ b/chat-android/src/main/java/com/ably/chat/Typing.kt
@@ -38,7 +38,7 @@ const val PRESENCE_GET_MAX_RETRIES = 5
  * This interface is used to interact with typing in a chat room including subscribing to typing events and
  * fetching the current set of typing clients.
  *
- * Get an instance via {@link Room.typing}.
+ * Get an instance via [Room.typing].
  */
 interface Typing : EmitsDiscontinuities {
     /**
@@ -56,7 +56,7 @@ interface Typing : EmitsDiscontinuities {
 
     /**
      * Get the current typers, a set of clientIds.
-     * @returns A Promise of a set of clientIds that are currently typing.
+     * @return set of clientIds that are currently typing.
      */
     suspend fun get(): Set<String>
 
diff --git a/chat-android/src/test/java/com/ably/chat/ChatApiTest.kt b/chat-android/src/test/java/com/ably/chat/ChatApiTest.kt
index 6739a249..2e8a126e 100644
--- a/chat-android/src/test/java/com/ably/chat/ChatApiTest.kt
+++ b/chat-android/src/test/java/com/ably/chat/ChatApiTest.kt
@@ -47,7 +47,7 @@ class ChatApiTest {
                     clientId = "clientId",
                     text = "hello",
                     createdAt = 1_000_000L,
-                    metadata = mapOf(),
+                    metadata = null,
                     headers = mapOf(),
                     latestAction = MessageAction.MESSAGE_CREATE,
                 ),
@@ -102,7 +102,7 @@ class ChatApiTest {
                 text = "hello",
                 createdAt = 1_000_000L,
                 headers = mapOf(),
-                metadata = mapOf(),
+                metadata = null,
                 latestAction = MessageAction.MESSAGE_CREATE,
             ),
             message,
diff --git a/chat-android/src/test/java/com/ably/chat/MessagesTest.kt b/chat-android/src/test/java/com/ably/chat/MessagesTest.kt
index 07b0dea6..c6700436 100644
--- a/chat-android/src/test/java/com/ably/chat/MessagesTest.kt
+++ b/chat-android/src/test/java/com/ably/chat/MessagesTest.kt
@@ -67,11 +67,9 @@ class MessagesTest {
         )
 
         val sentMessage = messages.send(
-            SendMessageParams(
-                text = "lala",
-                headers = mapOf("foo" to "bar"),
-                metadata = mapOf("meta" to "data"),
-            ),
+            text = "lala",
+            headers = mapOf("foo" to "bar"),
+            metadata = JsonObject().apply { addProperty("meta", "data") },
         )
 
         assertEquals(
@@ -81,7 +79,7 @@ class MessagesTest {
                 roomId = "room1",
                 text = "lala",
                 createdAt = 1_000_000,
-                metadata = mapOf("meta" to "data"),
+                metadata = JsonObject().apply { addProperty("meta", "data") },
                 headers = mapOf("foo" to "bar"),
                 latestAction = MessageAction.MESSAGE_CREATE,
             ),
@@ -141,7 +139,7 @@ class MessagesTest {
                 clientId = "clientId",
                 serial = "abcdefghij@1672531200000-123",
                 text = "some text",
-                metadata = mapOf(),
+                metadata = null,
                 headers = mapOf("foo" to "bar"),
                 latestAction = MessageAction.MESSAGE_CREATE,
             ),
@@ -234,10 +232,8 @@ class MessagesTest {
         val exception = assertThrows(AblyException::class.java) {
             runBlocking {
                 messages.send(
-                    SendMessageParams(
-                        text = "lala",
-                        headers = mapOf("ably-chat-foo" to "bar"),
-                    ),
+                    text = "lala",
+                    headers = mapOf("ably-chat-foo" to "bar"),
                 )
             }
         }
@@ -252,10 +248,8 @@ class MessagesTest {
         val exception = assertThrows(AblyException::class.java) {
             runBlocking {
                 messages.send(
-                    SendMessageParams(
-                        text = "lala",
-                        metadata = mapOf("ably-chat" to "data"),
-                    ),
+                    text = "lala",
+                    metadata = mapOf("ably-chat" to "data").toJson(),
                 )
             }
         }
diff --git a/chat-android/src/test/java/com/ably/chat/RoomReactionsTest.kt b/chat-android/src/test/java/com/ably/chat/RoomReactionsTest.kt
index d8745d58..2471d997 100644
--- a/chat-android/src/test/java/com/ably/chat/RoomReactionsTest.kt
+++ b/chat-android/src/test/java/com/ably/chat/RoomReactionsTest.kt
@@ -94,7 +94,7 @@ class RoomReactionsTest {
                 type = "like",
                 createdAt = 1000L,
                 clientId = "clientId",
-                metadata = mapOf(),
+                metadata = null,
                 headers = mapOf("foo" to "bar"),
                 isSelf = false,
             ),
diff --git a/example/src/main/java/com/ably/chat/example/MainActivity.kt b/example/src/main/java/com/ably/chat/example/MainActivity.kt
index c8bb3abe..d51ecec2 100644
--- a/example/src/main/java/com/ably/chat/example/MainActivity.kt
+++ b/example/src/main/java/com/ably/chat/example/MainActivity.kt
@@ -48,8 +48,6 @@ import com.ably.chat.RealtimeClient
 import com.ably.chat.Room
 import com.ably.chat.RoomOptions
 import com.ably.chat.RoomReactionsOptions
-import com.ably.chat.SendMessageParams
-import com.ably.chat.SendReactionParams
 import com.ably.chat.Typing
 import com.ably.chat.TypingOptions
 import com.ably.chat.example.ui.PresencePopup
@@ -215,9 +213,7 @@ fun Chat(room: Room, modifier: Modifier = Modifier) {
                 sending = true
                 coroutineScope.launch {
                     room.messages.send(
-                        SendMessageParams(
-                            text = messageText.text,
-                        ),
+                        text = messageText.text,
                     )
                     messageText = TextFieldValue("")
                     sending = false
@@ -225,7 +221,7 @@ fun Chat(room: Room, modifier: Modifier = Modifier) {
             },
             onReactionClick = {
                 coroutineScope.launch {
-                    room.reactions.send(SendReactionParams(type = "\uD83D\uDC4D"))
+                    room.reactions.send(type = "\uD83D\uDC4D")
                 }
             },
         )
@@ -323,7 +319,7 @@ fun MessageBubblePreview() {
                 roomId = "roomId",
                 clientId = "clientId",
                 createdAt = System.currentTimeMillis(),
-                metadata = mapOf(),
+                metadata = null,
                 headers = mapOf(),
                 latestAction = MessageAction.MESSAGE_CREATE,
             ),