# Channels
## Channels
The `Channels` object, accessed from the [realtime library client constructor](https://ably.com/docs/api/realtime-sdk#channels), is used to create and destroy `Channel` objects. It exposes the following public methods:
### Channels Methods
#### getGet
`Channel get(String name, ChannelOptions channelOptions?)`
`Channel get(String name, ChannelOptions channelOptions?)`
`ARTRealtimeChannel get(String channelName, ARTChannelOptions channelOptions);`
`Channel get(String channelName, ChannelOptions channelOptions)`
Creates a new [Channel](#properties) object if none for the channel exists, or returns the existing channel object.
#### getDerived
`Channel get(String name, DeriveOptions deriveOptions, ChannelOptions channelOptions?)`
Creates a new [Channel](#properties) object if none for the channel exists, or returns the existing channel object. The Channel object is created or returned with the specified `DeriveOptions` and optional `ChannelOptions`.
Derived channels enables you to subscribe to a filtered subset of messages on a channel. See [subscription filters](https://ably.com/channels#subscription-filters) for more information.
#### releaseRelease
`release(String channelName)`
`void release(String channelName)`
`bool Release(string channelName)`
Releases a [Channel](#properties) object, deleting it from the local SDK client instance and enabling it to be garbage collected. It also removes any listeners associated with the channel on this specific client instance.
This method only affects the local client-side representation of the channel. The channel itself on the Ably platform is not deleted or changed, and other client instances (in the same or different processes) are unaffected. Any listeners attached through other client instances remain active.
After releasing a channel, calling `channels.get(channelName)` will create a fresh channel object with no listeners. If the channel was attached before being released, the new channel object will be in the `initialized` state, not `attached`.
If using a singleton client pattern with multiple execution contexts, be cautious when calling `release` as it will affect all parts of your application using that client instance. Consider using `unsubscribe` for specific listeners instead.
**Note**: To release a channel, the [channel state](https://ably.com/docs/channels/states) must be `initialized`, `detached` or `failed`.
## Channel
The Channel object, created via the [Channels](#channels-object) object, is used to interact with a specific channel.
### Channel PropertiesARTRealtimeChannel PropertiesAbly::Realtime::Channel Attributesio.ably.lib.realtime.Channel MembersIO.Ably.Realtime.RealtimeChannel Properties
The `Channel` object exposes the following public propertiesattributesmembers:
#### stateState
The current `io.ably.lib.realtime.ChannelState state`[`IO.Ably.Realtime.ChannelState`](https://ably.com/docs/api/realtime-sdk/channels#channel-state) `state``Ably::Realtime::Channel::STATE state``ARTRealtimeChannelState``ChannelState` of this `Channel`. See the supported [channel states](https://ably.com/docs/channels/states) for more information.
#### errorReasonreasonerror_reasonErrorReason
When a channel failure occurs this attributememberpropertyproperty is populated.
The type is [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info)[`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception).
#### nameName
The name `String` unique to this channel.
#### presencePresence
Provides access to the [Presence](https://ably.com/docs/presence-occupancy/presence) object for this channel which can be used to access members present on the channel, or participate in presence.
#### push
Provides access to the [PushChannel](https://ably.com/docs/api/realtime-sdk/push#push-channel) object for this channel which can be used to access members present on the channel, or participate in presence.
#### object
Provides access to the [RealtimeObject](https://ably.com/docs/liveobjects) for this channel which can be used to read, modify and subscribe to LiveObjects on a channel.
#### objects
Provides access to the [Objects](https://ably.com/docs/liveobjects) object for this channel which can be used to read, modify and subscribe to LiveObjects on a channel.
#### params
The current [channel parameters](https://ably.com/docs/channels/options#params) configured for this channel.
#### modes
The current [channel modes](https://ably.com/docs/channels/options#modes) configured for this channel.
### Channel Methods
#### publishPublish
There are three overloaded versions of this method:
There are two overloaded versions of this method:
`publish(String name, Object data): Promise`
`Deferrable publish(String name, Object data) -> yields`
`void publish(String name, Object data, CompletionListener listener)`
`void Publish(string name, object data, Action callback = null, string clientId = null)`
`publish(name: String?, data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)`
`Future publish(name: String name, data: Object data, message: Message message)`
Publish a single message on this channel based on a given event name and payload. A callbacklistener may optionally be passed in to this call to be notified of success or failure of the operation. When publish is called with this client library, it [won't attempt to implicitly attach to the channel](https://ably.com/docs/channels/states#attach), so long as [transient publishing](https://ably.com/docs/pub-sub/advanced#transient-publish) is available in the library. Otherwise, the client will implicitly attach.
Publish a single message on this channel based on a given event name and payload. When publish is called with this client library, it [won't attempt to implicitly attach to the channel](https://ably.com/docs/channels/states#attach), so long as [transient publishing](https://ably.com/docs/pub-sub/advanced#transient-publish) is available in the library. Otherwise, the client will implicitly attach.
`publish(Object message): Promise`
Publish a single message on this channel. When publish is called with this client library, it [won't attempt to implicitly attach to the channel](https://ably.com/docs/channels/states#attach), so long as [transient publishing](https://ably.com/docs/pub-sub/advanced#transient-publish) is available in the library. Otherwise, the client will implicitly attach.
`publish(Object[] messages): Promise`
`Deferrable publish(Message[] messages) -> yields`
`void publish(Message[] messages, CompletionListener listener)`
`void Publish(IEnumerable messages, Action callback = null)`
`publish(messages: [ ARTMessage ], callback: ((ARTErrorInfo?) -> Void)?)`
`Future publish(messages: List messages)`
Publish several messages on this channel. A callbacklistenerblock may optionally be passed in to this call to be notified of success or failure of the operation. When publish is called with this client library, it [won't attempt to implicitly attach to the channel](https://ably.com/docs/channels#transient-publish). If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `publish` will implicitly attach the channel.
Publish several messages on this channel. When publish is called with this client library, it [won't attempt to implicitly attach to the channel](https://ably.com/docs/channels#transient-publish). If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `publish` will implicitly attach the channel.
The entire `messages` array is published atomically. This means that:
* Either they will all be successfully published or none of them will
* The [max message size](https://ably.com/docs/platform/pricing/limits#message) limit applies to the total size of all messages in the array
* The publish will only count as a single message for the purpose of [per-channel rate limit](https://ably.com/docs/platform/pricing/limits#message)
* If you are using client-specified message IDs, [they must conform to certain restrictions](https://faqs.ably.com/client-specified-message-id-restrictions-for-multiple-messages-published-atomically)
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the message. The supported payload types are Strings, objects or arrays capable of JSON representation, buffers containing arbitrary binary data, and null. (Note that if sending a binary, that binary should be the entire payload; an object with a binary field within it may not be correctly encoded) | `Object` |
| message | A message object to publish | [`Message`](https://ably.com/docs/api/realtime-sdk/channels#message) |
| messages | An array of message objects to publish | [`Message []`](/docs/api/realtime-sdk/channels#message) |
| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the message. The supported payload types are String, Map, List, and null. | `Object` |
| message | A message object to publish | [`Message`](https://ably.com/docs/api/realtime-sdk/channels#message) |
| messages | An array of message objects to publish | [`Message []`](/docs/api/realtime-sdk/channels#message) |
| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the message. The supported payload types are Strings, JsonObject, binary data as byte arrays, and null. | `Object` |
| message | A message object to publish | [`Message`](https://ably.com/docs/api/realtime-sdk/channels#message) |
| messages | An array of message objects to publish | [`Message []`](/docs/api/realtime-sdk/channels#message) |
| listener | Listener to be notified on completion | [`CompletionListener`](https://ably.com/docs/api/realtime-sdk/channels#completion-listener) |
| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the message. The supported payload types are Strings, binary data as byte arrays, any plain c# class that can be serialized to Json, and null. | `Object` |
| message | A message object to publish | [`Message`](https://ably.com/docs/api/realtime-sdk/channels#message) |
| messages | An array of message objects to publish | [`Message []`](/docs/api/realtime-sdk/channels#message) |
| callback | is an action of the form `Action` which is called upon completion | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the message. The supported payload types are Strings, Hash or Array objects that can be serialized to JSON using `to_json`, binary data as `ASCII-8BIT` byte arrays, and null. (Note that if sending a byte array, it should be the entire payload; a hash or array with a bytearray field within it may not be correctly encoded) | `Object` |
| message | A message object to publish | [`Message`](https://ably.com/docs/api/realtime-sdk/channels#message) |
| messages | An array of message objects to publish | [`Message []`](/docs/api/realtime-sdk/channels#message) |
| &block | yields upon successfully publishing the message | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the message. The supported payload types are NS`String`, NS`Dictionary` or NS`Array` objects that can be serialized to JSON, binary data as `NSData`, and `nil`. | `Object` |
| message | A message object to publish | [`Message`](https://ably.com/docs/api/realtime-sdk/channels#message) |
| messages | An array of message objects to publish | [`Message []`](/docs/api/realtime-sdk/channels#message) |
| callback | called upon publishing the message, or with an error | - |
##### Returns
Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.
##### Callback result
On successful publish of the message, `err` is null. On failure to publish the message, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object describing the failure reason.
##### Callback result
On successful publish of the message, `error` is null. On failure to publish the message, `error` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object describing the failure reason.
##### Listener result
On successful publish of the message, the `onSuccess` method of the [`CompletionListener`](#completion-listener) is called. On failure to publish the message, the `onError` method is called with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) argument describing the failure reason.
##### Returns
A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the method.
On successful publish of the message, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) and any block provided to the method are executed. On failure to publish the message, the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) are called with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) argument describing the failure reason.
##### Returns
`Future`
On successful publish of the message, no exception will be thrown. On failure to publish the message, an `AblyException` will be thrown with an [`errorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) property describing the failure reason.
#### subscribeSubscribe
There are overloaded versions of this method:
`subscribe(listener): Promise`
`void subscribe(MessageListener listener)`
`void Subscribe(Action handler)`
`subscribe → yields Message`
`subscribe(callback: (ARTMessage) -> Void) -> ARTEventListener?`
`StreamSubscription subscribe().listen((ably.Message) -> void)`
Subscribe to messages on this channel. The caller supplies a listener functiona lambda expressionan implementation of the [MessageListener](#message-listener) interfacea block, which is called each time one or more messages arrives on the channel.
`subscribe(String event, listener?): Promise`
`void subscribe(String name, MessageListener listener)`
`void Subscribe(string name, Action handler)`
`subscribe(String name) → yields Message`
`subscribe(name: String, callback: (ARTMessage) -> Void) -> ARTEventListener?`
`StreamSubscription subscribe(name: String).listen((ably.Message) -> void)`
Subscribe to messages with a given event name on this channel. The caller supplies a listener functiona lambda expressionan implementation of the [MessageListener](#message-listener) interfacea block, which is called each time one or more matching messages arrives on the channel.
`subscribe(String[] events, listener?): Promise`
`void subscribe(String[] names, MessageListener listener)`
`subscribe(String *names) → yields Message`
`StreamSubscription subscribe(names: List).listen((ably.Message) -> void)`
Subscribe a single listener to messages on this channel for multiple event `name` values.
`subscribe(filter, listener?): Promise`
Registers a listener for messages on this channel that match the supplied filter. The filter is used to provide server-side filtering of messages as part of [filtered subscriptions](https://ably.com/docs/pub-sub/advanced#subscription-filters).
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| event | The event name to subscribe to | `String` |
| events | An array of event names to subscribe to | `String[]` |
| listener | is a function of the form `function(message)` to be called for each message | - |
| filter | a filter object that is used to provide server-side filtering of messages as part of [filtered subscriptions](https://ably.com/docs/pub-sub/advanced#subscription-filters) | `Object` |
| Parameter | Description | Type |
|-----------|-------------|------|
| name | The event name to subscribe to | `String` |
| names | An array of event names to subscribe to | `String[]` |
| [`MessageListener`](#message-listener) listener | Message listener to be notified for matching messages | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| name | The event name to subscribe to | `String` |
| handler | called with each matching [`message`](#message) when received on the channel | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| name | The event name to subscribe to | `String` |
| names | An argument array of event names to subscribe to | `*argument` |
| &block | yields each matching message when received on the channel | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| name | The event name to subscribe to | `String` |
| callback | called with each matching [`message`](#message) when received on the channel | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| name | The event name to subscribe to | `String` |
| names | An array of event names to subscribe to | `String[]` |
##### Returns
Returns a promise. On successful channel attachment, the promise is fulfilled with a [`ChannelStateChange`](#channel-state-change) object. If the channel was already attached, then the promised will resolve with `null`. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.
##### Considerations
* If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `subscribe` will implicitly attach the channel. However, regardless of the implicit attach outcome, the listenerblockhandler will still be registered
* Calling subscribe with an event name is a convenient way to subscribe only to messages matching that event name. But this is purely a client-side filter, for convenience. It has no effect on what messages are actually sent by the server to the client. All clients attached to a given channel receive every message sent on that channel (that their capabilities allow them to receive); the channel is the unit of distribution. To filter messages server-side, you need to use [filtered subscriptions](https://ably.com/docs/pub-sub/advanced#subscription-filters) and provide a `filter` when calling `subscribe()`.
* If `subscribe` is called more than once with the same listenerblockhandler, then duplicates will be registered. For example, if you `subscribe` twice with the same listenerblockhandler and a message is later received, the same listenerblockhandler will be invoked twice
* The registered listenerblockhandler remains active on the channel regardless of the current channel state. For example, if you call `subscribe` when a channel is `attached` and it later becomes `detached` or even `failed`, when the channel is reattached and a message is received, the listenersblockshandlers originally registered will still be invoked. Listeners are only removed when calling [`unsubscribe`](#unsubscribe)`streamSubscription.close` or when a channel is `released` using the `Realtime.channels.release(name)``Realtime.Channels.Release(name)` method
* If an exception is thrown in the subscribe listener and bubbles up to the event emitter, it will be caught and logged at `error` level, so as not to affect other listeners for the same event
#### unsubscribeUnsubscribe
There are seventhree overloaded versions of this method:
`unsubscribe(String event, listener)`
`void unsubscribe(String name, MessageListener listener)`
`bool Unsubscribe(string eventName, Action handler)`
`unsubscribe(String name, &listener_proc)`
`unsubscribe(name: String, listener: ARTEventListener)`
Unsubscribe the given listener for the specified event name. This removes an earlier event-specific subscription.
`unsubscribe(listener)`
`void unsubscribe(MessageListener listener)`
`bool Unsubscribe(Action handler)`
`unsubscribe(&listener_proc)`
`unsubscribe(listener: ARTEventListener)`
Unsubscribe the given listener (for any/all event names). This removes an earlier subscription.
`unsubscribe(String[] events, listener)`
Unsubscribe the given listener from all event names in the array.
`unsubscribe(String event)`
Unsubscribe all listeners for a given event name.
`unsubscribe(String[] events)`
Unsubscribe all listeners for all event names in the array.
`unsubscribe(filter, listener?)`
Unsubscribe all listeners for a given filter.
`streamSubscription` obtained from a subscription can be used to cancel a listener by calling `streamSubscription.cancel`.
`unsubscribe()`
`unsubscribe()`
`void unsubscribe()`
`void Unsubscribe()`
`unsubscribe()`
Unsubscribes all listeners to messages on this channel. This removes all earlier subscriptions.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| event | The event name to unsubscribe from | `String` |
| events | An array of event names to unsubscribe from | `String[]` |
| listener | is the callback listener function that was previously subscribed | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| name | The event name to unsubscribe from | `String` |
| listener | previously registered listener | [`MessageListener`](#message-listener) |
| Parameter | Description | Type |
|-----------|-------------|------|
| name | The event name to unsubscribe from | `String` |
| handler | is the lambda expression that was previously subscribed | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| name | The event name to unsubscribe from | `String` |
| &listener_block | previously registered listener block | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| name | The event name to unsubscribe from | `String` |
| listener | previous return value from a `subscribe` call | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| name | The event name to unsubscribe from | `String` |
#### historyHistory
`history(Object params?): Promise>`
`PaginatedResult history(Param []` options)`
`Task> HistoryAsync(PaginatedRequestParams dataQuery, bool untilAttach = false)`
`Deferrable history(Hash options) -> yields PaginatedResult`
`history(query: ARTRealtimeHistoryQuery?, callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void) throws`
`Future> history(Hash options)`
Gets a [paginated](#paginated-result) set of historical messages for this channel. If the [channel is configured to persist messages to disk](https://faqs.ably.com/how-long-are-messages-stored-for), then message history will [typically be available for 24 - 72 hours](https://faqs.ably.com/how-long-are-messages-stored-for). If not, messages are only retained in memory by the Ably service for two minutes.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| params | an optional object containing the query parameters, as specified in the [message history API documentation](https://ably.com/docs/api/realtime-sdk/history#channel-history) | `Object` |
| Parameter | Description | Type |
|-----------|-------------|------|
| options | an optional object containing the query parameters, as specified in the [message history API documentation](https://ably.com/docs/api/realtime-sdk/history#channel-history) | [`Param []`](#param) |
| Parameter | Description | Type |
|-----------|-------------|------|
| dataQuery | an optional object containing the query parameters, as specified in the [message history API documentation](https://ably.com/docs/api/realtime-sdk/history#channel-history) | `PaginatedRequestParams` |
| Parameter | Description | Type |
|-----------|-------------|------|
| options | an optional set of key value pairs containing the query parameters, as specified in the [message history API documentation](https://ably.com/docs/api/realtime-sdk/history#channel-history) | `Hash` |
| &block | yields a `PaginatedResult` object | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| query | an optional object containing the query parameters, as specified in the [message history API documentation](https://ably.com/docs/api/realtime-sdk/history#channel-history) | `ARTRealtimeHistoryQuery` |
| callback | called with a [`ARTPaginatedResult`](#paginated-result)`<`[`ARTMessage`](#message)`>` object or an error | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| options | an optional object containing the query parameters, as specified in the [message history API documentation](https://ably.com/docs/api/realtime-sdk/history#channel-history) | `Object` |
Further details of the supported `options` params, see [message history API documentation](https://ably.com/docs/api/realtime-sdk/history#channel-history).
##### Returns
Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](#paginated-result) object containing an array of messages. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.
##### Callback result
On success, `resultPage` contains a [`PaginatedResult`](#paginated-result) encapsulating an array of [`Message`](#message) 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 history, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object with the failure reason.
##### Returns
On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods.
Failure to retrieve the message history will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception)
##### Returns
The return value is `Task>` which needs to be awaited.
On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`NextAsync`](#paginated-result) and [`FirstAsync`](#paginated-result) methods.
Failure to retrieve the message history will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception)
##### Returns
A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the method.
On success, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) and any block provided to the method yield a [`PaginatedResult`](#paginated-result) that encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next()`](#paginated-result) and [`first()`](#paginated-result) methods.
Failure to retrieve the message history will trigger the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object with the failure reason.
#### getMessage
`getMessage(serialOrMessage: string | Message): Promise`
`Message getMessage(String serial)`
`Message get_message(serial_or_message)`
Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](https://ably.com/docs/auth/capabilities).
See [updating and deleting messages: retrieving the latest version](https://ably.com/docs/messages/updates-deletes#get) for more information.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| serialOrMessage | Either the serial identifier string of the message to retrieve, or a [`Message`](https://ably.com/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](https://ably.com/docs/api/realtime-sdk/messages) |
##### Returns
Returns a promise which, upon success, will be fulfilled with a [`Message`](https://ably.com/docs/api/realtime-sdk/messages) object representing the latest version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object which explains the error.
| Parameter | Description | Type |
|-----------|-------------|------|
| serial | Serial identifier string of the message to retrieve | `String` |
##### Returns
Returns a [`Message`](https://ably.com/docs/api/realtime-sdk/messages) object representing the latest version of the message.
| Parameter | Description | Type |
|-----------|-------------|------|
| serial_or_message | Either the serial identifier string of the message to retrieve, or a `Message` object containing a populated `serial` field | `str` or `Message` |
##### Returns
Returns a [`Message`](https://ably.com/docs/api/realtime-sdk/messages) object representing the latest version of the message.
On failure, raises an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception).
#### updateMessage
`updateMessage(message: Message, operation?: MessageOperation): Promise`
`void updateMessage(Message message, MessageOperation operation, Callback callback)`
`UpdateDeleteResult update_message(message, operation=None, params=dict())`
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](https://ably.com/docs/auth/capabilities).
See [updating and deleting messages: updates](https://ably.com/docs/messages/updates-deletes#update) for more information.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| message | A [`Message`](https://ably.com/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the fields to update | [`Message`](https://ably.com/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) |
##### Returns
Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](https://ably.com/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object which explains the error.
##### Returns
Invokes the provided `Callback` with an [`UpdateDeleteResult`](https://ably.com/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message on success, or with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object describing the error on failure.
##### Returns
Returns an [`UpdateDeleteResult`](https://ably.com/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message.
On failure, raises an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception).
#### deleteMessage
`deleteMessage(message: Message, operation?: MessageOperation): Promise`
`void deleteMessage(Message message, MessageOperation operation, Callback callback)`
`UpdateDeleteResult delete_message(message, operation=None, params=dict())`
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](https://ably.com/docs/auth/capabilities).
See [updating and deleting messages: deletes](https://ably.com/docs/messages/updates-deletes#delete) for more information.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| message | A [`Message`](https://ably.com/docs/api/realtime-sdk/messages) object containing a populated `serial` field | [`Message`](https://ably.com/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) |
##### Returns
Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](https://ably.com/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object which explains the error.
##### Returns
Invokes the provided `Callback` with an [`UpdateDeleteResult`](https://ably.com/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message on success, or with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object describing the error on failure.
##### Returns
Returns an [`UpdateDeleteResult`](https://ably.com/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message.
On failure, raises an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception).
#### appendMessage
`appendMessage(message: Message, operation?: MessageOperation): Promise`
`void appendMessage(Message message, MessageOperation operation, Callback callback)`
`UpdateDeleteResult append_message(message, operation=None, params=dict())`
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](https://ably.com/docs/auth/capabilities).
See [updating and deleting messages: appends](https://ably.com/docs/messages/updates-deletes#append) for more information.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| message | A [`Message`](https://ably.com/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the data to append | [`Message`](https://ably.com/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) |
##### Returns
Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](https://ably.com/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object which explains the error.
##### Returns
Invokes the provided `Callback` with an [`UpdateDeleteResult`](https://ably.com/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message on success, or with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object describing the error on failure.
##### Returns
Returns an [`UpdateDeleteResult`](https://ably.com/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message.
On failure, raises an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception).
#### getMessageVersions
`getMessageVersions(serialOrMessage: string | Message, params?: Record): Promise>`
`PaginatedResult getMessageVersions(String serial, Param[] params)`
`PaginatedResult get_message_versions(serial_or_message, params = dict())`
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](https://ably.com/docs/auth/capabilities).
See [updating and deleting messages: message versions](https://ably.com/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`](https://ably.com/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](https://ably.com/docs/api/realtime-sdk/messages) |
| params | Optional parameters sent as part of the query string | `Record``Param[]` (optional) |
##### Returns
Returns a promise which, upon success, will be fulfilled with a [`PaginatedResult`](#paginated-result) object containing an array of [`Message`](https://ably.com/docs/api/realtime-sdk/messages) objects representing all versions of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object which explains the error.
##### Returns
On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods.
Failure to retrieve the message versions will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception)
#### setOptions
`setOptions(options): Promise`
Set the [ChannelOptions](#channel-options) for the channel.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| options | The options to set for the channel | `ChannelOptions` |
##### Returns
Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.
#### attachAttach
`attach(): Promise`
`void attach()`
`void Attach(Action callback = null)`
`Deferrable attach -> yields`
`attach(callback: ((ARTErrorInfo?) -> Void)?)`
`Future attach()`
Attach to this channel ensuring the channel is created in the Ably system and all messages published on the channel will be received by any channel listeners registered using `subscribe()``Subscribe()``subscribe`. Any resulting channel state change will be emitted to any listeners registered using the [`on``On`](#on) or [`once``Once`](#once) methods.
As a convenience, `attach()``Attach()``attach` will be called implicitly if [`subscribe()``Subscribe()``subscribe`](#subscribe) for the `Channel` is called, or [`enter()``Enter()``enter`](https://ably.com/docs/api/realtime-sdk/presence#enter) or [`subscribe()``Subscribe()``subscribe`](https://ably.com/docs/api/realtime-sdk/presence#subscribe) is called on the [`Presence`](https://ably.com/docs/presence-occupancy/presence) for this `Channel`.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| &block | yields once the channel becomes attached | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| callback | is a lambda expression of the form `Action` and is called once the channel attach succeeds or fails | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| callback | called once the channel becomes attached or if an error occurs | - |
##### Returns
Returns a promise. On successful attachment, the promise is fulfilled with a [`ChannelStateChange`](#channel-state-change) object. If the channel was already attached, then the promised is fulfilled with `null`. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.
##### Returns
A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the attach method.
On successful attachment, the success callbacks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) are called and any block provided to the method is yielded. Failure to attach will trigger the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object with the failure reason.
##### Returns
`Future`
Failure to attach will throw an `AblyException` with an [errorInfo](https://ably.com/docs/api/realtime-sdk/types#error-info) property with the failure reason.
#### detachDetach
`detach(): Promise`
`void detach()`
`void Detach(Action callback = null)`
[`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) `detach -> yields`
`detach(callback: ((`[`ARTErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info)`?) -> Void)?)`
`Future detach()`
Detach from this channel. Any resulting channel state change will be emitted to any listeners registered using the [`on``On`](#on) or [`once``Once`](#once) methods.
Please note: Once all clients globally have detached from the channel, the channel will be released in the Ably service within two minutes.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| callback | is a lambda expression in the form `Action` and is called once the channel detach succeeds or fails | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| &block | yields once the channel becomes detached | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| callback | called once the channel becomes detached or if an error occurs | - |
##### Returns
Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.
##### Returns
A [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the detach method.
On successful detachment, the registered success blocks for the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) and any block provided to the method are executed. Failure to detach will trigger the `errback` callbacks of the [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object with the failure reason.
##### Returns
`Future`
Failure to detach will throw an `AblyException` with an [errorInfo](https://ably.com/docs/api/realtime-sdk/types#error-info) property with the failure reason.
#### onOn
There are threetwo overloaded versions of this method:
`on(String event, listener(`[`ChannelStateChange`](#channel-state-change)` stateChange))`
`on(`[`ChannelEvent`](#channel-event)` *event) -> yields` [`ChannelStateChange`](#channel-state-change)
`void on(`[`ChannelEvent`](#channel-event)` event,` [`ChannelStateListener`](#channel-state-listener)` listener)`
`void On(`[`ChannelEvent`](#channel-event)` event, Action<`[`ChannelStateChange`](#channel-state-change)`> action)`
`on(event:` [`ARTChannelEvent`](#channel-event)`, call: (`[`ARTChannelStateChange?`](#channel-state-change)`) -> Void) -> ARTEventListener`
`Stream<`[`ChannelEvent`](#channel-event)`> on(`[`ChannelEvent`](#channel-event)` channelEvent)`
The Stream returned can be subscribed for with a listener.
`final streamSubscription = stream.listen(listener)`
Register the given listener blockfunctionlistener for the specified [`ChannelEvent`](#channel-event) on the `Channel`.
The listener is passed a [`ChannelStateChange``ARTChannelStateChange`](#channel-state-change) object that contains the current state, previous state, a boolean indicating whether the channel was resumed, and an optional reason for the state change.
`on(String[] events, listener(ChannelStateChange stateChange))`
Same as above, but registers multiple listeners, one for each event in the array.
`on(listener(ChannelStateChange stateChange))`
`on -> yields ChannelStateChange`
`void On(Action listener)`
`void on(ChannelStateListener listener)`
`on(call: (ARTChannelStateChange?) -> Void) -> ARTEventListener`
`Stream on()`
The Stream returned can be subscribed for with a listener.
`final streamSubscription = stream.listen(listener)`
Register the given listener blockfunctionlambda expressionlistener for all [`ChannelEvents`](#channel-event) on the `Channel`.
The listener is passed a [`ChannelStateChange``ARTChannelStateChange`](#channel-state-change) object that contains the current state, previous state, the event, a boolean indicating whether the channel was resumed, and an optional reason for the state change.
If an exception is thrown in the listener and bubbles up to the event emitter, it will be caught and logged at `error` level, so as not to affect other listeners for the same event
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| event(s) | the channel event(s) to subscribe to, see [`ChannelEvent`](#channel-event) for supported channel events | `String` or `String[]` |
| listener | is a function of the form `function(stateChange)` to be notified for matching event changes | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event to subscribe to | [`ChannelEvent`](#channel-event) |
| listener | listener to be notified for matching event changes | [`ChannelStateListener`](#channel-state-listener) |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event to subscribe to | [`ChannelEvent`](#channel-event) |
| action | lambda expression to be notified for matching event changes | [`ChannelStateChange`](#channel-state-listener) |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event as a Symbol such as `:attached` or a `ChannelEvent` object to subscribe to | [`ChannelEvent`](#channel-event) |
| &block | listener block that is yielded to for matching event changes | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the `ARTChannelEvent` to subscribe to | [`ARTChannelEvent`](#channel-event) |
| call | called possibly with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event to subscribe to | [`ChannelEvent`](#channel-event) |
#### onceOnce
There are two overloaded versions of this method:
`once(String event, listener(ChannelStateChange stateChange))`
`once(ChannelEvent *event) -> yields ChannelStateChange`
`void once(ChannelEvent event, ChannelStateListener listener)`
`void Once(ChannelEvent event, Action action)`
`once(event: ARTChannelEvent, call: (ARTChannelStateChange?) -> Void) -> ARTEventListener`
`once(ChannelEvent event)`
Register the given listener blockfunctionlambda expressionlistener for a single occurrence of the specified [`ChannelEvent`](#channel-event) on the `Channel`. Once the listener has been called, it is removed as a registered listener and will not be called again.
The listener is passed a [`ChannelStateChange``ARTChannelStateChange`](#channel-state-change) object that contains the current state, previous state, the event, a boolean indicating whether the channel was resumed, and an optional reason for the event change.
`once(listener(ChannelStateChange stateChange))`
`once -> yields ChannelStateChange`
`void once(ChannelStateListener listener)`
`void Once(Action listener)`
`once(call: (ARTChannelStateChange?) -> Void) -> ARTEventListener`
`once()`
Register the given listener blockfunctionlambda expressionlistener for a single occurrence of any [`ChannelEvent`](#channel-event) on the `Channel`. Once the listener has been called, it is removed as a registered listener and will not be called again.
The listener is passed a [`ChannelStateChange``ARTChannelStateChange`](#channel-state-change) object that contains the current state, previous state, the event, a boolean indicating whether the channel was resumed, and an optional reason for the event change.
If an exception is thrown in the listener and bubbles up to the event emitter, it will be caught and logged at `error` level, so as not to affect other listeners for the same event
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event to subscribe to, see [`ChannelEvent`](#channel-event) for supported channel events | `String` |
| listener | is a function of the form `function()` to be notified for a single occurrence of a matching event change. The current event is available as `this.event` | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event to subscribe to | [`ChannelEvent`](#channel-event) |
| listener | listener to be notified for a single occurrence of a matching event change | [`ChannelStateListener`](#channel-state-listener) |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event to subscribe to | [`ChannelEvent`](#channel-event) |
| listener | listener lambda expression that is notified only once for a matching event change | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event as a Symbol such as `:attached` or a `ChannelEvent` object to subscribe to | [`ChannelEvent`](#channel-event) |
| &block | listener block that is yielded to for a single occurrence of a matching event change | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the `ARTChannelEvent` to subscribe to | [`ARTChannelEvent`](#channel-event) |
| call | called possibly with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event to subscribe to | [`ChannelEvent`](#channel-event) |
#### offOff
There are sixtwo overloaded versions of this method:
`off(String event, listener)`
`off(ChannelEvent *event, &block)`
`void off(ChannelEvent event, ChannelStateListener listener)`
`void Off(ChannelEvent event, Action listener)`
`off(event: ARTChannelEvent, listener: ARTEventListener)`
`off(ChannelEvent event)`
Remove the given listener blocklistener for the [`ChannelEvent`](#channel-event).
`off(listener)`
`off(&block)`
`void off(ChannelStateListener listener)`
`void Off(Action listener)`
`off(listener: ARTEventListener)`
`off()`
Remove the given listener block for all [`ChannelEvents`](#channel-event).
`off(String[] events, listener)`
Removes the given listener from all [`ChannelEvents`](#channel-event) in the array.
`off(String event)`
Removes all listeners for a given [`ChannelEvent`](#channel-event).
`off(String[] events)`
Removes all listeners for all [`ChannelEvents`](#channel-event) in the array.
`off()`
Removes all listeners (including both those registered against specific events and those registered without an event).
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| event(s) | the channel event(s) to unsubscribe from | `String` or `String[]` |
| listener | is the listener function to be removed | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event to unsubscribe from | [`ChannelEvent`](#channel-event) |
| listener | is the listener to be removed | [`ChannelStateListener`](#channel-state-listener) |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event to unsubscribe from | [`ChannelEvent`](#channel-event) |
| listener | is the listener function to be removed | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the channel event as a Symbol such as `:detached` or a `ChannelEvent` object to unsubscribe from | [`ChannelEvent`](#channel-event) |
| &block | is the listener block to be removed | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| event | the `ARTChannelEvent` to unsubscribe from | [`ARTChannelEvent`](#channel-event) |
| listener | previous return value from a `on` or `once` call | - |
| Parameter | Description | Type |
|-----------|-------------|------|
| streamSubscription | obtained from calling `on` can be used to cancel a listener by calling `streamSubscription.cancel` | - |
#### whenState
`whenState(targetState): Promise`
Checks if a channel is in a given state and returns `null` if it is, else calls [`once()`](#once) for the given state.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| targetState | The [`ChannelState`](#channel-state) to wait for | `ChannelState` |
##### Returns
Returns a promise. If the channel is already in the given state, the promise will immediately resolve to `null`. If not, it will call [`once()`](#once) to return a promise which resolves the next time the channel transitions to the given state.
## Related types
### ChannelStateARTRealtimeChannelStateChannel::STATE Enumio.ably.lib.realtime.ChannelState EnumIO.Ably.Realtime.ChannelState Enumably.ChannelState Enum
`ChannelState` is a String with a value matching any of the [Realtime Channel states](https://ably.com/docs/channels/states).
```javascript
var ChannelStates = [
'initialized',
'attaching',
'attached',
'detaching',
'detached',
'failed',
'suspended'
]
```
```javascript
var ChannelStates = [
'initialized',
'attaching',
'attached',
'detaching',
'detached',
'failed',
'suspended'
]
```
`io.ably.lib.realtime.ChannelState` is an enum representing all the [Realtime Channel states](https://ably.com/docs/channels/states).
```java
public enum ChannelState {
initialized, // 0
attaching, // 1
attached, // 2
detaching, // 3
detached, // 4
failed // 5
}
```
`IO.Ably.Realtime.ChannelState` is an enum representing all the [Realtime Channel states](https://ably.com/docs/channels/states).
```csharp
public enum ChannelState
{
Initialized = 0,
Attaching = 1,
Attached = 2,
Detaching= 3,
Detached = 4,
Failed = 5
};
```
`Ably::Realtime::Channel::STATE` is an enum-like value representing all the [Realtime Channel states](https://ably.com/docs/channels/states). `STATE` can be represented interchangeably as either symbols or constants.
#### Symbol states
```ruby
:initialized # => 0
:attaching # => 1
:attached # => 2
:detaching # => 3
:detached # => 4
:failed # => 5
```
#### Constant states
```ruby
Channel::STATE.Initialized # => 0
Channel::STATE.Attaching # => 1
Channel::STATE.Attached # => 2
Channel::STATE.Detaching # => 3
Channel::STATE.Detached # => 4
Channel::STATE.Failed # => 5
```
#### Example usage
```ruby
# Example with symbols
channel.on(:attached) { ... }
# Example with constants
channel.on(Ably::Realtime::Channel::STATE.Attached) { ... }
# Interchangeable
Ably::Realtime::Channel::STATE.Attached == :attached # => true
```
`ARTRealtimeChannelState` is an enum representing all the [Realtime Channel states](https://ably.com/docs/channels/states).
```objc
typedef NS_ENUM(NSUInteger, ARTRealtimeChannelState) {
ARTRealtimeChannelInitialized,
ARTRealtimeChannelAttaching,
ARTRealtimeChannelAttached,
ARTRealtimeChannelDetaching,
ARTRealtimeChannelDetached,
ARTRealtimeChannelFailed
};
```
```swift
public enum ARTRealtimeChannelState : UInt {
case Initialized
case Attaching
case Attached
case Detaching
case Detached
case Failed
}
```
`ably.ChannelState` is an enum representing all the [Realtime Channel states](https://ably.com/docs/channels/states).
```flutter
enum ChannelState {
initialized,
attaching,
attached,
detaching,
detached,
suspended,
failed
}
```
### ChannelEventARTChannelEventChannel::EVENT Enumio.ably.lib.realtime.ChannelEvent EnumIO.Ably.Realtime.ChannelEvent Enumably.ChannelEvent Enum
`ChannelEvent` is a String that can be emitted as an event on the `Channel` object; either a [ChannelState](https://ably.com/docs/channels/states) or an `update` event.
```javascript
var ChannelEvents = [
'initialized',
'attaching',
'attached',
'detaching',
'detached',
'failed',
'suspended',
'update'
]
```
```javascript
var ChannelEvents = [
'initialized',
'attaching',
'attached',
'detaching',
'detached',
'failed',
'suspended',
'update'
]
```
`io.ably.lib.realtime.ChannelEvent` is an enum representing all the events that can be emitted be the `Channel`; either a [ChannelState](https://ably.com/docs/channels/states) or an `update` event.
```java
public enum ChannelEvent {
initialized, // 0
attaching, // 1
attached, // 2
detaching, // 3
detached, // 4
failed // 5
update // 6
}
```
`IO.Ably.Realtime.ChannelEvent` is an enum representing all the events that can be emitted be the `Channel`; either a [ChannelState](https://ably.com/docs/channels/states) or an `Update` event.
```csharp
public enum ChannelEvent
{
Initialized = 0,
Attaching = 1,
Attached = 2,
Detaching= 3,
Detached = 4,
Failed = 5,
Update = 6
};
```
`Ably::Realtime::Channel::EVENT` is an enum-like value representing all the events that can be emitted be the `Channel`; either a [ChannelState](https://ably.com/docs/channels/states) or an `:update` event. `EVENT` can be represented interchangeably as either symbols or constants.
#### Symbol states
```ruby
:initialized # => 0
:attaching # => 1
:attached # => 2
:detaching # => 3
:detached # => 4
:failed # => 5
:update # => 6
```
#### Constant states
```ruby
Channel::EVENT.Initialized # => 0
Channel::EVENT.Attaching # => 1
Channel::EVENT.Attached # => 2
Channel::EVENT.Detaching # => 3
Channel::EVENT.Detached # => 4
Channel::EVENT.Failed # => 5
Channel::EVENT.Update # => 6
```
`ARTChannelEvent` is the enum emitted as the event in `ARTRealtimeChannel.on`; either a [ChannelState](https://ably.com/docs/api/realtime-sdk/channels#channel-state) or an `Update` event.
```objc
typedef NS_ENUM(NSUInteger, ARTChannelEvent) {
ARTChannelEventInitialized,
ARTChannelEventAttaching,
ARTChannelEventAttached,
ARTChannelEventDetaching,
ARTChannelEventDetached,
ARTChannelEventFailed,
ARTChannelEventUpdate
};
```
```swift
enum ARTChannelEvent : UInt {
case Initialized
case Attaching
case Attached
case Detaching
case Detached
case Failed
case Update
}
```
`ably.ChannelEvent` is an enum representing all the events that can be emitted be the `Channel`; either a [ChannelState](https://ably.com/docs/channels/states) or an `update` event.
```flutter
enum ChannelEvent {
initialized,
attaching,
attached,
detaching,
detached,
suspended,
failed,
update
}
```
### ChannelStateChangeARTRealtimeChannelStateChangeio.ably.lib.realtime.ChannelStateListener.ChannelStateChangeIO.Ably.Realtime.ChannelStateChangedably.ChannelStateChange
A `Ably::Models::ChannelStateChange``ChannelStateChange``ARTRealtimeChannelStateChange``ChannelStateChanged` is a type encapsulating state change information emitted by the [`Channel`](https://ably.com/docs/channels) object. See [`Channel#on`](https://ably.com/docs/api/realtime-sdk/channels#on) to register a listener for one or more events.
#### Attributes
| Attribute | Description | Type |
|-----------|-------------|------|
| current | the new current state | [`ChannelState``Channel::STATE``ARTRealtimeChannelState`](https://ably.com/docs/api/realtime-sdk/types#channel-state) |
| previous | the previous state. (for the `update` event, this will be equal to the `current` state) | [`ChannelState``Channel::STATE``ARTRealtimeChannelState`](https://ably.com/docs/api/realtime-sdk/types#channel-state) |
| event | the event that triggered this state change | [`ChannelEvent``Channel::EVENT``ARTChannelEvent`](https://ably.com/docs/api/realtime-sdk/types#channel-event) |
| reason | an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) containing any information relating to the transition | [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) |
| resumed | a boolean indicated whether message continuity on this channel is preserved, see [Nonfatal channel errors](https://ably.com/docs/channels#non-fatal-errors) for more info. | Boolean |
| Attribute | Description | Type |
|-----------|-------------|------|
| Current | the new current state | [`ChannelState`](https://ably.com/docs/api/realtime-sdk/types#channel-state) |
| Previous | the previous state. (for the `update` event, this will be equal to the `current` state) | [`ChannelState`](https://ably.com/docs/api/realtime-sdk/types#channel-state) |
| Event | the event that triggered this state change | [`ChannelEvent`](https://ably.com/docs/api/realtime-sdk/types#channel-event) |
| Reason | an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) containing any information relating to the transition | [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) |
| Resumed | a boolean indicated whether message continuity on this channel is preserved, see [Nonfatal channel errors](https://ably.com/docs/channels#non-fatal-errors) for more info. | Boolean |
### MessageARTMessageAbly::Models::Messageio.ably.lib.types.MessageIO.Ably.Messageably.Message
A `Message` represents an individual message that is sent to or received from Ably.
#### nameName
The event name, if provided.
**Type: `String`**
#### dataData
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``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `Map`, `List`
#### extrasExtras
Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](https://ably.com/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](https://ably.com/docs/pub-sub/advanced#ephemeral), and [`privileged`](https://ably.com/docs/platform/integrations/webhooks#skipping) objects.
**Type:** `JSONObject`, `JSONArray`_plain C# object that can be converted to JSON_`JSON Object``Hash`, `Array``Dictionary`, `Array``NSDictionary *`, `NSArray *``Map`, `List`
#### idId
A Unique ID assigned by Ably to this message.
**Type: `String`**
#### clientIdclient_id
The client ID of the publisher of this message.
**Type: `String`**
#### connectionIdconnection_id
The connection ID of the publisher of this message.
**Type: `String`**
#### connectionKeyconnection_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](https://ably.com/docs/pub-sub/advanced#publish-on-behalf).
**Type: `String`**
#### timestampTimestamp
Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object.
**Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`**
#### 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`**
### action
The action type of the message, one of the [`MessageAction`](https://ably.com/docs/api/realtime-sdk/types#message-action) enum values.
_Type: `enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }`_
### serial
A server-assigned identifier that will be the same in all future updates of this message. It can be used to add [annotations](https://ably.com/docs/messages/annotations) to a message or to [update or delete](https://ably.com/docs/messages/updates-deletes) it. Serial will only be set if you enable annotations, updates, deletes, and appends in [channel rules](https://ably.com/docs/channels#rules).
_Type: `String`_
### annotations
An object containing information about annotations that have been made to the object.
_Type: [`MessageAnnotations`](https://ably.com/docs/api/realtime-sdk/types#message-annotations)_
### version
An object containing version metadata for messages that have been updated or deleted. See [updating and deleting messages](https://ably.com/docs/messages/updates-deletes) for more information.
_Type: [`MessageVersion`](#message-version)_
### Message constructors
#### Message.fromEncoded
`Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message`
A static factory method to create a [`Message`](https://ably.com/docs/api/realtime-sdk/types#message) from a deserialized `Message`-like object encoded using Ably's wire protocol.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| encodedMsg | a `Message`-like deserialized object | `Object` |
| channelOptions | an optional [`ChannelOptions`](https://ably.com/docs/api/realtime-sdk/types#channel-options). If you have an encrypted channel, use this to allow the library to decrypt the data | `Object` |
##### Returns
A [`Message`](https://ably.com/docs/api/realtime-sdk/types#message) object
#### Message.fromEncodedArray
`Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[]`
A static factory method to create an array of [`Messages`](https://ably.com/docs/api/realtime-sdk/types#message) from an array of deserialized `Message`-like object encoded using Ably's wire protocol.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| encodedMsgs | an array of `Message`-like deserialized objects | `Array` |
| channelOptions | an optional [`ChannelOptions`](https://ably.com/docs/api/realtime-sdk/types#channel-options). If you have an encrypted channel, use this to allow the library to decrypt the data | `Object` |
##### Returns
An `Array` of [`Message`](https://ably.com/docs/api/realtime-sdk/types#message) objects
### ChannelOptions ObjectARTChannelOptionsChannelOptions Hashio.ably.lib.types.ChannelOptionsIO.Ably.Rest.ChannelOptionsably.ChannelOptions
Channel options are used for setting [channel parameters](https://ably.com/docs/channels/options) and [configuring encryption](https://ably.com/docs/channels/options/encryption).
`ChannelOptions`, a plain JavaScript object, may optionally be specified when instancing a [`Channel`](https://ably.com/docs/channels), and this may be used to specify channel-specific options. The following attributes can be defined on the object:
`ChannelOptions`, a Hash object, may optionally be specified when instancing a [`Channel`](https://ably.com/docs/channels), and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash:
`io.ably.lib.types.ChannelOptions` may optionally be specified when instancing a [`Channel`](https://ably.com/docs/channels), and this may be used to specify channel-specific options.
`ART``ChannelOptions` may optionally be specified when instancing a [`Channel`](https://ably.com/docs/channels), and this may be used to specify channel-specific options.
`IO.Ably.ChannelOptions` may optionally be specified when instancing a [`Channel`](https://ably.com/docs/channels), and this may be used to specify channel-specific options.
`ably.ChannelOptions` may optionally be specified when instancing a [`Channel`](https://ably.com/docs/channels), and this may be used to specify channel-specific options.
#### PropertiesMembersAttributes
| Property | Description | Type |
|----------|-------------|------|
| paramsParams | Optional [parameters](https://ably.com/docs/channels/options) which specify behaviour of the channel | `Map``JSON Object` |
| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](https://ably.com/docs/api/realtime-sdk/encryption#getting-started) | [`CipherParams`](https://ably.com/docs/api/realtime-sdk/encryption#cipher-params) or an options object containing at a minimum a `key` or a `Param[]` list containing at a minimum a `key` |
| Property | Description | Type |
|----------|-------------|------|
| :cipher | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](https://ably.com/docs/channels/options/encryption) | [`CipherParams`](https://ably.com/docs/api/realtime-sdk/encryption#cipher-params) or an options hash containing at a minimum a `key` |
| Property | Description | Type |
|----------|-------------|------|
| cipher | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](https://ably.com/docs/channels/options/encryption) | [`CipherParams`](https://ably.com/docs/api/realtime-sdk/encryption#cipher-params) |
#### Static methods
##### withCipherKey
`static ChannelOptions.withCipherKey(Byte[] or String key)`
A helper method to generate a `ChannelOptions` for the simple case where you only specify a key.
###### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| key | A binary `Byte[]` array or a base64-encoded `String` | `Byte[]` or `String` |
###### Returns
On success, the method returns a complete `ChannelOptions` object. Failure will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception).
#### DeriveOptions
Properties passed to [`getDerived()`](#get-derived) to filter the messages returned in a subscription to it.
##### Parameters
| Parameter | Description | Type |
|-----------|-------------|------|
| filter | The filter expression to use when creating or returning the derived channel. This is a [JMESPath](https://jmespath.org/) query | `String` |
#### io.ably.lib.realtime.ChannelStateListener
A `io.ably.lib.realtime.ChannelStateListener` is an interface allowing a client to be notified of [channel state changes](https://ably.com/docs/api/realtime-sdk/types#channel-state-change) for a [`Channel`](https://ably.com/docs/channels).
```java
public interface ChannelStateListener {
// Called when the channel state changes
public void onChannelStateChanged(ChannelStateChange stateChange, ErrorInfo reason);
}
```
#### io.ably.lib.realtime.CompletionListener
A `io.ably.lib.realtime.CompletionListener` is an interface allowing a client to be notified of the outcome of an asynchronous operation.
```java
public interface CompletionListener {
// Called when the associated operation completes successfully,
public void onSuccess();
// Called when the associated operation completes with an error.
public void onError(ErrorInfo reason);
}
```
### PaginatedRequestParams
`HistoryRequestParams` is a type that encapsulates the parameters for a history queries. For example usage see [`Channel#History`](https://ably.com/docs/api/realtime-sdk/history#channel-history).
#### Members
| Member | Description | Type |
|--------|-------------|------|
| Start | The start of the queried interval.
default: _null_ | `DateTimeOffset` |
| End | The end of the queried interval.
default: _null_ | `DateTimeOffset` |
| Limit | Limits the number of items returned by history or stats.
default: _null_ | `Integer` |
| Direction | Enum which is either `Forwards` or `Backwards`.
default: _Backwards_ | `Direction` enum |
| ExtraParameters | Optionally any extra query parameters that may be passed to the query. This is mainly used internally by the library to manage paging | `Dictionary` |
#### io.ably.lib.realtime.Channel.MessageListener
A `io.ably.lib.realtime.Channel.MessageListener` is an interface allowing a client to be notified when messages are received on a channel using a [channel subscription](https://ably.com/docs/pub-sub#subscribe).
```java
public interface MessageListener {
// Called when one or more messages are received
public void onMessage(Message message);
}
```
### PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.PaginatedResult
A `PaginatedResult` is a type that represents a page of results for all message and presence history, stats and REST presence requests. The response from a [Ably REST API paginated query](https://ably.com/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object.
#### PropertiesMembersAttributes
| Property | Description | Type |
|----------|-------------|------|
| itemsItems | contains the current page of results (for example an Array of [`Message`](#message) or `PresenceMessage` objects for a channel history request) | `Array ` |
#### Methods
##### firstFirst
`first(): Promise`
Returns a promise. On success, the promise is fulfilled with a new `PaginatedResult` for the first page of results. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.
`PaginatedResult first`
Returns a new [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/channels#paginated-result) for the first page of results. When using the Realtime library, the `first` method returns a [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) and yields a `PaginatedResult`.
`PaginatedResult first()`
Returns a new `PaginatedResult` for the first page of results.
`Task> FirstAsync()`
Returns a new `PaginatedResult` for the first page of results. The method is asynchronous and returns a Task which needs to be awaited to get the `PaginatedResult`.
`first(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)`
Returns a new `PaginatedResult` for the first page of results.
`Future first()`
Returns a new `PaginatedResult` for the first page of results.
##### hasNextHasNexthas_next?
`Boolean hasNext()`
`Boolean has_next?`
Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available.
##### isLastIsLastlast?
`Boolean isLast()`
`Boolean last?`
Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available.
##### nextNext
`next(): Promise`
Returns a promise. On success, the promise is fulfilled with a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `null` is returned. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.
`PaginatedResult next`
Returns a new [`PaginatedResult`](https://ably.com/docs/api/realtime-sdk/channels#paginated-result) loaded with the next page of results. If there are no further pages, then `null` is returned. When using the Realtime library, the `first` method returns a [`Deferrable`](https://ably.com/docs/api/realtime-sdk/types#deferrable) and yields a `PaginatedResult`.
`PaginatedResult next()`
Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `Null` is returned.
`Task> NextAsync()`
Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then a blank PaginatedResult will be returned. The method is asynchronous and return a Task which needs to be awaited to get the `PaginatedResult`.
`next(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)`
Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `nil` is returned.
`Future next()`
Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `null` is returned.
##### current
`current(): Promise`
Returns a promise. On success, the promise is fulfilled with a new `PaginatedResult` loaded with the current page of results. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.
#### Example
```javascript
const paginatedResult = await channel.history();
console.log('Page 0 item 0:' + paginatedResult.items[0].data);
const nextPage = await paginatedResult.next();
console.log('Page 1 item 1: ' + nextPage.items[1].data);
console.log('Last page?: ' + nextPage.isLast());
```
```nodejs
const paginatedResult = await channel.history();
console.log('Page 0 item 0:' + paginatedResult.items[0].data);
const nextPage = await paginatedResult.next();
console.log('Page 1 item 1: ' + nextPage.items[1].data);
console.log('Last page?: ' + nextPage.isLast());
```
```java
PaginatedResult firstPage = channel.history();
System.out.println("Page 0 item 0:" + firstPage.items[0].data);
if (firstPage.hasNext) {
PaginatedResult nextPage = firstPage.next();
System.out.println("Page 1 item 1:" + nextPage.items[1].data);
System.out.println("More pages?:" + Strong.valueOf(nextPage.hasNext()));
};
```
```csharp
PaginatedResult firstPage = await channel.HistoryAsync(null);
Message firstMessage = firstPage.Items[0];
Console.WriteLine("Page 0 item 0: " + firstMessage.data);
if (firstPage.HasNext)
{
var nextPage = await firstPage.NextAsync();
Console.WriteLine("Page 1 item 1:" + nextPage.Items[1].data);
Console.WriteLine("More pages?: " + nextPage.HasNext());
}
```
```ruby
# When using the REST sync library
first_page = channel.history
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
next_page = first_page.next
puts "Page 1 item 1: #{next_page.items[1].data}"
puts "Last page?: #{next_page.is_last?}"
end
# When using the Realtime EventMachine library
channel.history do |first_page|
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
first_page.next do |next_page|
puts "Page 1 item 1: #{next_page.items[1].data}"
puts "Last page?: #{next_page.is_last?}"
end
end
end
```
```objc
[channel history:^(ARTPaginatedResult *paginatedResult, ARTErrorInfo *error) {
NSLog(@"Page 0 item 0: %@", paginatedResult.items[0].data);
[paginatedResult next:^(ARTPaginatedResult *nextPage, ARTErrorInfo *error) {
NSLog(@"Page 1 item 1: %@", nextPage.items[1].data);
NSLog(@"Last page?: %d", nextPage.isLast());
}];
}];
```
```swift
channel.history { paginatedResult, error in
guard let paginatedResult = paginatedResult else {
print("No results available")
return
}
print("Page 0 item 0: \((paginatedResult.items[0] as! ARTMessage).data)")
paginatedResult.next { nextPage, error in
guard let nextPage = nextPage else {
print("No next page available")
return
}
print("Page 1 item 1: \((nextPage.items[1] as! ARTMessage).data)")
print("Last page? \(nextPage.isLast())")
}
}
```
### io.ably.lib.types.Param
`Param` is a type encapsulating a key/value pair. This type is used frequently in method parameters allowing key/value pairs to be used more flexible, see [`Channel#history`](https://ably.com/docs/api/realtime-sdk/history#channel-history) for an example.
Please note that `key` and `value` attributes are always strings. If an `Integer` or other value type is expected, then you must coerce that type into a `String`.
#### Members
| Parameter | Description | Type |
|-----------|-------------|------|
| key | The key value | `String` |
| value | The value associated with the `key` | `String` |