# Presence

## <If lang="javascript,nodejs,flutter">Presence Properties</If><If lang="objc,swift">ARTPresence Properties</If><If lang="ruby">Ably::Realtime::Presence Attributes</If><If lang="java">io.ably.lib.realtime.Presence Members</If><If lang="csharp">IO.Ably.Realtime.Presence Properties</If> 

The `Presence` object exposes the following public <If lang="javascript,nodejs,flutter,csharp,objc,swift">properties</If><If lang="ruby">attributes</If><If lang="java">members</If>:

### <If lang="javascript,nodejs,flutter,objc,swift,java">syncComplete</If><If lang="ruby">sync_complete?</If><If lang="csharp">SyncComplete</If> 

A `boolean` field indicating whether the presence member set is synchronized with server after a channel attach.

When a channel is attached, the Ably service immediately synchronizes the presence member set with the client. Typically this process completes in milliseconds, however when the presence member set is very large, bandwidth constraints may slow this synchronization process down.

## Methods

### <If lang="javascript,nodejs,objc,swift,java,ruby">enter</If><If lang="csharp">EnterAsync</If> 

In order to enter and be present on a channel, the client must [be identified by having a client ID](https://faqs.ably.com/authenticated-and-identified-clients), [have permission to be present](https://faqs.ably.com/using-capabilities-to-manage-client-access-privileges-on-channels), and be attached to the channel. For simplicity, the library will implicitly attach to a channel when entering. Entering when already entered is treated as an [update](#update).

<If lang="java,objc,swift,ruby,csharp">

There are two overloaded versions of this method. <If lang="java,objc,swift,ruby">With both versions, a <If lang="objc,swift,csharp">callback</If><If lang="ruby">block</If><If lang="java">completion listener</If> can optionally be passed in to be notified of success or failure to enter.</If>

<If lang="ruby">

`Deferrable enter() -> yields`

</If>
<If lang="java">

`void enter(CompletionListener listener)`

</If>
<If lang="objc,swift">

`enter(data: nil, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="csharp">

`Task EnterAsync()`

</If>

Enter a presence channel without any data. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel.

<If lang="flutter">

`enter(Object data, callback(ErrorInfo err))`

</If>
<If lang="ruby">

`Deferrable enter(Object data) -> yields`

</If>
<If lang="java">

`void enter(Object data, CompletionListener listener)`

</If>
<If lang="objc,swift">

`enter(data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="csharp">

`Task EnterAsync(object clientData)`

</If>

Enter a presence channel and provide data that is associated with the current present member. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel.

</If>
<If lang="javascript,nodejs">

`enter(Object data?): Promise<void>`

Enter a presence channel with optional data that is associated with the current present member. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel.

</If>

#### Parameters

<If lang="javascript,nodejs,csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the current present member. The supported payload types are <If lang="javascript,nodejs">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="csharp">strings, plain object convertible to json, binary data as byte arrays, and null</If>. | `Object` |

</If>

<If lang="flutter,java,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the current present member. The supported payload types are <If lang="flutter">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="java">Strings, JsonObject, binary data as byte arrays, and null</If><If lang="ruby">Strings, Hash or Array objects that can be serialized to JSON using `to_json`, binary data as `ASCII-8BIT` byte arrays, and null</If><If lang="swift,objc">The supported payload types are <If lang="objc">`NS`</If>`String`, <If lang="objc">`NS`</If>`Dictionary` or <If lang="objc">`NS`</If>`Array` objects that can be serialized to JSON, binary data as `NSData`, and `nil`</If>. | `Object` |
| <If lang="java">listener</If><If lang="ruby">&block</If><If lang="swift,objc">callback</If> | <If lang="java">Listener to be notified on completion</If><If lang="ruby">yields upon successfully entering the channel</If><If lang="swift,objc">called upon successfully entering the channel, or with an error</If> | <If lang="java">[CompletionListener](#completion-listener)</If> |

</If>

<If lang="javascript,nodejs">

#### 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.

</If>
<If lang="swift,objc">

#### Callback result

On successfully entering the channel, `err` is null. On failure to enter, `err` contains an [ErrorInfo](#error-info) object describing the failure reason.

</If>
<If lang="java">

#### Listener result

On successfully entering the channel, the `onSuccess` method of the [CompletionListener](#completion-listener) is called. On failure to enter, the `onError` method is called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>
<If lang="csharp">

#### Task result

On successfully entering the channel, the method will complete. On failure to enter, an `AblyException` will be thrown with an [ErrorInfo](#error-info) object describing the failure reason.

</If>
<If lang="ruby">

#### Returns

A [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the method.

On successfully entering the channel, 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 enter, the `errback` callbacks of the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) are called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

### <If lang="javascript,nodejs,objc,java,swift,flutter,ruby">leave</If><If lang="csharp">Leave</If> 

In order to leave the presence set of a channel, the client must have already [entered and been present](#enter).

<If lang="flutter,objc,swift,java,ruby,csharp">

There are two overloaded versions of this method. <If lang="csharp"></If><If lang="flutter,objc,swift,java,ruby">With both versions, a <If lang="flutter,objc,swift">callback</If><If lang="ruby">block</If><If lang="java">completion listener</If> can optionally be passed in to be notified of success or failure to leave.</If>

<If lang="ruby">

`Deferrable leave() -> yields`

</If>
<If lang="java">

`void leave(CompletionListener listener)`

</If>
<If lang="swift,objc">

`leave(data: nil, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="csharp">

`Task LeaveAsync()`

</If>

Leave a presence channel without emitting any data.

<If lang="flutter">

`leave(Object data, callback(ErrorInfo err))`

</If>
<If lang="ruby">

`Deferrable leave(Object data) -> yields`

</If>
<If lang="java">

`void leave(Object data, CompletionListener listener)`

</If>
<If lang="swift,objc">

`leave(data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="csharp">

`Task LeaveAsync(object clientData)`

</If>

Leave a presence channel and emit data that is associated with the current leaving member.

</If>
<If lang="javascript,nodejs">

`leave(Object data?): Promise<void>`

Leave a presence channel and emit an optional data that is associated with the current leaving member.

</If>

#### Parameters

<If lang="javascript,nodejs,csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the current present member. The supported payload types are <If lang="javascript,nodejs">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="csharp">strings, plain objects convertible to json, binary data as byte arrays, and null</If>. | `Object` |

</If>

<If lang="flutter,java,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the current present member. The supported payload types are <If lang="flutter">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="java">Strings, JsonObject, binary data as byte arrays, and null</If><If lang="ruby">Strings, Hash or Array objects that can be serialized to JSON using `to_json`, binary data as `ASCII-8BIT` byte arrays, and null</If><If lang="swift,objc">The supported payload types are <If lang="objc">`NS`</If>`String`, <If lang="objc">`NS`</If>`Dictionary` or <If lang="objc">`NS`</If>`Array` objects that can be serialized to JSON, binary data as `NSData`, and `nil`</If>. | `Object` |
| <If lang="java">listener</If><If lang="ruby">&block</If><If lang="swift,objc">callback</If> | <If lang="java">Listener to be notified on completion</If><If lang="ruby">yields upon successfully leaving the channel</If><If lang="swift,objc">called upon leaving the channel, or with an error</If> | <If lang="java">[CompletionListener](#completion-listener)</If> |

</If>

<If lang="javascript,nodejs">

#### 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.

</If>
<If lang="swift,objc">

#### Callback result

On successfully leaving the channel, `err` is null. On failure to leave, `err` contains an [ErrorInfo](#error-info) object describing the failure reason.

</If>
<If lang="java">

#### Listener result

On successfully leaving the channel, the `onSuccess` method of the [CompletionListener](#completion-listener) is called. On failure to leave, the `onError` method is called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>
<If lang="csharp">

#### Task result

On successfully leaving the channel, the method will complete. On failure to leave, an `AblyException` will be thrown with an [ErrorInfo](#error-info) object describing the failure reason.

</If>
<If lang="ruby">

#### Returns

A [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the method.

On successfully leaving the channel, 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 leave, the `errback` callbacks of the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) are called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

### <If lang="javascript,nodejs,flutter,java,objc,swift,ruby">update</If><If lang="csharp">Update</If>

Clients can update their member data on the channel which will trigger a broadcast of this update to all presence subscribers. The [pre-requisites for](#update) <If lang="javascript,nodejs,flutter,java,objc,swift,ruby">`update`</If><If lang="csharp">`Update`</If> are the same as for <If lang="javascript,nodejs,flutter,java,objc,swift,ruby">[`enter`](#enter).</If><If lang="csharp">[`Enter`](#enter).</If> If an attempt to <If lang="javascript,nodejs,flutter,java,objc,swift,ruby">`update`</If><If lang="csharp">`Update`</If> is made before the client has entered the channel, the update is treated as an <If lang="javascript,nodejs,flutter,java,objc,swift,ruby">`enter`</If><If lang="csharp">`Enter`</If>.

<If lang="javascript,nodejs"></If><If lang="csharp"></If><If lang="flutter,java,objc,swift,ruby">A <If lang="flutter,objc,swift">callback</If><If lang="ruby">block</If><If lang="java">completion listener</If> can optionally be passed in to be notified of success or failure to update the member data.<br /><br /></If>

<If lang="flutter">

`update(Object data, callback(ErrorInfo err))`

</If>
<If lang="nodejs,javascript">

`update(Object data?): Promise<void>`

</If>
<If lang="ruby">

`Deferrable update(Object data) -> yields`

</If>
<If lang="java">

`void update(Object data, CompletionListener listener)`

</If>
<If lang="swift,objc">

`update(data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="csharp">

`Task UpdateAsync(object clientData)`

</If>

Update the current member's data and broadcast an update event to all subscribers. `data` may be `null`. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `update` will implicitly attach the channel.

#### Parameters

<If lang="javascript,nodejs,csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the current present member. The supported payload types are <If lang="javascript,nodejs">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="csharp">strings, plain objects convertible to json, binary data as byte arrays, and null</If>. | `Object` |

</If>

<If lang="flutter,java,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the current present member. The supported payload types are <If lang="flutter">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="java">Strings, JsonObject, binary data as byte arrays, and null</If><If lang="ruby">Strings, Hash or Array objects that can be serialized to JSON using `to_json`, binary data as `ASCII-8BIT` byte arrays, and null</If><If lang="swift,objc">The supported payload types are <If lang="objc">`NS`</If>`String`, <If lang="objc">`NS`</If>`Dictionary` or <If lang="objc">`NS`</If>`Array` objects that can be serialized to JSON, binary data as `NSData`, and `nil`</If>. | `Object` |
| <If lang="java">listener</If><If lang="ruby">&block</If><If lang="swift,objc">callback</If> | <If lang="java">Listener to be notified on completion</If><If lang="ruby">yields upon successfully updating the member data</If><If lang="swift,objc">called upon updating the channel, or with an error</If> | <If lang="java">[CompletionListener](#completion-listener)</If> |

</If>

<If lang="javascript,nodejs">

#### 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.

</If>
<If lang="objc,swift">

#### Callback result

On successfully updating the data, `err` is null. On failure to update, `err` contains an [ErrorInfo](#error-info) object describing the failure reason.

</If>
<If lang="java">

#### Listener result

On successfully updating the data, the `onSuccess` method of the [CompletionListener](#completion-listener) is called. On failure to update, the `onError` method is called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>
<If lang="csharp">

#### Task result

On successfully entering the channel, the method will complete. On failure to enter, an `AblyException` will be thrown with an [ErrorInfo](#error-info) object describing the failure reason. The methods needs to be awaited otherwise the exception won't be thrown.

</If>
<If lang="ruby">

#### Returns

A [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the method.

On successfully updating the data, 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 update, the `errback` callbacks of the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) are called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">get</If><If lang="csharp">Get</If> 

Get the current presence member set for this channel. Typically, this method returns the member set immediately as the member set is retained in memory by the client. However, by default this method will wait until the presence member set is synchronized, so if the synchronization is not yet complete following a channel being attached, this method will wait until the presence member set is synchronized.

When a channel is attached, the Ably service immediately synchronizes the presence member set with the client. Typically this process completes in milliseconds, however when the presence member set is very large, bandwidth constraints may slow this synchronization process down.

When a channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `get` will implicitly attach the channel.

<If lang="javascript,nodejs">

`get(Object params?): Promise<PresenceMessage[]>`

</If>
<If lang="flutter">

`get(Object options, callback(ErrorInfo err, PresenceMessage[] members))`

</If>
<If lang="ruby">

`Deferrable get(Hash options) -> yields PresenceMessage[]`

</If>
<If lang="java">

`PresenceMessage[] get(Param[] options)`

</If>
<If lang="swift,objc">

`get(query: ARTRealtimePresenceQuery, callback: ([ARTPresenceMessage], ARTErrorInfo?) -> Void)`

</If>
<If lang="csharp">

`Task<IEnumerable<PresenceMessage>> GetAsync(GetOptions { bool waitForSync = true, string clientId = "", string connectionId = "" })`

</If>

Gets an array of members present on the channel as [PresenceMessage](#presence-message) objects.

<If lang="javascript,nodejs,ruby,java,swift,objc">

#### Parameters

<If lang="javascript,nodejs,java,csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs">params</If><If lang="java">options</If><If lang="csharp">query</If> | an optional <If lang="javascript,nodejs">object</If><If lang="java">object</If><If lang="csharp">set of parameters</If> containing query parameters as specified below. | <If lang="java">[`Param[]`](/docs/api/realtime-sdk/presence#param)</If><If lang="csharp">`PaginatedRequestParams`</If> |

</If>

<If lang="flutter,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="flutter,ruby">options</If><If lang="swift,objc">query</If> | <If lang="flutter">an optional object containing query parameters</If><If lang="ruby">an optional set of symbol key and value pairs containing the query parameters</If> as specified below. | |
| <If lang="ruby">&block</If><If lang="swift,objc">callback</If> | <If lang="ruby">yields a [`PresenceMessage[]`](/docs/api/realtime-sdk/presence#presence-message) array</If><If lang="swift,objc">called with a [ARTPresenceMessage], or with an error</If> | |

</If>

</If>

#### <If lang="java,ruby,flutter">`options` parameters</If><If lang="javascript,nodejs">`params` parameters</If><If lang="objc,swift">`ARTRealtimePresenceQuery` properties</If><If lang="csharp">`GetOptions` properties</If>

| Property | Description | Type |
|----------|-------------|------|
| <If lang="javascript,nodejs,flutter,java,objc,swift,csharp">clientId</If><If lang="ruby">:client_id</If> | when provided, will filter array of members returned that match the provided <If lang="javascript,nodejs,flutter,java,objc,swift">[clientId](https://ably.com/docs/api/realtime-sdk#client-id)</If><If lang="ruby">[client_id](https://ably.com/docs/api/realtime-sdk#client-id)</If><If lang="csharp">[ClientId](https://ably.com/docs/api/realtime-sdk#client-id)</If> string | `String` |
| <If lang="javascript,nodejs,flutter,java,objc,swift,csharp">connectionId</If><If lang="ruby">:connection_id</If> | when provided, will filter array of members returned that match the provided <If lang="javascript,nodejs,flutter,java,objc,swift">[connectionId](https://ably.com/docs/api/realtime-sdk/connection#id)</If><If lang="csharp">[ConnectionId](https://ably.com/docs/api/realtime-sdk/connection#id)</If><If lang="ruby">[connection_id](https://ably.com/docs/api/realtime-sdk/connection#id)</If> string | `String` |
| <If lang="javascript,nodejs,flutter,java,objc,swift,csharp">waitForSync</If><If lang="ruby">:wait_for_sync</If> | A boolean value that by default waits for the initial presence synchronization following channel attachment to complete before returning the members present. When false, the current list of members is returned without waiting for a complete synchronization. <br />_Default: true_ | `Boolean` |

<If lang="javascript,nodejs">

#### Returns

Returns a promise. On success, the promise is fulfilled with an array of [PresenceMessage](#presence-message) objects corresponding to the current set of present members on the channel. 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.

</If>
<If lang="swift,objc">

#### Callback result

On success, `members` contains an array of [PresenceMessage](#presence-message) objects corresponding to the current set of present members on the channel.

On failure to retrieve the current presence member set, `err` contains an [ErrorInfo](#error-info) object with the failure reason.

</If>
<If lang="java">

#### Returns

On success, the returned array of [PresenceMessage](#presence-message) objects corresponds to the current set of present members on the channel.

Failure to retrieve the current presence member set will raise an [AblyException](https://ably.com/docs/api/realtime-sdk/types#ably-exception)

</If>
<If lang="csharp">

#### Returns

On success, the returned enumerable of [`#PresenceMessage`](#presence-message) objects correspond to the current set of present members on the channel.

Failure to retrieve the current presence member set will raise an [AblyException](https://ably.com/docs/api/realtime-sdk/types#ably-exception)

</If>
<If lang="ruby">

#### 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 an array of [PresenceMessage](#presence-message) objects to the current set of present members on the channel.

Failure to retrieve the current presence member set will trigger the `errback` callbacks of the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) with an [ErrorInfo](#error-info) object with the failure reason.

</If>

### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">history</If><If lang="csharp">History</If> 

<If lang="flutter">

`history(Object options, callback(ErrorInfo err, PaginatedResult<PresenceMessage> resultPage))`

</If>
<If lang="javascript,nodejs">

`history(Object params?): Promise<PaginatedResult<PresenceMessage>>`

</If>
<If lang="ruby">

`Deferrable history(Hash options) -> yields PaginatedResult<PresenceMessage>`

</If>
<If lang="java">

`PaginatedResult<PresenceMessage> history(Param[] options)`

</If>
<If lang="swift,objc">

`history(query: ARTRealtimeHistoryQuery?, callback: (ARTPaginatedResult<ARTPresenceMessage>?, ARTErrorInfo?) -> Void) throws`

</If>
<If lang="csharp">

`Task<PaginatedResult<PresenceMessage>> HistoryAsync(PaginatedRequestParams query, bool untilAttach = false [deprecated])`

</If>

Gets a [paginated](#paginated-result) set of historical presence message events for this channel. If the [channel is configured to persist messages to disk](https://faqs.ably.com/how-long-are-messages-stored-for,) then the presence message event history will [typically be available for 24 - 72 hours](https://faqs.ably.com/how-long-are-messages-stored-for.) If not, presence message events are only retained in memory by the Ably service for two minutes.

#### Parameters

<If lang="javascript,nodejs,java,csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs">params</If><If lang="java">options</If><If lang="csharp">query</If> | an optional <If lang="javascript,nodejs">object</If><If lang="java">object</If><If lang="csharp">PaginatedRequestParams object</If> containing query parameters, as specified in the [presence history API documentation](https://ably.com/docs/storage-history/history#presence-history) | <If lang="java">[`Param[]`](/docs/api/realtime-sdk/presence#param)</If><If lang="csharp">`PaginatedRequestParams`</If> |

</If>

<If lang="ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="ruby">options</If><If lang="swift,objc">query</If> | <If lang="objc,swift">an optional object containing query parameters</If><If lang="ruby">an optional set of key value pairs containing query parameters</If>, as specified in the [presence history API documentation](https://ably.com/docs/storage-history/history#presence-history) | |
| <If lang="ruby">&block</If><If lang="swift,objc">callback</If> | <If lang="ruby">yields a `PaginatedResult<Message>` object</If><If lang="swift,objc">called with a `ARTPaginatedResult<ARTPresenceMessage>` object or an error</If> | |

</If>

Further details of the supported `options` params, see [presence history API documentation](https://ably.com/docs/storage-history/history#presence-history.)

<If lang="javascript,nodejs">

#### Returns

Returns a promise. On success, the promise is fulfilled with a [PaginatedResult](#paginated-result) object containing an array of [PresenceMessage](#presence-message) objects  corresponding to 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.

</If>

<If lang="swift,objc">

#### Callback result

On success, `resultPage` contains a [PaginatedResult](#paginated-result) encapsulating an array of [PresenceMessage](#presence-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](#error-info) object with the failure reason.

</If>

<If lang="java">

#### Returns

On success, the returned [PaginatedResult](#paginated-result) encapsulates an array of [PresenceMessage](#presence-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)

</If>

<If lang="csharp">

#### Returns

Returns a task that needs to be awaited.

On success, the returned [PaginatedResult](#paginated-result) encapsulates an array of [PresenceMessage](#presence-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.) Only if the task is awaited.

</If>

<If lang="ruby">

#### 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 [PresenceMessage](#presence-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](#error-info) object with the failure reason.

</If>

### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">subscribe</If><If lang="csharp">Subscribe</If> 

There are overloaded versions of this method:

<If lang="javascript,nodejs">

`subscribe(listener(PresenceMessage)): Promise<void>`

</If>
<If lang="flutter">

`subscribe(listener(PresenceMessage))`

</If>
<If lang="java">

`void subscribe(PresenceListener listener)`

</If>
<If lang="ruby">

`subscribe → yields PresenceMessage`

</If>
<If lang="swift,objc">

`subscribe(callback: (ARTPresenceMessage) -> Void) -> ARTEventListener`

</If>
<If lang="csharp">

`void Subscribe(Action<PresenceMessage> handler)`

</If>

Subscribe to presence message events on this channel. The caller supplies <If lang="javascript,nodejs,flutter,objc,swift">a listener function</If><If lang="java">an implementation of the [PresenceListener](#presence-listener) interface</If><If lang="ruby">a block</If><If lang="csharp">a handler</If>, which is called each time one or more presence events occurs such as a member entering or leaving a channel.

<If lang="flutter">

`subscribe(String action, listener(PresenceMessage))`

</If>
<If lang="javascript,nodejs">

`subscribe(String action, listener(PresenceMessage)): Promise<void>`

</If>
<If lang="java">

`void subscribe(PresenceMessage.Action action, PresenceListener listener)`

</If>
<If lang="ruby">

`subscribe(PresenceMessage::ACTION action) → yields PresenceMessage`

</If>
<If lang="swift,objc">

`subscribe(action: ARTPresenceAction, callback: (ARTPresenceMessage) -> Void) -> ARTEventListener`

</If>
<If lang="csharp">

`void Subscribe(PresenceAction action, Action<PresenceMessage> handler)`

</If>

Subscribe to presence message events with a given [action](#presence-action) on this channel. The caller supplies <If lang="javascript,nodejs,flutter,objc,swift">a listener function</If><If lang="java">an implementation of the [PresenceListener](#presence-listener) interface</If><If lang="ruby">a block</If><If lang="csharp">a handler</If>, which is called each time one or more presence events occurs such as a member entering or leaving a channel.

<If lang="javascript,nodejs,java,ruby">

<If lang="javascript,nodejs">

`subscribe(String[] actions, listener(PresenceMessage))`

</If>
<If lang="java">

`void subscribe(PresenceMessage.Action[] actions, PresenceListener listener)`

</If>
<If lang="ruby">

`subscribe(PresenceMessage::ACTION *actions) → yields PresenceMessage`

</If>

Subscribe a single listener to messages on this channel for multiple [action](#presence-action) values.

</If>

#### Parameters

<If lang="flutter,javascript,nodejs,java,ruby">

| Parameter | Description | Type |
|-----------|-------------|------|
| action | The presence [`action` event](#presence-action) to subscribe to | <If lang="javascript,nodejs">`String`</If><If lang="java">[PresenceMessage.Action](#presence-action)</If><If lang="ruby">[PresenceMessage::ACTION](#presence-action) action</If> |
| <If lang="flutter,javascript,nodejs,java,ruby">actions</If> | An <If lang="ruby">argument</If><If lang="flutter,javascript,nodejs,java">array</If> of [`action` events](#presence-action) to subscribe to | <If lang="flutter,javascript,nodejs,java">`String[]`</If><If lang="ruby">`*argument`</If> |
| <If lang="javascript,nodejs">listener</If><If lang="java">listener</If><If lang="ruby">&block</If> | <If lang="javascript,nodejs">is a function of the form `function(presenceMessage)` to be called for each matching presence message event</If><If lang="java">Message listener to be notified for matching presence message event</If><If lang="ruby">yields matching presence message event when received on the channel</If> | <If lang="java">[`PresenceListener`](#presence-listener)</If> |

</If>

<If lang="swift,objc,csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| action | The presence [`action` event](#presence-action) to subscribe to | <If lang="swift,objc">`ARTPresenceAction`</If><If lang="csharp">[PresenceAction](#presence-action)</If> |
| <If lang="swift,objc">callback</If><If lang="csharp">handler</If> | called with each matching [presence message](#presence-message) when received on the channel | |

</If>

<If lang="javascript,nodejs">

#### Returns

Returns a promise. On successful channel attachment, the promise is resolved. 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.

</If>

#### 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 <If lang="flutter,javascript,nodejs,java,swift,objc">listener</If><If lang="ruby">block</If><If lang="csharp">handler</If> will still be registered
* If `subscribe` is called more than once with the same <If lang="flutter,javascript,nodejs,java,swift,objc">listener</If><If lang="ruby">block</If><If lang="csharp">handler</If>, then duplicates will be registered. For example, if you `subscribe` twice with the same <If lang="flutter,javascript,nodejs,java,swift,objc">listener</If><If lang="ruby">block</If><If lang="csharp">handler</If> and a presence message is later received, the same <If lang="flutter,javascript,nodejs,java,swift,objc">listener</If><If lang="ruby">block</If><If lang="csharp">handler</If> will be invoked twice
* The registered <If lang="flutter,javascript,nodejs,java,swift,objc">listener</If><If lang="ruby">block</If><If lang="csharp">handler</If> remains active on the presence channel regardless of the underlying channel state. For example, if you call `subscribe` when the underlying channel is `attached` and it later becomes `detached` or even `failed`, when the channel is reattached and a presence message is received, the <If lang="flutter,javascript,nodejs,java,swift,objc">listeners</If><If lang="ruby">blocks</If><If lang="csharp">handlers</If> originally registered will still be invoked. Listeners are only removed when calling [unsubscribe](#unsubscribe) or when the underlying channel is `released` using the <If lang="flutter,javascript,nodejs,java,swift,objc">`Realtime.channels.release(name)`</If><If lang="csharp">`Realtime.Channels.Release(name)`</If> 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

### <If lang="flutter,javascript,nodejs,ruby,java,swift,objc">unsubscribe</If><If lang="csharp">Unsubscribe</If> 

There are <If lang="javascript,nodejs">six</If><If lang="flutter,ruby,java,swift,objc,csharp">three</If> overloaded versions of this method:

<If lang="flutter">

`unsubscribe(String action, listener)`

</If>
<If lang="javascript,nodejs">

`unsubscribe(String action, listener)`

</If>
<If lang="java">

`void unsubscribe(PresenceMessage.Action action, PresenceListener listener)`

</If>
<If lang="ruby">

`unsubscribe(PresenceMessage::ACTION action, &listener_proc)`

</If>
<If lang="swift,objc">

`unsubscribe(action: ARTPresenceAction, listener: ARTEventListener)`

</If>
<If lang="csharp">

`bool Unsubscribe(PresenceAction presenceAction, Action<PresenceMessage> handler)`

</If>

Unsubscribe the given listener from presence message events on this channel for the given [action](#presence-action.) This removes an earlier event-specific subscription.

<If lang="flutter">

`unsubscribe(listener)`

</If>
<If lang="javascript,nodejs">

`unsubscribe(listener)`

</If>
<If lang="java">

`void unsubscribe(PresenceListener listener)`

</If>
<If lang="ruby">

`unsubscribe(&listener_proc)`

</If>
<If lang="swift,objc">

`unsubscribe(listener: ARTEventListener)`

</If>
<If lang="csharp">

`bool Unsubscribe(Action<PresenceMessage> handler)`

</If>

Unsubscribe the given listener from presence message events on this channel. This removes an earlier subscription.

<If lang="javascript,nodejs">

`unsubscribe(String[] actions, listener)`

Unsubscribe the given listener from all presence actions in the array.

`unsubscribe(String action)`

Unsubscribe all listeners for a given [action](#presence-action.)

`unsubscribe(String[] actions)`

Unsubscribe all listeners for all presence actions in the array.

</If>



<If lang="flutter,javascript,nodejs,ruby">

`unsubscribe()`

</If>
<If lang="java">

`void unsubscribe()`

</If>
<If lang="swift,objc">

`unsubscribe()`

</If>
<If lang="csharp">

`bool Unsubscribe()`

</If>

Unsubscribes all listeners to presence message events on this channel. This removes all earlier subscriptions.

#### Parameters

<If lang="javascript,nodejs">

| Parameter | Description | Type |
|-----------|-------------|------|
| action | The presence [`action` event](#presence-action) to unsubscribe from | `String` |
| actions | An array of actions to unsubscribe from | `String[]` |
| listener | is the callback listener function that was previously subscribed | |

</If>

<If lang="java,csharp,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| action | The presence [`action` event](#presence-action) to unsubscribe from | <If lang="java">[PresenceMessage.Action](#presence-action)</If><If lang="ruby">[PresenceMessage::ACTION](#presence-action) action</If><If lang="swift,objc">`ARTPresenceAction`</If> |
| <If lang="java">listener</If><If lang="csharp">handler</If><If lang="ruby">&listener_block</If><If lang="swift,objc">listener</If> | <If lang="java">previously registered listener</If><If lang="csharp">previously registered handler</If><If lang="ruby">previously registered listener block</If><If lang="swift,objc">previous return value from a `subscribe` call</If> | <If lang="java">[`PresenceListener`](#presence-listener)</If> |

</If>

### <If lang="javascript,nodejs,java,objc,swift">enterClient</If><If lang="ruby">enter_client</If><If lang="csharp">EnterClientAsync</If> 

Enter this presence channel for the given <If lang="flutter,javascript,nodejs,java,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If><If lang="csharp">`ClientId`</If>. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](https://ably.com/docs/presence-occupancy/presence#presence-multiple-client-id) for more info. In order to be able to publish presence changes for arbitrary client IDs, the client library must have been instantiated either with an [API key](https://ably.com/docs/auth#api-keys,) or with a [token bound to a wildcard client ID](https://faqs.ably.com/can-a-client-emulate-any-client-id-i.e.-authenticate-using-a-wildcard-client-id.)

<If lang="flutter,ruby,java,swift,objc,csharp">

There are two overloaded versions of this method. <If lang="flutter,ruby,java,swift,objc">With both versions, a <If lang="swift,objc">callback</If><If lang="ruby">block</If><If lang="java">completion listener</If> can optionally be passed in to be notified of success or failure to enter.</If>

<If lang="ruby">

`Deferrable enter_client(String client_id) -> yields`

</If>
<If lang="java">

`void enterClient(String clientId, CompletionListener listener)`

</If>
<If lang="swift,objc">

`enterClient(clientId: String, data: nil, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="csharp">

`Task EnterClientAsync(string clientId)`

</If>

Enter a presence channel on behalf of the provided <If lang="flutter,java,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If><If lang="csharp">`ClientId`</If> without any data. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel.

<If lang="flutter">

`enterClient(String clientId, Object data, callback(ErrorInfo err))`

</If>
<If lang="ruby">

`Deferrable enter_client(String client_id, Object data) -> yields`

</If>
<If lang="java">

`void enterClient(String clientId, Object data, CompletionListener listener)`

</If>
<If lang="swift,objc">

`enterClient(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="csharp">

`Task EnterClientAsync(string clientId, object clientData)`

</If>

Enter a presence channel on behalf of the provided <If lang="flutter,java,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If><If lang="csharp">`ClientId`</If> and provide data that is associated with the current present member. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel.

</If>

<If lang="javascript,nodejs">

`enterClient(String clientId, Object data?): Promise<void>`

Enter a presence channel on behalf of the provided `clientId` and provide an optional data that is associated with the current present member. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel.

</If>

#### Parameters

<If lang="javascript,nodejs,csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the member. The supported payload types are <If lang="javascript,nodejs">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="csharp">strings, plain object convertible to json, binary data as byte arrays, and null</If>. | `Object` |

</If>

<If lang="flutter,java,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the member. The supported payload types are <If lang="flutter">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="java">Strings, JsonObject, binary data as byte arrays, and null</If><If lang="ruby">Strings, Hash or Array objects that can be serialized to JSON using `to_json`, binary data as `ASCII-8BIT` byte arrays, and null</If><If lang="swift,objc">The supported payload types are <If lang="objc">`NS`</If>`String`, <If lang="objc">`NS`</If>`Dictionary` or <If lang="objc">`NS`</If>`Array` objects that can be serialized to JSON, binary data as `NSData`, and `nil`</If>. | `Object` |
| <If lang="java">listener</If><If lang="ruby">&block</If><If lang="swift,objc">callback</If> | <If lang="java">Listener to be notified on completion</If><If lang="ruby">yields upon successfully entering the channel</If><If lang="swift,objc">called upon successfully entering the channel, or with an error</If> | <If lang="java">[`CompletionListener`](#completion-listener)</If> |

</If>

<If lang="javascript,nodejs">

#### 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.

</If>

<If lang="swift,objc">

#### Callback result

On successfully entering the channel, `err` is null. On failure to enter, `err` contains an [ErrorInfo](#error-info) object describing the failure reason.

</If>

<If lang="java">

#### Listener result

On successfully entering the channel, the `onSuccess` method of the [CompletionListener](#completion-listener) is called. On failure to enter, the `onError` method is called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

<If lang="csharp">

#### Returns

The method returns a `Task` that will need to be awaited. On success the method will complete and will not throw an exception. On failure to enter the method will throw an `AblyException` with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

<If lang="ruby">

#### Returns

A [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the method.

On successfully entering the channel, 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 enter, the `errback` callbacks of the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) are called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

### <If lang="flutter,javascript,nodejs,java,objc,swift">leaveClient</If><If lang="ruby">leave_client</If><If lang="csharp">LeaveClientAsync</If> 

Leave this presence channel for the given <If lang="flutter,javascript,nodejs,java,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If><If lang="csharp">`ClientId`</If>. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](https://ably.com/docs/presence-occupancy/presence#presence-multiple-client-id) for more info. In order to leave the presence set of a channel, the client must have already [entered and been present](#enter-client.)

<If lang="flutter,ruby,java,swift,objc,csharp">

There are two overloaded versions of this method. <If lang="ruby,java,swift,objc">With both versions, a <If lang="swift,objc">callback</If><If lang="ruby">block</If><If lang="java">completion listener</If> can optionally be passed in to be notified of success or failure to leave.</If>

<If lang="ruby">

`Deferrable leave_client(String client_id) -> yields`

</If>
<If lang="java">

`void leaveClient(String clientId, CompletionListener listener)`

</If>
<If lang="swift,objc">

`leaveClient(clientId: String, data: nil, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="csharp">

`Task LeaveClientAsync(string clientId, object data)`

</If>

Leave a presence channel on behalf of the provided <If lang="java,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If><If lang="csharp">`ClientId`</If> without emitting any data.

<If lang="ruby">

`Deferrable leave_client(String client_id, Object data) -> yields`

</If>
<If lang="java">

`void leaveClient(String clientId, Object data, CompletionListener listener)`

</If>
<If lang="swift,objc">

`leave(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="csharp">

`Task LeaveClientAsync(string clientId)`

</If>

Leave a presence channel on behalf of the provided <If lang="flutter,java,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If><If lang="csharp">`ClientId`</If> and emit data that is associated with the current leaving member.

</If>

<If lang="javascript,nodejs">

`leaveClient(String clientId, Object data?): Promise<void>`

Leave a presence channel on behalf of the provided `clientId` and emit an optional data that is associated with the current leaving member.

</If>

#### Parameters

<If lang="javascript,nodejs,csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the member. The supported payload types are <If lang="javascript,nodejs">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="csharp">strings, plain object convertible to json, binary data as byte arrays, and null</If>. | `Object` |

</If>

<If lang="flutter,java,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the member. The supported payload types are <If lang="flutter">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="java">Strings, JsonObject, binary data as byte arrays, and null</If><If lang="ruby">Strings, Hash or Array objects that can be serialized to JSON using `to_json`, binary data as `ASCII-8BIT` byte arrays, and null</If><If lang="swift,objc">The supported payload types are <If lang="objc">`NS`</If>`String`, <If lang="objc">`NS`</If>`Dictionary` or <If lang="objc">`NS`</If>`Array` objects that can be serialized to JSON, binary data as `NSData`, and `nil`</If>. | `Object` |
| <If lang="java">listener</If><If lang="ruby">&block</If><If lang="swift,objc">callback</If> | <If lang="java">Listener to be notified on completion</If><If lang="ruby">yields upon successfully entering the channel</If><If lang="swift,objc">called upon successfully entering the channel, or with an error</If> | <If lang="java">[`CompletionListener`](#completion-listener)</If> |

</If>

<If lang="javascript,nodejs">

#### 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.

</If>

<If lang="swift,objc">

#### Callback result

On successfully leaving the channel, `err` is null. On failure to leave, `err` contains an [ErrorInfo](#error-info) object describing the failure reason.

</If>

<If lang="java">

#### Listener result

On successfully leaving the channel, the `onSuccess` method of the [CompletionListener](#completion-listener) is called. On failure to leave, the `onError` method is called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

<If lang="csharp">

#### Returns

The method returns a `Task` that will need to be awaited. On success the method will complete and will not throw an exception. On failure to leave the method will throw an `AblyException` with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

<If lang="ruby">

#### Returns

A [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the method.

On successfully leaving the channel, 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 leave, the `errback` callbacks of the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) are called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

### <If lang="flutter,javascript,nodejs,java,objc,swift">updateClient</If><If lang="ruby">update_client</If><If lang="csharp">UpdateClientAsync</If> 

Clients can update the member data on behalf of the given <If lang="flutter,javascript,nodejs,java,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If><If lang="csharp">`ClientId`</If> which will trigger a broadcast of this update to all presence subscribers. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](https://ably.com/docs/presence-occupancy/presence#presence-multiple-client-id) for more info. If an attempt to update is made before the member has entered the channel, the update is treated as an enter.

<If lang="flutter,javascript,nodejs,ruby,java,swift,objc">
A <If lang="flutter,javascript,nodejs,swift,objc">callback</If><If lang="ruby">block</If><If lang="java">completion listener</If> can optionally be passed in to be notified of success or failure to update the member data.
</If>

<If lang="flutter">

`updateClient(String clientId, Object data, callback(ErrorInfo err))`

</If>
<If lang="javascript,nodejs">

`updateClient(String clientId, Object data?): Promise<void>`

</If>
<If lang="ruby">

`Deferrable update_client(String client_id, Object data) -> yields`

</If>
<If lang="java">

`void updateClient(String clientId, Object data, CompletionListener listener)`

</If>
<If lang="swift,objc">

`update(clientId: String, data: AnyObject?, callback: ((ARTErrorInfo?) -> Void)?)`

</If>
<If lang="csharp">

`Task UpdateClientAsync(string clientId, object data)`

</If>

Update the member data on behalf of the provided <If lang="flutter,javascript,nodejs,java,swift,objc">`clientId`</If><If lang="ruby">`client_id`</If><If lang="csharp">`ClientId`</If> and broadcast an update event to all subscribers. `data` may be `null`. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel.

#### Parameters

<If lang="javascript,nodejs,csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the member. The supported payload types are <If lang="javascript,nodejs">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="csharp">strings, plain object convertible to json, binary data as byte arrays, and null</If>. | `Object` |

</If>

<If lang="flutter,java,ruby,swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| data | data payload for the member. The supported payload types are <If lang="flutter">Strings, JSON objects and arrays, buffers containing arbitrary binary data, and null</If><If lang="java">Strings, JsonObject, binary data as byte arrays, and null</If><If lang="ruby">Strings, Hash or Array objects that can be serialized to JSON using `to_json`, binary data as `ASCII-8BIT` byte arrays, and null</If><If lang="swift,objc">The supported payload types are <If lang="objc">`NS`</If>`String`, <If lang="objc">`NS`</If>`Dictionary` or <If lang="objc">`NS`</If>`Array` objects that can be serialized to JSON, binary data as `NSData`, and `nil`</If>. | `Object` |
| <If lang="java">listener</If><If lang="ruby">&block</If><If lang="swift,objc">callback</If> | <If lang="java">Listener to be notified on completion</If><If lang="ruby">yields upon successfully entering the channel</If><If lang="swift,objc">called upon successfully entering the channel, or with an error</If> | <If lang="java">[`CompletionListener`](#completion-listener)</If> |

</If>

<If lang="javascript,nodejs">

#### 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.

</If>

<If lang="objc,swift">

#### Callback result

On successfully updating the data, `err` is null. On failure to update, `err` contains an [ErrorInfo](#error-info) object describing the failure reason.

</If>

<If lang="java">

#### Listener result

On successfully updating the data, the `onSuccess` method of the [CompletionListener](#completion-listener) is called. On failure to update, the `onError` method is called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

<If lang="csharp">

#### Returns

The method returns a Task that will need to be awaited. On success the method will complete and will not throw an exception. On failure to update the method will throw an `AblyException` with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

<If lang="ruby">

#### Returns

A [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) object is returned from the method.

On successfully updating the data, 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 update, the `errback` callbacks of the [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) are called with an [ErrorInfo](#error-info) argument describing the failure reason.

</If>

## Related types 

## <If lang="flutter,javascript,nodejs">PresenceMessage</If><If lang="swift,objc">ARTPresenceMessage</If><If lang="ruby">Ably::Models::PresenceMessage</If><If lang="java">io.ably.lib.types.PresenceMessage</If><If lang="csharp">IO.Ably.PresenceMessage</If> 

A `PresenceMessage` represents an individual presence update that is sent to or received from Ably.

#### <If lang="flutter,javascript,nodejs,swift,objc,csharp">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>

| Property | Description | Type |
|----------|-------------|------|
| <If lang="flutter,javascript,nodejs,ruby,swift,objc">action</If><If lang="java">action</If><If lang="csharp">Action</If> | the event signified by a PresenceMessage. See <If lang="flutter,javascript,nodejs">[`Presence action`](https://ably.com/docs/api/realtime-sdk/types#presence-action)</If><If lang="java">[`PresenceMessage.action`](https://ably.com/docs/api/realtime-sdk/types#presence-action)</If><If lang="csharp">[`PresenceMessage.action`](https://ably.com/docs/api/realtime-sdk/types#presence-action)</If><If lang="ruby">[`PresenceMessage::ACTION`](https://ably.com/docs/api/realtime-sdk/types#presence-action)</If><If lang="swift,objc">[`PresenceMessage.action`](https://ably.com/docs/api/realtime-sdk/types#presence-action)</If> | <If lang="java">`enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }`</If><If lang="csharp">`enum { Absent, Present, Enter, Leave, Update }`</If><If lang="javascript,nodejs">`int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }`</If><If lang="ruby">`enum { :absent, :present, :enter, :leave, :update }`</If><If lang="swift,objc">`ARTPresenceAction`</If> |
| <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">data</If><If lang="csharp">Data</If> | The presence update payload, if provided | <If lang="java">`String`, `ByteArray`, `JSONObject`, `JSONArray`</If><If lang="csharp">`String`, `byte[]`, plain C# object that can be converted to Json</If><If lang="javascript,nodejs">`String`, `StringBuffer`, `JSON Object`</If><If lang="ruby">`String`, `Binary` (ASCII-8BIT String), `Hash`, `Array`</If><If lang="swift">`String`, `NSData`, `Dictionary`, `Array`</If><If lang="objc">`NSString *`, `NSData *`, `NSDictionary *`, `NSArray *`</If> |
| <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">extras</If><If lang="csharp">Extras</If> | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](https://ably.com/docs/push/publish#sub-channels), [`ref`](https://ably.com/docs/channels/messages#interactions) and [`privileged`](https://ably.com/docs/platform/integrations/webhooks#skipping) objects. | <If lang="java">`JSONObject`, `JSONArray`</If><If lang="csharp">plain C# object that can be converted to Json</If><If lang="javascript,nodejs">`JSON Object`</If><If lang="ruby">`Hash`, `Array`</If><If lang="swift">`Dictionary`, `Array`</If><If lang="objc">`NSDictionary *`, `NSArray *`</If><If lang="flutter">`Map`, `List`</If> |
| <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">id</If><If lang="csharp">Id</If> | Unique ID assigned by Ably to this presence update | `String` |
| <If lang="flutter,javascript,nodejs,java,swift,objc">clientId</If><If lang="ruby">client_id</If><If lang="csharp">ClientId</If> | The client ID of the publisher of this presence update | `String` |
| <If lang="flutter,javascript,nodejs,java,swift,objc">connectionId</If><If lang="ruby">connection_id</If><If lang="csharp">ConnectionId</If> | The connection ID of the publisher of this presence update | `String` |
| <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">timestamp</If><If lang="csharp">Timestamp</If> | Timestamp when the presence update was received by Ably<If lang="flutter,javascript,nodejs,java">, as milliseconds since the epoch</If>. | <If lang="flutter,javascript,nodejs">`Integer`</If><If lang="java">`Long Integer`</If><If lang="csharp">`DateTimeOffset`</If><If lang="ruby">`Time`</If><If lang="objc,swift">`NSDate`</If> |
| <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">encoding</If><If lang="csharp">Encoding</If> | This will typically be empty as all presence updates 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 | `String` |

### PresenceMessage constructors

#### PresenceMessage.fromEncoded 

`PresenceMessage.fromEncoded(Object encodedPresMsg, ChannelOptions channelOptions?) -> PresenceMessage`

A static factory method to create a [`PresenceMessage`](https://ably.com/docs/api/realtime-sdk/types#presence-message) from a deserialized `PresenceMessage`-like object encoded using Ably's wire protocol.

#### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| encodedPresMsg | a `PresenceMessage`-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 [`PresenceMessage`](https://ably.com/docs/api/realtime-sdk/types#presence-message) object

#### PresenceMessage.fromEncodedArray 

`PresenceMessage.fromEncodedArray(Object[] encodedPresMsgs, ChannelOptions channelOptions?) -> PresenceMessage[]`

A static factory method to create an array of [`PresenceMessages`](https://ably.com/docs/api/realtime-sdk/types#presence-message) from an array of deserialized `PresenceMessage`-like object encoded using Ably's wire protocol.

#### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| encodedPresMsgs | an array of `PresenceMessage`-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 [`PresenceMessage`](https://ably.com/docs/api/realtime-sdk/types#presence-message) objects

## <If lang="flutter,javascript,nodejs">Presence action</If><If lang="swift,objc">ARTPresenceAction</If><If lang="java">io.ably.lib.types.PresenceMessage.Action</If><If lang="ruby">Ably::Models::PresenceMessage::ACTION</If><If lang="csharp">IO.Ably.PresenceAction</If> 

<If lang="javascript,nodejs">

`Presence` `action` is a String with a value matching any of the [`Realtime Presence` states & events](https://ably.com/docs/presence-occupancy/presence#trigger-events.)

<Code>
```javascript
var PresenceActions = [
  'absent', // (reserved for internal use)
  'present',
  'enter',
  'leave',
  'update'
]
```
</Code>

</If>

<If lang="java">

`io.ably.lib.types.PresenceMessage.Action` is an enum representing all the [`Realtime Presence` states & events](https://ably.com/docs/presence-occupancy/presence#trigger-events.)

<Code>
```java
public enum Action {
  ABSENT,  // 0 (reserved for internal use)
  PRESENT, // 1
  ENTER,   // 2
  LEAVE,   // 3
  UPDATE   // 4
}
```
</Code>

</If>

<If lang="csharp">

`IO.Ably.PresenceAction` is an enum representing all the [`Realtime Presence` states & events](https://ably.com/docs/presence-occupancy/presence#trigger-events.)

<Code>
```csharp
public enum Action {
  Absent,  // 0 (reserved for internal use)
  Present, // 1
  Enter,   // 2
  Leave,   // 3
  Update   // 4
}
```
</Code>

</If>

<If lang="ruby">

`Ably::Models::PresenceMessage::ACTION` is an enum-like value representing all the [`Realtime Presence` states & events](https://ably.com/docs/presence-occupancy/presence#trigger-events.) `ACTION` can be represented interchangeably as either symbols or constants.

#### Symbol states

<Code>
```ruby
:absent  # => 0 (reserved for internal use)
:present # => 1
:enter   # => 2
:leave   # => 3
:update  # => 4
```
</Code>

#### Constant states

<Code>
```ruby
PresenceMessage::ACTION.Absent  # => 0 (internal use)
PresenceMessage::ACTION.Present # => 1
PresenceMessage::ACTION.Enter   # => 2
PresenceMessage::ACTION.Leave   # => 3
PresenceMessage::ACTION.Update  # => 4
```
</Code>

#### Example usage

<Code>
```ruby
# Example with symbols
presence.on(:attached) { ... }

# Example with constants
presence.on(Ably::Models::PresenceMessage::ACTION.Enter) { ... }

# Interchangeable
Ably::Models::PresenceMessage::ACTION.Enter == :enter # => true
```
</Code>

</If>

<If lang="swift,objc">

`ARTPresenceAction` is an enum representing all the [`Realtime Presence` states & events](https://ably.com/docs/presence-occupancy/presence#trigger-events.)

<If lang="objc">
<Code>
```objc
typedef NS_ENUM(NSUInteger, ARTPresenceAction) {
    ARTPresenceAbsent, // reserved for internal use
    ARTPresencePresent,
    ARTPresenceEnter,
    ARTPresenceLeave,
    ARTPresenceUpdate
};
```
</Code>
</If>

<If lang="swift">
<Code>
```swift
enum ARTPresenceAction : UInt {
  case Absent // reserved for internal use
  case Present
  case Enter
  case Leave
  case Update
}
```
</Code>
</If>

</If>

<If lang="csharp">

## 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 | _null_ The start of the queried interval | `DateTimeOffset` |
| End | _null_ The end of the queried interval | `DateTimeOffset` |
| Limit | _null_ By default it is null. Limits the number of items returned by history or stats | `Integer` |
| Direction | _Backwards_ Enum which is either `Forwards` or `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<string, string>` |

</If>

<If lang="java">

## 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.

<Code>
```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);
}
```
</Code>

</If>

## <If lang="flutter,javascript,nodejs">PaginatedResult</If><If lang="swift,objc">ARTPaginatedResult</If><If lang="ruby">Ably::Models::PaginatedResult</If><If lang="java">io.ably.lib.types.PaginatedResult</If><If lang="csharp">IO.Ably.PaginatedResult</If> 

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.

#### <If lang="flutter,javascript,nodejs,swift,objc,csharp">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>

| Property | Description | Type |
|----------|-------------|------|
| <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">items</If><If lang="csharp">Items</If> | contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">`Array <Message, Presence, Stats>`</If><If lang="csharp">`List <Message, Presence, Stats>`</If> |

### Methods

#### <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">first</If><If lang="csharp">First</If>

<If lang="flutter">

`first(callback(ErrorInfo err, PaginatedResult resultPage))`

</If>
<If lang="javascript,nodejs">

`first(): Promise<PaginatedResult>`

</If>
<If lang="ruby">

`PaginatedResult first`

</If>
<If lang="java">

`PaginatedResult first()`

</If>
<If lang="swift,objc">

`first(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)`

</If>
<If lang="csharp">

`Task<PaginatedResult<T>> FirstAsync()`

</If>

<If lang="flutter,ruby,java,swift,objc,csharp">

Returns a new `PaginatedResult` for the first page of results. <If lang="ruby">When using the Realtime library, the `first` method returns a [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) and yields a [PaginatedResult](#paginated-result).</If><If lang="csharp">The method is asynchronous and returns a Task which needs to be awaited to get the [PaginatedResult](#paginated-result).</If>

</If>

<If lang="javascript,nodejs">

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.

</If>

#### <If lang="flutter,javascript,nodejs,java,swift,objc">hasNext</If><If lang="csharp">HasNext</If><If lang="ruby">has_next?</If>

<If lang="flutter,javascript,nodejs,java,swift,objc">

`Boolean hasNext()`

</If>
<If lang="ruby">

`Boolean has_next?`

</If>
<If lang="csharp">

`Boolean HasNext()`

</If>

Returns `true` if there are more pages available by calling <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">`next`</If><If lang="csharp">`Next`</If> and returns `false` if this page is the last page available.

#### <If lang="flutter,javascript,nodejs,java,swift,objc">isLast</If><If lang="csharp">IsLast</If><If lang="ruby">last?</If>

<If lang="flutter,javascript,nodejs,java,swift,objc">

`Boolean isLast()`

</If>
<If lang="ruby">

`Boolean last?`

</If>
<If lang="csharp">

`Boolean IsLast()`

</If>

Returns `true` if this page is the last page and returns `false` if there are more pages available by calling <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">`next`</If><If lang="csharp">`Next`</If> available.

#### <If lang="flutter,javascript,nodejs,java,ruby,swift,objc">next</If><If lang="csharp">Next</If>

<If lang="flutter">

`next(callback(ErrorInfo err, PaginatedResult resultPage))`

</If>
<If lang="javascript,nodejs">

`next(): Promise<PaginatedResult | null>`

</If>
<If lang="ruby">

`PaginatedResult next`

</If>
<If lang="java">

`PaginatedResult next()`

</If>
<If lang="swift,objc">

`next(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)`

</If>
<If lang="csharp">

`Task<PaginatedResult<T>> NextAsync()`

</If>

<If lang="flutter,ruby,java,swift,objc,csharp">

Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then <If lang="flutter">`null`</If><If lang="csharp">a blank PaginatedResult will be returned</If><If lang="java">`Null`</If><If lang="swift,objc">`nil`</If> is returned. <If lang="csharp">The method is asynchronous and return a Task which needs to be awaited to get the `PaginatedResult`</If><If lang="ruby">When using the Realtime library, the `first` method returns a [Deferrable](https://ably.com/docs/api/realtime-sdk/types#deferrable) and yields a [PaginatedResult](#paginated-result).</If>

</If>

<If lang="javascript,nodejs">

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.

</If>

<If lang="javascript,nodejs">

#### current 

`current(): Promise<PaginatedResult>`

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.

</If>

#### Example 

<If lang="javascript">
<Code>
```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());
```
</Code>
</If>

<If lang="nodejs">
<Code>
```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());
```
</Code>
</If>

<If lang="java">
<Code>
```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()));
};
```
</Code>
</If>

<If lang="csharp">
<Code>
```csharp
PaginatedResult<Message> 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());
}
```
</Code>
</If>

<If lang="ruby">
<Code>
```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
```
</Code>
</If>

<If lang="objc">
<Code>
```objc
[channel history:^(ARTPaginatedResult<ARTMessage *> *paginatedResult, ARTErrorInfo *error) {
    NSLog(@"Page 0 item 0: %@", paginatedResult.items[0].data);
    [paginatedResult next:^(ARTPaginatedResult<ARTMessage *> *nextPage, ARTErrorInfo *error) {
        NSLog(@"Page 1 item 1: %@", nextPage.items[1].data);
        NSLog(@"Last page?: %d", nextPage.isLast());
    }];
}];
```
</Code>
</If>

<If lang="swift">
<Code>
```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())")
    }
}
```
</Code>
</If>

<If lang="java">
### 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

| Member | Description | Type |
|--------|-------------|------|
| key | The key value | `String` |
| value | The value associated with the `key` | `String` |

### io.ably.lib.realtime.PresenceListener 

A `io.ably.lib.realtime.Presence.PresenceListener` is an interface allowing a client to be notified when presence message events are received on a presence channel using a [presence subscription](https://ably.com/docs/presence-occupancy/presence.)

<Code>
```java
public interface PresenceListener {
  // Called when one or more presence messages are received
  public void onPresenceMessage(PresenceMessage message);
}
```
</Code>
</If>