# Presence

## Methods

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

Get the current presence member set for this channel.  In the REST client library this method directly queries [Ably's REST presence API](https://ably.com/docs/api/rest-api.md#presence)

<If lang="javascript,nodejs">

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

</If>

<If lang="ruby">

`PaginatedResult<PresenceMessage> get(Hash options)`

</If>

<If lang="python">

`PaginatedResult<PresenceMessage> get(kwargs_options)`

</If>

<If lang="php">

`PaginatedResult<PresenceMessage> get(Array options)`

</If>

<If lang="java">

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

</If>

<If lang="csharp">

`Task<PaginatedResult<PresenceMessage>> GetAsync(int? limit = null, string clientId = null, string connectionId = null);`

</If>

<If lang="swift,objc">

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

</If>

<If lang="go">

`(p *RestPresence) Get(options *PaginateParams) (*PaginatedResult, error)`

</If>

<If lang="flutter">

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

</If>

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

<If lang ="javascript,nodejs,java,php,python,ruby,go,flutter,objc,swift">

#### Parameters

<If lang="objc,swift">

| Name | Description |
|------|-------------|
| query | an optional object containing query parameters as specified below. |
| callback | called with a [`PaginatedResult`](#paginated-result)\<[`PresenceMessage`](#presence-message)>, or with an error |

</If>

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

| Name | Description |
|------|-------------|
| <If lang="javascript,nodejs">params</If><If lang="csharp">query</If><If lang="java">[`Param[]`](#param) options</If><If lang="php,python,ruby,go,flutter">options</If> | <If lang="javascript,nodejs,java,csharp,go,flutter">an optional object containing query parameters</If><If lang="python">optional keyword arguments containing the query parameters</If><If lang="ruby">an optional set of symbol key and value pairs containing the query parameters</If><If lang="php">an optional Associate Array containing the query parameters</If> as specified below. |

</If>

</If>

#### <If lang="java,php,python,ruby,go,flutter">`options` parameters</If><If lang="javascript,nodejs">`params` parameters</If><If lang="objc,swift">`ARTPresenceQuery` properties</If><If lang="csharp">Arguments</If>

| Name | Description |
|------|-------------|
| <If lang="javascript,nodejs,java,objc,swift,php,go,flutter,csharp">clientId</If><If lang="python">client_id</If><If lang="ruby">:client_id</If>| when provided, will filter array of members returned that match the provided <If lang="javascript,nodejs,java,objc,swift,php,go,flutter">[`clientId`](https://ably.com/docs/api/rest-sdk.md#client-options)</If><If lang="ruby,python">[`client_id`](https://ably.com/docs/api/rest-sdk.md#client-options)</If><If lang="csharp">[`ClientId`](https://ably.com/docs/api/rest-sdk.md#client-options)</If> string |
| <If lang="javascript,nodejs,java,objc,swift,php,go,flutter,csharp">connectionId</If><If lang="python">connection_id</If><If lang="ruby">:connection_id</If> | when provided, will filter array of members returned that match the provided <If lang="javascript,nodejs,java,objc,swift,php,go,flutter">[`connectionId`](https://ably.com/docs/api/realtime-sdk/connection.md#id)</If><If lang="csharp">[`ConnectionId`](https://ably.com/docs/api/realtime-sdk/connection.md#id)</If><If lang="ruby,python">[`connection_id`](https://ably.com/docs/api/realtime-sdk/connection.md#id)</If> string |

<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/rest-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="java,ruby,php,python,csharp">

#### Returns

<If lang="csharp">This method is asynchronous and needs to be awaited.</If>

On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`PresenceMessage`](#presence-message) objects corresponding to the current page of members currently present on the channel. [`PaginatedResult`](#paginated-result) supports pagination using <If lang="java,ruby,php,python">[`next`](#paginated-result)</If><If lang="csharp">[`NextAsync`](#paginated-result)</If> and <If lang="java,ruby,php,python">[`first`](#paginated-result)</If><If lang="csharp">[`FirstAsync`](#paginated-result)</If> methods.

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

</If>

<If lang="java,ruby,php,python,csharp">

#### Returns

<If lang="go">This method is asynchronous and needs to be awaited.</If>

On success, `resultPage` contains a [`PaginatedResult`](#paginated-result) encapsulating an array of [`PresenceMessage`](#presence-message) objects corresponding to the current page of members currently present on the channel. [`PaginatedResult`](#paginated-result) supports pagination using [`next()`](#paginated-result) and [`first()`](#paginated-result) methods.

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

</If>

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

<If lang="javascript,nodejs">

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

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

`PaginatedResult<PresenceMessage> history(Hash options)`

</If>
<If lang="python">

`PaginatedResult<PresenceMessage> history(kwargs_options)`

</If>
<If lang="php">

`PaginatedResult<PresenceMessage> history(Array options)`

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

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

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

`Task<PaginatedResult<PresenceMessage>> HistoryAsync(PaginatedRequestParams query);`

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

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

</If>
<If lang="go">

`(p *RestPresence) History(params *PaginateParams) (*PaginatedResult, error)`

</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="objc,swift">

| Parameter | Description | Type |
|-----------|-------------|------|
| query | an optional object containing query parameters, as specified in the [presence history API documentation](https://ably.com/docs/storage-history/history.md#presence-history). | `ARTDataQuery` |
| callback | called with a [`ARTPaginatedResult`](#paginated-result)\<[`ARTPresenceMessage`](#presence-message)> object or an error | Callback |

</If>

<If lang="javascript,nodejs,java,csharp,php,python,ruby,go,flutter">

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs">params</If><If lang="csharp">query</If><If lang="java">[`Param[]`](#param) options</If><If lang="php,python,ruby,go,flutter">options</If> | <If lang="javascript,nodejs,java,csharp,go,flutter">an optional object containing query parameters</If><If lang="python">optional keyword arguments containing the query parameters</If><If lang="ruby">an optional set of key value pairs containing query parameters</If><If lang="php">an optional Associate Array containing the query parameters</If>, as specified in the [presence history API documentation](https://ably.com/docs/storage-history/history.md#presence-history). | <If lang="javascript,nodejs">Object</If><If lang="csharp">[`PaginatedRequestParams`](#paginated-request-params)</If><If lang="java">[`Param[]`](#param)</If><If lang="php,python,ruby,go,flutter">Object</If> |

</If>

<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/rest-sdk/types.md#error-info) object that details the reason why it was rejected.

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

#### 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,ruby,php,python,csharp">

#### Returns

<If lang="csharp">

This method is asynchronous and needs to be awaited.

</If>

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 <If lang="java,ruby,php,python">[`next`](#paginated-result)</If><If lang="csharp">[`NextAsync`](#paginated-result)</If> and <If lang="java,ruby,php,python">[`first`](#paginated-result)</If><If lang="csharp">[`FirstAsync`](#paginated-result)</If> methods.

Failure to retrieve the message history will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types.md#ably-exception)

</If>
<If lang="go">

#### Returns

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.

Upon failure to retrieve the message history, the `error` contains an [`ErrorInfo`](#error-info) object with the failure reason.

</If>

## Related types 

### <If lang="javascript,nodejs,php,python,go,flutter">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="javascript,nodejs,php,python,go,flutter,swift,objc,csharp">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>

| Property | Description | Type |
|----------|-------------|------|
| <If lang="java,javascript,nodejs,python,ruby,php,objc,swift,flutter">action</If><If lang="csharp">Action</If><If lang="go">Action</If> | <If lang="java">the event signified by a PresenceMessage. See [`PresenceMessage.action`](https://ably.com/docs/api/realtime-sdk/types.md#presence-action)</If><If lang="csharp">the event signified by a PresenceMessage. See [`PresenceMessage.action`](https://ably.com/docs/api/realtime-sdk/types.md#presence-action)</If><If lang="javascript,nodejs">the event signified by a PresenceMessage. See [`Presence action`](https://ably.com/docs/api/realtime-sdk/types.md#presence-action)</If><If lang="python">the event signified by a PresenceMessage. See [`PresenceAction`](https://ably.com/docs/api/realtime-sdk/types.md#presence-action)</If><If lang="ruby">the event signified by a PresenceMessage. See [`PresenceMessage::ACTION`](https://ably.com/docs/api/realtime-sdk/types.md#presence-action)</If><If lang="php">the event signified by a PresenceMessage. See [`PresenceMessage::ACTION`](https://ably.com/docs/api/realtime-sdk/types.md#presence-action)</If><If lang="objc,swift">the event signified by a PresenceMessage. See [`PresenceMessage.action`](https://ably.com/docs/api/realtime-sdk/types.md#presence-action)</If><If lang="go">the event signified by a PresenceMessage. See [`PresenceMessage::action`](https://ably.com/docs/api/realtime-sdk/types.md#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="python">`int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }`</If><If lang="ruby">`enum { :absent, :present, :enter, :leave, :update }`</If><If lang="php">`const PresenceMessage::ABSENT,PRESENT,ENTER,LEAVE,UPDATE`</If><If lang="objc,swift">`ARTPresenceAction`</If><If lang="go">`const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate`</If> |
| <If lang="javascript,nodejs,java,objc,swift,php,python,ruby,flutter">data</If><If lang="csharp,go">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="go">`String`, `[]byte`</If><If lang="ruby">`String`, `Binary` (ASCII-8BIT String), `Hash`, `Array`</If><If lang="python">`String`, `Bytearray`, `Dict`, `List`</If><If lang="swift">`String`, `NSData`, `Dictionary`, `Array`</If><If lang="objc">`NSString *`, `NSData *`, `NSDictionary *`, `NSArray *`</If><If lang="php">`String`, `Binary String`, `Associative Array`, `Array`</If> |
| <If lang="javascript,nodejs,java,objc,swift,php,python,ruby,flutter">extras</If><If lang="csharp,go">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.md#sub-channels), [`ref`](https://ably.com/docs/channels/messages.md#interactions) and [`privileged`](https://ably.com/docs/platform/integrations/webhooks.md#skipping) objects. | <If lang="java">`JSONObject`, `JSONArray`</If><If lang="csharp">plain C# object that can be converted to Json</If><If lang="go">`String`, `[]byte`</If><If lang="javascript,nodejs">`JSON Object`</If><If lang="ruby">`Hash`, `Array`</If><If lang="python">`Dict`, `List`</If><If lang="swift">`Dictionary`, `Array`</If><If lang="objc">`NSDictionary *`, `NSArray *`</If><If lang="php">`Associative Array`, `Array`</If><If lang="flutter">`Map`, `List`</If> |
| <If lang="javascript,nodejs,java,objc,swift,php,python,ruby,flutter">id</If><If lang="csharp,go">Id</If> | Unique ID assigned by Ably to this presence update | `String` |
| <If lang="javascript,nodejs,java,objc,swift,php,flutter">clientId</If><If lang="ruby,python">client_id</If><If lang="csharp,go">ClientId</If> | The client ID of the publisher of this presence update | `String` |
| <If lang="javascript,nodejs,java,objc,swift,php,flutter">connectionId</If><If lang="ruby,python">connection_id</If><If lang="csharp,go">ConnectionId</If> | The connection ID of the publisher of this presence update | `String` |
| <If lang="javascript,nodejs,java,objc,swift,php,python,ruby,flutter">timestamp</If><If lang="csharp,go">Timestamp</If> | Timestamp when the presence update was received by Ably<If lang="javascript,nodejs,java,php,python,flutter">, as milliseconds since the epoch</If>. | <If lang="javascript,nodejs,php,python,flutter">`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="javascript,nodejs,java,objc,swift,php,python,ruby,flutter">encoding</If><If lang="csharp,go">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.md#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.md#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.md#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.md#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.md#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.md#presence-message) objects

### <If lang="javascript,nodejs,php,go,flutter">Presence action</If><If lang="python">PresenceAction</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.md#trigger-events).

<If lang="javascript">

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

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

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

</If>

</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.md#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.md#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="python">

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

<Code>
```python
  class PresenceAction(object):
    ABSENT = 0    # (reserved for internal use)
    PRESENT = 1
    ENTER = 2
    LEAVE = 3
    UPDATE = 4
```
</Code>

</If>
<If lang="php">

`PresenceMessage Action` is one of the class constants representing all the [`Realtime Presence` states & events](https://ably.com/docs/presence-occupancy/presence.md#trigger-events).

<Code>
```php
  namespace Ably\Models;
  class PresenceMessages {
    const ABSENT  = 0; /* (reserved for internal use) */
    const PRESENT = 1;
    const ENTER   = 2;
    const LEAVE   = 3;
    const UPDATE  = 4;
  }
```
</Code>

#### Example usage

<Code>
```php
  if ($presenceMessage->action == Ably\Models\PresenceMesage::ENTER) {
    /* do something */
  }
```
</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.md#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="objc,swift">

`ARTPresenceAction` is an enum representing all the [`Realtime Presence` states & events](https://ably.com/docs/presence-occupancy/presence.md#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="go">

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

<Code>
```go
const (
  PresenceAbsent = 0
  PresencePresent = 1
  PresenceEnter = 2
  PresenceLeave = 3
  PresenceUpdate = 4
)
```
</Code>

</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.md#channel-history).

#### Members

| Member | Description | Type |
|--------|-------------|------|
| Start | The start of the queried interval | `DateTimeOffset` |
| End | The end of the queried interval | `DateTimeOffset` |
| Limit | 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="javascript,nodejs,php,python,go,flutter">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.md#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object.

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

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

#### Methods

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

<If lang="javascript,nodejs">

`first(): Promise<PaginatedResult>`

</If>

<If lang="ruby">

`PaginatedResult first`

</If>

<If lang="php">

`PaginatedResult first()`

</If>

<If lang="python">

`PaginatedResult first()`

</If>

<If lang="java">

`PaginatedResult first()`

</If>

<If lang="csharp">

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

</If>

<If lang="swift,objc">

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

</If>

<If lang="go">

`First() (PaginatedResult, error)`

</If>


<If lang="java,php,python,go,flutter,swift,objc">

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.md#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.md#error-info) object that details the reason why it was rejected.

</If>

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

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

`Boolean hasNext()`

</If>

<If lang="ruby">

`Boolean has_next?`

</If>

<If lang="python">

`Boolean has_next()`

</If>

<If lang="csharp">

`Boolean HasNext()`

</If>

<If lang="go">

`HasNext() (bool)`

</If>

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

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

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

`Boolean isLast()`

</If>

<If lang="ruby">

`Boolean last?`

</If>

<If lang="python">

`Boolean is_last()`

</If>

<If lang="csharp">

`Boolean IsLast()`

</If>

<If lang="go">

`IsLast() (bool)`

</If>

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

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

<If lang="javascript,nodejs">

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

</If>

<If lang="ruby">

`PaginatedResult next`

</If>

<If lang="php">

`PaginatedResult next()`

</If>

<If lang="python">

`PaginatedResult next()`

</If>

<If lang="java">

`PaginatedResult next()`

</If>

<If lang="csharp">

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

</If>

<If lang="swift,objc">

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

</If>

<If lang="go">

`Next() (PaginatedResult, error)`

</If>

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

Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then <If lang="php,flutter">`null`</If><If lang="csharp">a blank PaginatedResult will be returned</If><If lang="java">`Null`</If><If lang="python">`None`</If><If lang="objc,swift">`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.md#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.md#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.md#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="python">

<Code>
```python
result_page = channel.history()
print 'Page 0 item 0: ' + str(result_page.items[0].data)
if result_page.has_next():
  next_page = result_page.next()
  print 'Page 1 item 1: ' + str(next_page.items[1].data)
  print 'Last page?: ' + str(next_page.is_last())
```
</Code>

</If>
<If lang="php">

<Code>
```php
$firstPage = $channel.history();
echo("Page 0 item 0: " . $firstPage->items[0]->data);
if ($firstPage->hasNext()) {
  $nextPage = $firstPage->next();
  echo("Page 1 item 1: " . $nextPage->items[1]->data);
  echo("Last page?: " . $nextPage->isLast());
}
```
</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="go">

<Code>
```go
page0, err := channel.History(nil)
fmt.Println("Page. 0 item 0: %s\n", page0.Messages[0].Data)
page1, err := page0.Next()
fmt.Println("Page. 1 item 1: %s\n", page1.Messages[1].Data)
fmt.Println("Last page? %s\n", page1.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.md#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

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

</If>