From a29e4f4ccce7d2afbbccca564c54aecb737fa189 Mon Sep 17 00:00:00 2001 From: Simon Woolf Date: Thu, 17 Apr 2025 11:24:09 +0100 Subject: [PATCH 1/2] Use message partial in rest-sdk/messages and realtime-sdk/messages So we're not making the same change in multiple places. Copy the version from realtime-sdk to the partial since it seemed to have been kept more up to date than the partial version. (which is the sort of drift that we can avoid exactly by using partials!) --- content/api/realtime-sdk/messages.textile | 91 +------------------ content/api/rest-sdk/messages.textile | 104 +--------------------- content/partials/types/_message.textile | 69 ++++++++++---- 3 files changed, 55 insertions(+), 209 deletions(-) diff --git a/content/api/realtime-sdk/messages.textile b/content/api/realtime-sdk/messages.textile index f0a539a449..2544a4e3e6 100644 --- a/content/api/realtime-sdk/messages.textile +++ b/content/api/realtime-sdk/messages.textile @@ -57,93 +57,4 @@ h2(#properties). ruby: Attributes python: Attributes -A @Message@ represents an individual message that is sent to or received from Ably. - -h6(#name). - default: name - csharp: Name - -The event name, if provided.
__Type: @String@__ - -h6(#data). - default: data - csharp: Data - -The message payload, if provided.
__Type: @String@, @StringBuffer@, @JSON Object@@String@, @ByteArray@, @JSONObject@, @JSONArray@@String@, @byte[]@, @plain C# object that can be serialized to JSON@@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@@String@, @Bytearray@, @Dict@, @List@@String@, @Binary String@, @Associative Array@, @Array@@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@@String@, @NSData@, @Dictionary@, @Array@@String@, @Map@, @List@__ - -h6(#extras). - default: extras - csharp: Extras - -Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the "@push@":/docs/push/publish#payload, "@ref@":/docs/channels/messages#interactions and "@privileged@":/docs/integrations/webhooks#skipping objects.
__Type: @JSONObject@, @JSONArray@plain C# object that can be converted to JSON@JSON Object@@Hash@, @Array@@Dict@, @List@@Dictionary@, @Array@@NSDictionary *@, @NSArray *@@Associative Array@, @Array@__ - -h6(#id). - default: id - csharp: Id - -A Unique ID assigned by Ably to this message.
__Type: @String@__ - -h6(#client-id). - default: clientId - csharp: ClientId - ruby: client_id - python: client_id - -The client ID of the publisher of this message.
__Type: @String@__ - -h6(#connection-id). - default: connectionId - csharp: ConnectionId - ruby: connection_id - python: connection_id - -The connection ID of the publisher of this message.
__Type: @String@__ - -h6(#timestamp). - default: timestamp - csharp: Timestamp - -Timestamp when the message was received by the Ably, as milliseconds since the epocha @Time@ object
.__Type: @Integer@@Long Integer@@DateTimeOffset@@Time@@NSDate@__ - -h6(#encoding). - default: encoding - csharp: 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.
__Type: @String@__ - -h2(methods). - default: Message methods - -h6(#message-from-encoded). - default: Message.fromEncoded - -bq(definition). - default: 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. - -h4. Parameters - -- encodedMsg := a @Message@-like deserialized object.
__Type: @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.
__Type: @Object@__ - -h4. Returns - -A "@Message@":/docs/api/realtime-sdk/types#message object - -h6(#message-from-encoded-array). - default: Message.fromEncodedArray - -bq(definition). - default: 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. - -h4. Parameters - -- encodedMsgs := an array of @Message@-like deserialized objects.
__Type: @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.
__Type: @Object@__ - -h4. Returns - -An @Array@ of "@Message@":/docs/api/realtime-sdk/types#message objects +<%= partial partial_version('types/_message') %> diff --git a/content/api/rest-sdk/messages.textile b/content/api/rest-sdk/messages.textile index 7aca74a680..12c12ac560 100644 --- a/content/api/rest-sdk/messages.textile +++ b/content/api/rest-sdk/messages.textile @@ -50,106 +50,4 @@ blang[javascript,nodejs].

This API reference is for version 1.2 of the JavaScript SDK. Version 2.0 references are "available in TypeDoc.":https://ably.com/docs/sdk/js/v2.0/

-h2(#properties). - default: Properties - java: Members - ruby: Attributes - python: Attributes - -A @Message@ represents an individual message that is sent to or received from Ably. - -h6(#name). - default: name - csharp,go: Name - -The event name, if provided.
__Type: @String@__ - -h6(#data). - default: data - csharp,go: Data - -The message payload, if provided.
__Type: @String@, @StringBuffer@, @JSON Object@@String@, @ByteArray@, @JSONObject@, @JSONArray@@String@, @byte[]@, @plain C# object that can be serialized to Json@@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@@String@, @Bytearray@, @Dict@, @List@@String@, @Binary String@, @Associative Array@, @Array@@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@@String@, @NSData@, @Dictionary@, @Array@@String@, @Map@, @List@__ - -h6(#extras). - default: extras - csharp: Extras - -Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the "@push@":/docs/push/publish#sub-channels, "@ref@":/docs/channels/messages#interactions and "@privileged@":/docs/integrations/webhooks#skipping objects.
__Type: @JSONObject@, @JSONArray@plain C# object that can be converted to JSON@JSON Object@@Hash@, @Array@@Dict@, @List@@Dictionary@, @Array@@NSDictionary *@, @NSArray *@@Associative Array@, @Array@__ - -h6(#id). - default: id - csharp,go: Id - -A Unique ID assigned by Ably to this message. Can optionally be assigned by the client as part of "idempotent publishing":#idempotent
__Type: @String@__ - -h6(#client-id). - default: clientId - csharp,go: ClientId - ruby: client_id - python: client_id - -The client ID of the publisher of this message.
__Type: @String@__ - -h6(#connection-id). - default: connectionId - csharp,go: ConnectionId - ruby: connection_id - python: connection_id - -The connection ID of the publisher of this message.
__Type: @String@__ - -h6(#connection-key). - default: connectionKey - csharp,go: ConnectionKey - ruby,python: 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.
__Type: @String@__ - -h6(#timestamp). - default: timestamp - csharp,go: Timestamp - -Timestamp when the message was received by the Ably, as milliseconds since the epocha @Time@ object
.__Type: @Integer@@Long Integer@@DateTimeOffset@@Time@@NSDate@__ - -h6(#encoding). - default: encoding - csharp,go: 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.
__Type: @String@__ - -h2(methods). - default: Message methods - -h6(#message-from-encoded). - default: Message.fromEncoded - -bq(definition). - default: Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message - -A static factory method to create a "@Message@":/docs/api/rest-sdk/types#message from a deserialized @Message@-like object encoded using Ably's wire protocol. - -h4. Parameters - -- encodedMsg := a @Message@-like deserialized object.
__Type: @Object@__ -- channelOptions := an optional "@ChannelOptions@":/docs/api/rest-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.
__Type: @Object@__ - -h4. Returns - -A "@Message@":/docs/api/rest-sdk/types#message object - -h6(#message-from-encoded-array). - default: Message.fromEncodedArray - -bq(definition). - default: Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[] - -A static factory method to create an array of "@Messages@":/docs/api/rest-sdk/types#message from an array of deserialized @Message@-like object encoded using Ably's wire protocol. - -h4. Parameters - -- encodedMsgs := an array of @Message@-like deserialized objects.
__Type: @Array@__ -- channelOptions := an optional "@ChannelOptions@":/docs/api/rest-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.
__Type: @Object@__ - -h4. Returns - -An @Array@ of "@Message@":/docs/api/rest-sdk/types#message objects +<%= partial partial_version('types/_message') %> diff --git a/content/partials/types/_message.textile b/content/partials/types/_message.textile index fe718fe437..33724929f7 100644 --- a/content/partials/types/_message.textile +++ b/content/partials/types/_message.textile @@ -1,31 +1,68 @@ A @Message@ represents an individual message that is sent to or received from Ably. -h4. - default: Properties - java: Members - ruby: Attributes - python: Attributes +h6(#name). + default: name + csharp: Name -- nameName := Event name, if provided
__Type: @String@__ +The event name, if provided.
__Type: @String@__ -- dataData := The presence update payload, if provided
__Type: @String@, @ByteArray@, @JSONObject@, @JSONArray@@String@, @byte[]@, plain C# object that can be converted to Json@String@, @[]byte@@String@, @StringBuffer@, @JSON Object@@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@@String@, @Bytearray@, @Dict@, @List@@String@, @NSData@, @Dictionary@, @Array@@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@@String@, @Binary String@, @Associative Array@, @Array@@Object@__ +h6(#data). + default: data + csharp: Data -- extrasExtras := Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the "@push@":/docs/push/publish#payload, "@ref@":/docs/channels/messages#interactions and "@privileged@":/docs/integrations/webhooks#skipping objects.
__Type: @JSONObject@, @JSONArray@plain C# object that can be converted to Json@String@, @[]byte@@JSON Object@@Hash@, @Array@@Dict@, @List@@Dictionary@, @Array@@NSDictionary *@, @NSArray *@@Associative Array@, @Array@@Map@, @List@__ +The message payload, if provided.
__Type: @String@, @StringBuffer@, @JSON Object@@String@, @ByteArray@, @JSONObject@, @JSONArray@@String@, @byte[]@, @plain C# object that can be serialized to JSON@@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@@String@, @Bytearray@, @Dict@, @List@@String@, @Binary String@, @Associative Array@, @Array@@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@@String@, @NSData@, @Dictionary@, @Array@@String@, @Map@, @List@__ -- idId := Unique ID assigned by Ably to this message. Can optionally be assigned by the client as part of "idempotent publishing":/docs/pub-sub/advanced#idempotency
__Type: @String@__ +h6(#extras). + default: extras + csharp: Extras -- clientIdclient_idClientId := The client ID of the publisher of this message
__Type: @String@__ +Metadata and/or ancillary payloads, if provided. Valid payloads include "@push@":/docs/push/publish#payload, "@headers@" (a map of strings to strings for arbitrary customer-supplied metadata), "@ephemeral@":/docs/pub-sub/advanced#ephemeral, and "@privileged@":/docs/integrations/webhooks#skipping objects.
__Type: @JSONObject@, @JSONArray@plain C# object that can be converted to JSON@JSON Object@@Hash@, @Array@@Dict@, @List@@Dictionary@, @Array@@NSDictionary *@, @NSArray *@@Associative Array@, @Array@__ -- connectionIdconnection_idConnectionId := The connection ID of the publisher of this message
__Type: @String@__ +h6(#id). + default: id + csharp: Id -- timestampTimestamp := Timestamp when the message was received by the Ably service, as milliseconds since the epocha @Time@ object
__Type: @Integer@@Long Integer@@DateTimeOffset@@Time@@NSDate@@DateTime@__ +A Unique ID assigned by Ably to this message.
__Type: @String@__ -- encodingEncoding := 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
__Type: @String@__ +h6(#client-id). + default: clientId + csharp: ClientId + ruby: client_id + python: client_id -h3. +The client ID of the publisher of this message.
__Type: @String@__ + +h6(#connection-id). + default: connectionId + csharp: ConnectionId + ruby: connection_id + python: connection_id + +The connection ID of the publisher of this message.
__Type: @String@__ + +h6(#connection-key). + default: connectionKey + csharp,go: ConnectionKey + ruby,python: 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.
__Type: @String@__ + +h6(#timestamp). + default: timestamp + csharp: Timestamp + +Timestamp when the message was received by the Ably, as milliseconds since the epocha @Time@ object
.__Type: @Integer@@Long Integer@@DateTimeOffset@@Time@@NSDate@__ + +h6(#encoding). + default: encoding + csharp: 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.
__Type: @String@__ + +h3(constructors). default: Message constructors -h4(#message-from-encoded). +h6(#message-from-encoded). default: Message.fromEncoded bq(definition). @@ -42,7 +79,7 @@ h4. Returns A "@Message@":/docs/api/realtime-sdk/types#message object -h4(#message-from-encoded-array). +h6(#message-from-encoded-array). default: Message.fromEncodedArray bq(definition). From 565aed5582ce5a2196850adc34f7f91a9df0da51 Mon Sep 17 00:00:00 2001 From: Simon Woolf Date: Thu, 17 Apr 2025 11:25:41 +0100 Subject: [PATCH 2/2] Add docs for ephemeral publishes --- content/api/rest-api.textile | 2 +- content/pub-sub/advanced.textile | 30 ++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/content/api/rest-api.textile b/content/api/rest-api.textile index 08f2f56387..6e81fa1828 100644 --- a/content/api/rest-api.textile +++ b/content/api/rest-api.textile @@ -358,7 +358,7 @@ It is possible for a client publishing through REST to not receive an acknowledg h5(#message-extras). Message extras -Messages can include an optional @extras@ field, used by extensions to Ably's core realtime service. +Messages can include an optional @extras@ field, used by extensions to Ably's core realtime service. For example, @extras.ephemeral@ can be set to @true@ to "make an ephemeral publish":/docs/pub-sub/advanced#ephemeral. h5(#message-extras-push). Send push notification diff --git a/content/pub-sub/advanced.textile b/content/pub-sub/advanced.textile index 19bfa09a45..5248be1d53 100644 --- a/content/pub-sub/advanced.textile +++ b/content/pub-sub/advanced.textile @@ -901,6 +901,36 @@ channel := realtime.Channels.Get("chatroom") channel.Publish(context.Background(), "action", "boom!") ``` +h3(#ephemeral). Ephemeral messages + +A message can be marked as *ephemeral* to exempt it from: +- being stored in "persisted history":/docs/storage-history/storage +- being sent in "attachment rewinds":/docs/channels/options/rewind +- being sent to clients "resuming over a period of disconnection":/docs/connect/states +- being sent to "firehose, webhooks, and queue integrations":/docs/integrations + +In other words, it will be exempt from everything except being delivered to currently-connected realtime connections. + +This is useful for when you want a channel to have a mixture of messages, some of which you care about more than others. For example, say you have a chat room with ephemeral room reactions, and you are using @rewind=100@ so that new attachments get the last one hundred messages on the channel. Without this feature, you may only get 70 'real' messages in the rewind and 30 stale reactions, which you'd then need to filter out clientside. + +To mark a message as ephemeral, either include @ephemeral: true@ in the message's extras object, or (for REST publishes) include @ephemeral: true@ in the publish params. + +The following is an example of publishing an ephemeral message: + +```[realtime_javascript] +const channel = realtime.channels.get('chatroom'); +await channel.publish({name: 'emote', data: ':heart:', extras: { ephemeral: true }}); +``` + +```[rest_javascript] +const channel = rest.channels.get('chatroom'); +await channel.publish('emote', ':heart:', { ephemeral: true }); +// or +await channel.publish({ name: 'emote', data: ':heart:' }, { ephemeral: true }); +``` + +Note that if using the form of publish that takes an array of messages to be published atomically, either all the messages must be marked ephemeral or none of them. If they are mixed, the publish will be rejected. + h3(#idempotency). Idempotent publishing Idempotency ensures that multiple publishes of the same message cannot result in duplicate messages.