Ephemeral messages; _message partial

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. <br>__Type: @String@__
-
-h6(#data).
-  default: data
-  csharp: Data
-
-The message payload, if provided.<br>__Type: <span lang="default">@String@, @StringBuffer@, @JSON Object@</span><span lang="java">@String@, @ByteArray@, @JSONObject@, @JSONArray@</span><span lang="csharp">@String@, @byte[]@, @plain C# object that can be serialized to JSON@</span><span lang="ruby">@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@</span><span lang="python">@String@, @Bytearray@, @Dict@, @List@</span><span lang="php">@String@, @Binary String@, @Associative Array@, @Array@</span><span lang="objc">@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@</span><span lang="swift">@String@, @NSData@, @Dictionary@, @Array@</span><span lang="flutter">@String@, @Map@, @List@</span>__
-
-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.<br>__Type: <span lang="java">@JSONObject@, @JSONArray@</span><span lang="csharp">plain C# object that can be converted to JSON</span><span lang="jsall">@JSON Object@</span><span lang="ruby">@Hash@, @Array@</span><span lang="python">@Dict@, @List@</span><span lang="swift">@Dictionary@, @Array@</span><span lang="objc">@NSDictionary *@, @NSArray *@</span><span lang="php">@Associative Array@, @Array@</span>__
-
-h6(#id).
-  default: id
-  csharp: Id
-
-A Unique ID assigned by Ably to this message.<br>__Type: @String@__
-
-h6(#client-id).
-  default: clientId
-  csharp: ClientId
-  ruby: client_id
-  python: client_id
-
-The client ID of the publisher of this message.<br>__Type: @String@__
-
-h6(#connection-id).
-  default: connectionId
-  csharp: ConnectionId
-  ruby: connection_id
-  python: connection_id
-
-The connection ID of the publisher of this message.<br>__Type: @String@__
-
-h6(#timestamp).
-  default: timestamp
-  csharp: Timestamp
-
-Timestamp when the message was received by the Ably, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>.__Type: <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span>__
-
-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.<br>__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.<br>__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.<br>__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.<br>__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.<br>__Type: @Object@__
-
-h4. Returns
-
-An @Array@ of "@Message@":/docs/api/realtime-sdk/types#message objects
+<%= partial partial_version('types/_message') %>

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
 

content/api/rest-sdk/messages.textile

@@ -50,106 +50,4 @@ blang[javascript,nodejs].
   <p>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/</p>
   </aside>
 
-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. <br>__Type: @String@__
-
-h6(#data).
-  default: data
-  csharp,go: Data
-
-The message payload, if provided.<br>__Type: <span lang="default">@String@, @StringBuffer@, @JSON Object@</span><span lang="java">@String@, @ByteArray@, @JSONObject@, @JSONArray@</span><span lang="csharp">@String@, @byte[]@, @plain C# object that can be serialized to Json@</span><span lang="ruby">@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@</span><span lang="python">@String@, @Bytearray@, @Dict@, @List@</span><span lang="php">@String@, @Binary String@, @Associative Array@, @Array@</span><span lang="objc">@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@</span><span lang="swift">@String@, @NSData@, @Dictionary@, @Array@</span><span lang="flutter">@String@, @Map@, @List@</span>__
-
-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.<br>__Type: <span lang="java">@JSONObject@, @JSONArray@</span><span lang="csharp">plain C# object that can be converted to JSON</span><span lang="jsall">@JSON Object@</span><span lang="ruby">@Hash@, @Array@</span><span lang="python">@Dict@, @List@</span><span lang="swift">@Dictionary@, @Array@</span><span lang="objc">@NSDictionary *@, @NSArray *@</span><span lang="php">@Associative Array@, @Array@</span>__
-
-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<br>__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.<br>__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.<br>__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.<br>__Type: @String@__
-
-h6(#timestamp).
-  default: timestamp
-  csharp,go: Timestamp
-
-Timestamp when the message was received by the Ably, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>.__Type: <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span>__
-
-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.<br>__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.<br>__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.<br>__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.<br>__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.<br>__Type: @Object@__
-
-h4. Returns
-
-An @Array@ of "@Message@":/docs/api/rest-sdk/types#message objects
+<%= partial partial_version('types/_message') %>

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
 
-- <span lang="default">name</span><span lang="csharp,go">Name</span> := Event name, if provided<br>__Type: @String@__
+The event name, if provided. <br>__Type: @String@__
 
-- <span lang="default">data</span><span lang="csharp,go">Data</span> := The presence update payload, if provided<br>__Type: <span lang="java">@String@, @ByteArray@, @JSONObject@, @JSONArray@</span><span lang="csharp">@String@, @byte[]@, plain C# object that can be converted to Json</span><span lang="go">@String@, @[]byte@</span><span lang="jsall">@String@, @StringBuffer@, @JSON Object@</span><span lang="ruby">@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@</span><span lang="python">@String@, @Bytearray@, @Dict@, @List@</span><span lang="swift">@String@, @NSData@, @Dictionary@, @Array@</span><span lang="objc">@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@</span><span lang="php">@String@, @Binary String@, @Associative Array@, @Array@</span><span lang="flutter">@Object@</span>__
+h6(#data).
+  default: data
+  csharp: Data
 
-- <span lang="default">extras</span><span lang="csharp,go">Extras</span> := 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.<br>__Type: <span lang="java">@JSONObject@, @JSONArray@</span><span lang="csharp">plain C# object that can be converted to Json</span><span lang="go">@String@, @[]byte@</span><span lang="jsall">@JSON Object@</span><span lang="ruby">@Hash@, @Array@</span><span lang="python">@Dict@, @List@</span><span lang="swift">@Dictionary@, @Array@</span><span lang="objc">@NSDictionary *@, @NSArray *@</span><span lang="php">@Associative Array@, @Array@</span><span lang="flutter">@Map@, @List@</span>__
+The message payload, if provided.<br>__Type: <span lang="default">@String@, @StringBuffer@, @JSON Object@</span><span lang="java">@String@, @ByteArray@, @JSONObject@, @JSONArray@</span><span lang="csharp">@String@, @byte[]@, @plain C# object that can be serialized to JSON@</span><span lang="ruby">@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@</span><span lang="python">@String@, @Bytearray@, @Dict@, @List@</span><span lang="php">@String@, @Binary String@, @Associative Array@, @Array@</span><span lang="objc">@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@</span><span lang="swift">@String@, @NSData@, @Dictionary@, @Array@</span><span lang="flutter">@String@, @Map@, @List@</span>__
 
-- <span lang="default">id</span><span lang="csharp,go">Id</span> := 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<br>__Type: @String@__
+h6(#extras).
+  default: extras
+  csharp: Extras
 
-- <span lang="default">clientId</span><span lang="ruby,python">client_id</span><span lang="csharp,go">ClientId</span> := The client ID of the publisher of this message<br>__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.<br>__Type: <span lang="java">@JSONObject@, @JSONArray@</span><span lang="csharp">plain C# object that can be converted to JSON</span><span lang="jsall">@JSON Object@</span><span lang="ruby">@Hash@, @Array@</span><span lang="python">@Dict@, @List@</span><span lang="swift">@Dictionary@, @Array@</span><span lang="objc">@NSDictionary *@, @NSArray *@</span><span lang="php">@Associative Array@, @Array@</span>__
 
-- <span lang="default">connectionId</span><span lang="ruby,python">connection_id</span><span lang="csharp,go">ConnectionId</span> := The connection ID of the publisher of this message<br>__Type: @String@__
+h6(#id).
+  default: id
+  csharp: Id
 
-- <span lang="default">timestamp</span><span lang="csharp,go">Timestamp</span> := Timestamp when the message was received by the Ably service, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>__Type: <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span><span lang="flutter">@DateTime@</span>__
+A Unique ID assigned by Ably to this message.<br>__Type: @String@__
 
-- <span lang="default">encoding</span><span lang="csharp,go">Encoding</span> := 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@__
+h6(#client-id).
+  default: clientId
+  csharp: ClientId
+  ruby: client_id
+  python: client_id
 
-h3.
+The client ID of the publisher of this message.<br>__Type: @String@__
+
+h6(#connection-id).
+  default: connectionId
+  csharp: ConnectionId
+  ruby: connection_id
+  python: connection_id
+
+The connection ID of the publisher of this message.<br>__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.<br>__Type: @String@__
+
+h6(#timestamp).
+  default: timestamp
+  csharp: Timestamp
+
+Timestamp when the message was received by the Ably, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>.__Type: <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span>__
+
+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.<br>__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).

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.