diff --git a/src/pages/docs/api/realtime-sdk/channels.mdx b/src/pages/docs/api/realtime-sdk/channels.mdx index 72bff23da3..34f341a6fd 100644 --- a/src/pages/docs/api/realtime-sdk/channels.mdx +++ b/src/pages/docs/api/realtime-sdk/channels.mdx @@ -824,7 +824,7 @@ Failure to retrieve the message history will trigger the `errback` callbacks of - + #### getMessage @@ -840,6 +840,10 @@ Failure to retrieve the message history will trigger the `errback` callbacks of `Message get_message(serial_or_message)` + +`getMessageWithSerial(_ serial: String, callback: (ARTMessage?, ARTErrorInfo?) -> Void)` + + Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities). See [updating and deleting messages: retrieving the latest version](/docs/messages/updates-deletes#get) for more information. @@ -878,6 +882,18 @@ Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the l On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + +| Parameter | Description | Type | +|-----------|-------------|------| +| serial | A serial identifier string of the message to retrieve | `String` | +| callback | A success or failure callback function. On success, it receives an [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message | - | + +##### Callback result +On success, the callback receives a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. + +On failure, the callback receives an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. + + #### updateMessage @@ -892,16 +908,39 @@ On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-except `UpdateDeleteResult update_message(message, operation=None, params=dict())` + +`update(_ message: ARTMessage, operation: ARTMessageOperation?, params: [String: ARTStringifiable]?, callback: ((ARTUpdateDeleteResult?, ARTErrorInfo?) -> Void)?)` + + Publishes an update to an existing message with shallow mixin semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities). + +Note: Note that this publishes an update, it does not mutate the original message if passed in. + + See [updating and deleting messages: updates](/docs/messages/updates-deletes#update) for more information. ##### Parameters + + +| Parameter | Description | Type | +|-----------|-------------|------| +| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the fields to update | [`Message`](/docs/api/realtime-sdk/messages) | +| operation | An optional `MessageOperation` object containing metadata about the update operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | + + + + + | Parameter | Description | Type | |-----------|-------------|------| | message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the fields to update | [`Message`](/docs/api/realtime-sdk/messages) | | operation | An optional `MessageOperation` object containing metadata about the update operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | +| params | Optional parameters sent as part of the request. As Ably adds supported parameters, they will be documented on the [docs pages](https://ably.com/docs) | `[String: Stringifiable]` (optional) | +| callback | A success or failure callback function. On success, it receives an `UpdateDeleteResult` object containing the new version of the message | (optional) | + + ##### Returns @@ -923,6 +962,14 @@ Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-res On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + +##### Callback result + +On success, the callback receives an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +On failure, the callback receives an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. + + #### deleteMessage @@ -937,16 +984,35 @@ On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-except `UpdateDeleteResult delete_message(message, operation=None, params=dict())` + +`delete(_ message: ARTMessage, operation: ARTMessageOperation?, params: [String: ARTStringifiable]?, callback: ((ARTUpdateDeleteResult?, ARTErrorInfo?) -> Void)?)` + + Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses shallow mixin semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-delete-own** or **message-delete-any** [capability](/docs/auth/capabilities). See [updating and deleting messages: deletes](/docs/messages/updates-deletes#delete) for more information. ##### Parameters + + +| Parameter | Description | Type | +|-----------|-------------|------| +| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | [`Message`](/docs/api/realtime-sdk/messages) | +| operation | An optional `MessageOperation` object containing metadata about the delete operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | + + + + + | Parameter | Description | Type | |-----------|-------------|------| | message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | [`Message`](/docs/api/realtime-sdk/messages) | | operation | An optional `MessageOperation` object containing metadata about the delete operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | +| params | Optional parameters sent as part of the request. As Ably adds supported parameters, they will be documented on the [docs pages](https://ably.com/docs) | `[String: Stringifiable]` (optional) | +| callback | A success or failure callback function. On success, it receives an `UpdateDeleteResult` object containing the new version of the message | (optional) | + + ##### Returns @@ -968,6 +1034,14 @@ Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-res On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + +##### Callback result + +On success, the callback receives an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +On failure, the callback receives an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. + + #### appendMessage @@ -982,16 +1056,35 @@ On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-except `UpdateDeleteResult append_message(message, operation=None, params=dict())` + +`append(_ message: ARTMessage, operation: ARTMessageOperation?, params: [String: ARTStringifiable]?, callback: ((ARTUpdateDeleteResult?, ARTErrorInfo?) -> Void)?)` + + Appends data to an existing message. The supplied `data` field is appended to the previous message's data, while all other fields (`name`, `extras`) replace the previous values if provided. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities). See [updating and deleting messages: appends](/docs/messages/updates-deletes#append) for more information. ##### Parameters + + +| Parameter | Description | Type | +|-----------|-------------|------| +| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the data to append | [`Message`](/docs/api/realtime-sdk/messages) | +| operation | An optional `MessageOperation` object containing metadata about the append operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | + + + + + | Parameter | Description | Type | |-----------|-------------|------| | message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the data to append | [`Message`](/docs/api/realtime-sdk/messages) | | operation | An optional `MessageOperation` object containing metadata about the append operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | +| params | Optional parameters sent as part of the request. As Ably adds supported parameters, they will be documented on the [docs pages](https://ably.com/docs) | `[String: Stringifiable]` (optional) | +| callback | A success or failure callback function. On success, it receives an `UpdateDeleteResult` object containing the new version of the message | - | + + ##### Returns @@ -1013,6 +1106,14 @@ Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-res On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + +##### Callback result + +On success, the callback receives an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +On failure, the callback receives an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. + + #### getMessageVersions @@ -1027,17 +1128,34 @@ On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-except `PaginatedResult get_message_versions(serial_or_message, params = dict())` + +`getMessageVersions(withSerial serial: String, callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)?)` + + Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/auth/capabilities). See [updating and deleting messages: message versions](/docs/messages/updates-deletes#versions) for more information. ##### Parameters + + | Parameter | Description | Type | |-----------|-------------|------| | serialOrMessage | Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](/docs/api/realtime-sdk/messages) | | params | Optional parameters sent as part of the query string | `Record``Param[]` (optional) | + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| serial | A serial identifier string of the message whose versions are to be retrieved | `String` | +| callback | A success or failure callback function. On success, it receives an [`PaginatedResult`](#paginated-result) object containing an array of [`Message`](#message) objects representing all versions of the message. | - | + + + ##### Returns @@ -1052,6 +1170,13 @@ On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an Failure to retrieve the message versions will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception) + +##### Callback result + +On success, the callback receives a [`PaginatedResult`](#paginated-result) encapsulating an array of [`Message`](#message) version objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next()`](#paginated-result) and [`first()`](#paginated-result) methods. + +On failure to retrieve message versions, the callback receives an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object with the failure reason. + diff --git a/src/pages/docs/api/rest-sdk/channels.mdx b/src/pages/docs/api/rest-sdk/channels.mdx index 98709998bb..64a69fb4e5 100644 --- a/src/pages/docs/api/rest-sdk/channels.mdx +++ b/src/pages/docs/api/rest-sdk/channels.mdx @@ -465,7 +465,7 @@ On failure to retrieve message history, the `error` contains an [`ErrorInfo`](#e - + #### getMessage @@ -481,6 +481,10 @@ On failure to retrieve message history, the `error` contains an [`ErrorInfo`](#e `Message get_message(serial_or_message)` + +`getMessageWithSerial(_ serial: String, callback: (ARTMessage?, ARTErrorInfo?) -> Void)` + + Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities). See [updating and deleting messages: retrieving the latest version](/docs/messages/updates-deletes#get) for more information. @@ -519,6 +523,19 @@ Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the l On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). + +| Parameter | Description | Type | +|-----------|-------------|------| +| serial | A serial identifier string of the message to retrieve | `String` | +| callback | A success or failure callback function. On success, it receives an [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message | - | + +##### Callback result + +On success, the callback receives a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. + +On failure, the callback receives an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. + + #### updateMessage @@ -533,18 +550,41 @@ On failure, raises an [`AblyException`](/docs/api/realtime-sdk/types#ably-except `UpdateDeleteResult update_message(message, operation=None, params=dict())` + +`update(_ message: ARTMessage, operation: ARTMessageOperation?, params: [String: ARTStringifiable]?, callback: ((ARTUpdateDeleteResult?, ARTErrorInfo?) -> Void)?)` + + Publishes an update to an existing message with shallow mixin semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities). + +Note: Note that this publishes an update, it does not mutate the original message if passed in. + + See [updating and deleting messages: updates](/docs/messages/updates-deletes#update) for more information. ##### Parameters + + | Parameter | Description | Type | |-----------|-------------|------| | message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the fields to update | [`Message`](/docs/api/realtime-sdk/messages) | | operation | An optional `MessageOperation` object containing metadata about the update operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | | params | Optional parameters sent as part of the query string | `Record` (optional) | + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the fields to update | [`Message`](/docs/api/realtime-sdk/messages) | +| operation | An optional `MessageOperation` object containing metadata about the update operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | +| params | Optional parameters sent as part of the request. As Ably adds supported parameters, they will be documented on the [docs pages](https://ably.com/docs) | `[String: Stringifiable]` (optional) | +| callback | A success or failure callback function. On success, it receives an `UpdateDeleteResult` object containing the new version of the message | (optional) | + + + ##### Returns @@ -557,6 +597,14 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +##### Callback result + +On success, the callback receives an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +On failure, the callback receives an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. + + #### deleteMessage @@ -571,18 +619,37 @@ Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-res `UpdateDeleteResult delete_message(message, operation=None, params=dict())` + +`delete(_ message: ARTMessage, operation: ARTMessageOperation?, params: [String: ARTStringifiable]?, callback: ((ARTUpdateDeleteResult?, ARTErrorInfo?) -> Void)?)` + + Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses shallow mixin semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-delete-own** or **message-delete-any** [capability](/docs/auth/capabilities). See [updating and deleting messages: deletes](/docs/messages/updates-deletes#delete) for more information. ##### Parameters + + | Parameter | Description | Type | |-----------|-------------|------| | message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | [`Message`](/docs/api/realtime-sdk/messages) | | operation | An optional `MessageOperation` object containing metadata about the delete operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | | params | Optional parameters sent as part of the query string | `Record` (optional) | + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | [`Message`](/docs/api/realtime-sdk/messages) | +| operation | An optional `MessageOperation` object containing metadata about the delete operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | +| params | Optional parameters sent as part of the request. As Ably adds supported parameters, they will be documented on the [docs pages](https://ably.com/docs) | `[String: Stringifiable]` (optional) | +| callback | A success or failure callback function. On success, it receives an `UpdateDeleteResult` object containing the new version of the message | (optional) | + + + ##### Returns @@ -595,6 +662,14 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +##### Callback result + +On success, the callback receives an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +On failure, the callback receives an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. + + #### appendMessage @@ -609,6 +684,10 @@ Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-res `UpdateDeleteResult append_message(message, operation=None, params=dict())` + +`append(_ message: ARTMessage, operation: ARTMessageOperation?, params: [String: ARTStringifiable]?, callback: ((ARTUpdateDeleteResult?, ARTErrorInfo?) -> Void)?)` + + Appends data to an existing message. The supplied `data` field is appended to the previous message's data, while all other fields (`name`, `extras`) replace the previous values if provided. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities). For publishing a high rate of appends, you typically want to use a realtime client, not a REST client, in order to have message order preservation. See [append ordering](/docs/messages/updates-deletes#append-ordering). @@ -617,12 +696,27 @@ See [updating and deleting messages: appends](/docs/messages/updates-deletes#app ##### Parameters + + | Parameter | Description | Type | |-----------|-------------|------| | message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the data to append | [`Message`](/docs/api/realtime-sdk/messages) | | operation | An optional `MessageOperation` object containing metadata about the append operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | | params | Optional parameters sent as part of the query string | `Record` (optional) | + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the data to append | [`Message`](/docs/api/realtime-sdk/messages) | +| operation | An optional `MessageOperation` object containing metadata about the append operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | +| params | Optional parameters sent as part of the request. As Ably adds supported parameters, they will be documented on the [docs pages](https://ably.com/docs) | `[String: Stringifiable]` (optional) | +| callback | A success or failure callback function. On success, it receives an `UpdateDeleteResult` object containing the new version of the message | - | + + + ##### Returns @@ -635,6 +729,14 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +##### Callback result + +On success, the callback receives an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + +On failure, the callback receives an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. + + #### getMessageVersions @@ -649,16 +751,33 @@ Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-res `PaginatedResult get_message_versions(serial_or_message, **params)` + +`getMessageVersions(withSerial serial: String, callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)?)` + + Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/auth/capabilities). See [updating and deleting messages: versions](/docs/messages/updates-deletes#versions) for more information. ##### Parameters + + | Parameter | Description | Type | |-----------|-------------|------| | serialOrMessage | Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](/docs/api/realtime-sdk/messages) | -| params | Optional parameters sent as part of the query string | `Record` (optional) | +| params | Optional parameters sent as part of the query string | `Record``Param[]` (optional) | + + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| serial | A serial identifier string of the message whose versions are to be retrieved | `String` | +| callback | A success or failure callback function. On success, it receives an [`PaginatedResult`](#paginated-result) object containing an array of [`Message`](#message) objects representing all versions of the message. | - | + + ##### Returns @@ -674,6 +793,14 @@ On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an Failure to retrieve the message versions will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception) + +##### Callback result + +On success, the callback receives a [`PaginatedResult`](#paginated-result) encapsulating an array of [`Message`](#message) version objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next()`](#paginated-result) and [`first()`](#paginated-result) methods. + +On failure to retrieve message versions, the callback receives an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object with the failure reason. + + ## Related types