# History

## Channel object

The [Rest `Channel` object](https://ably.com/docs/channels.md) exposes the following public method to obtain [`Message`](#message) history.

### Methods 

### <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<Message>>`

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

`PaginatedResult<Message> history(Hash option)`

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

`PaginatedResult<Message> history(kwargs_options)`

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

`PaginatedResult<Message> history(Array option)`

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

`PaginatedResult<Message> history(Param[] option)`

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

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

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

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

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

`(c *RestChannel) History(option *PaginateParams) (*PaginatedResult, error)`

</If>

Gets a [paginated](#paginated-result) set of historical messages for this channel.

#### Parameters

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

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs">params</If><If lang="csharp">query</If><If lang="java">option</If><If lang="php,python,ruby,go">option</If> | <If lang="javascript,nodejs">an optional object containing the 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 the query parameters</If><If lang="php">an Associate Array containing the query parameters</If><If lang="java,csharp,go">an optional object containing the query parameters</If>, as specified below. | <If lang="javascript,nodejs">Object</If><If lang="java">[`Param[]`](#param)</If><If lang="csharp">[`PaginatedRequestParams`](#paginated-request-params)</If><If lang="php,python,ruby,go">Object</If> |

</If>

<If lang="swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| query | an optional object containing the query parameters, as specified below. | ARTDataQuery |
| callback | called with a [`ARTPaginatedResult`](#paginated-result)[`<ARTMessage>`](#message) object or an error | Callback |

</If>

#### <If lang="javascript,nodejs">`params` parameters</If><If lang="objc,swift">`ARTDataQuery` properties</If><If lang="csharp">[`PaginatedRequestParams`](#paginated-request-params) properties</If><If lang="java,php,python,ruby,go">`options` parameters</If>

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs,java,objc,swift,php,go">start</If><If lang="ruby">:start</If><If lang="csharp">Start</If><If lang="python">start</If> | _beginning of time_ earliest <If lang="csharp">`DateTimeOffset` or </If><If lang="ruby">`Time` or </If>time in milliseconds since the epoch for any messages retrieved | <If lang="javascript,nodejs">`Number`</If><If lang="ruby">`Int` or `Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="java,php,python,go">`Long`</If><If lang="objc,swift">Long</If> |
| <If lang="javascript,nodejs,java,objc,swift,php,go">end</If><If lang="ruby">:end</If><If lang="csharp">End</If><If lang="python">end</If> | _current time_ latest <If lang="csharp">`DateTimeOffset` or </If><If lang="ruby">`Time` or </If>time in milliseconds since the epoch for any messages retrieved | <If lang="javascript,nodejs">`Number`</If><If lang="ruby">`Int` or `Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="java,php,python,go">`Long`</If><If lang="objc,swift">Long</If> |
| <If lang="javascript,nodejs,java,objc,swift,php,go">direction</If><If lang="ruby">:direction</If><If lang="csharp">Direction</If><If lang="python">direction</If> | _backwards_ <If lang="ruby">`:forwards` or `:backwards`</If><If lang="javascript,nodejs,java,objc,swift,php,python,go">`forwards` or `backwards`</If><If lang="csharp">forwards or backwards</If> | <If lang="javascript,nodejs,java,objc,swift,php,python,go">`String`</If><If lang="ruby">`Symbol`</If><If lang="csharp">`Direction` enum</If> |
| <If lang="javascript,nodejs,java,objc,swift,php,go">limit</If><If lang="ruby">:limit</If><If lang="csharp">Limit</If><If lang="python">limit</If> | _100_ maximum number of messages to retrieve per page, up to 1,000 | <If lang="javascript,nodejs">`Number`</If><If lang="java,php,python,ruby,csharp,objc,swift,go">`Integer`</If> |

<If lang="javascript,nodejs">

#### Returns

Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](#paginated-result) encapsulating an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next()`](#paginated-result) and [`first()`](#paginated-result) methods. On failure, 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="objc,swift">

#### Callback result

On success, `resultPage` contains a [`PaginatedResult`](#paginated-result) encapsulating an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next()`](#paginated-result) and [`first()`](#paginated-result) methods.

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

</If>

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

#### Returns

On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods.

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

</If>

<If lang="go">

#### Returns

On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods.

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

</If>

<If lang="csharp">

#### Returns

This method returns a `Task` and needs to be awaited.

On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`NextAsync`](#paginated-result) and [`FirstAsync`](#paginated-result) methods.

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

</If>

## Presence object

[Rest `Presence` object](https://ably.com/docs/presence-occupancy/presence.md) exposes the following public method to obtain presence event history such as enter, update and leave events. These events are represented as [`PresenceMessage`](#presence-message) objects.

### Methods 

### <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 option)`

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

`PaginatedResult<PresenceMessage> history(kwargs_options)`

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

`PaginatedResult<PresenceMessage> history(Array option)`

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

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

</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(option *PaginateParams) (*PaginatedResult, error)`

</If>

Gets a [paginated](#paginated-result) set of historical presence events for this channel.

#### Parameters

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

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs">params</If><If lang="java">option</If><If lang="csharp">[`PaginatedRequestParams`](#paginated-request-params) query</If><If lang="php,python,ruby,go">option</If> | <If lang="javascript,nodejs,java,csharp,go">an optional object containing the 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 the query parameters</If><If lang="php">an Associate Array containing the query parameters</If>, as specified below. | <If lang="javascript,nodejs">Object</If><If lang="java">[`Param[]`](#param)</If><If lang="csharp">[`PaginatedRequestParams`](#paginated-request-params)</If><If lang="php,python,ruby,go">Object</If> |

</If>

<If lang="swift,objc">

| Parameter | Description | Type |
|-----------|-------------|------|
| query | an optional object containing query parameters, as specified below. | ARTDataQuery |
| callback | called with a [`ARTPaginatedResult`](#paginated-result)[`<ARTPresenceMessage>`](#presence-message) object or an error | Callback |

</If>

#### <If lang="javascript,nodejs">`params` parameters</If><If lang="objc,swift">`ARTDataQuery` properties</If><If lang="csharp">[`PaginatedRequestParams`](#paginated-request-params) properties</If><If lang="java,php,python,ruby,go">`options` parameters</If>

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs,java,objc,swift,php,go">start</If><If lang="ruby">:start</If><If lang="csharp">Start</If><If lang="python">start</If> | _beginning of time_ earliest <If lang="csharp">`DateTimeOffset` or </If><If lang="ruby">`Time` or </If>time in milliseconds since the epoch for any presence events retrieved | <If lang="javascript,nodejs">`Number`</If><If lang="ruby">`Int` or `Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="java,php,python,go">`Long`</If><If lang="objc,swift">Long</If> |
| <If lang="javascript,nodejs,java,objc,swift,php,go">end</If><If lang="ruby">:end</If><If lang="csharp">End</If><If lang="python">end</If> | _current time_ latest <If lang="csharp">`DateTimeOffset` or </If><If lang="ruby">`Time` or </If>time in milliseconds since the epoch for any presence events retrieved | <If lang="javascript,nodejs">`Number`</If><If lang="ruby">`Int` or `Time`</If><If lang="csharp">`DateTimeOffset`</If><If lang="java,php,python,go">`Long`</If><If lang="objc,swift">Long</If> |
| <If lang="javascript,nodejs,java,objc,swift,php,go">direction</If><If lang="ruby">:direction</If><If lang="csharp">Direction</If><If lang="python">direction</If> | _backwards_ <If lang="ruby">`:forwards` or `:backwards`</If><If lang="javascript,nodejs,java,objc,swift,php,python,go">`forwards` or `backwards`</If><If lang="csharp">forwards or backwards</If> | <If lang="javascript,nodejs,java,objc,swift,php,python,go">`String`</If><If lang="ruby">`Symbol`</If><If lang="csharp">`Direction` enum</If> |
| <If lang="javascript,nodejs,java,objc,swift,php,go">limit</If><If lang="ruby">:limit</If><If lang="csharp">Limit</If><If lang="python">limit</If> | _100_ maximum number of presence events to retrieve up to 1,000 | <If lang="javascript,nodejs">`Number`</If><If lang="java,php,python,ruby,csharp,objc,swift,go">`Integer`</If> |

<If lang="javascript,nodejs">

#### Returns

Returns a promise. On success, the promise is fulfilled with 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, 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="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 presence event history, `err` contains an [`ErrorInfo`](#error-info) object with the failure reason.

</If>

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

#### 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 presence event history will raise an [`AblyException`](https://ably.com/docs/api/rest-sdk/types.md#ably-exception)

</If>

<If lang="go">

#### 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 mean `error` contains an [`ErrorInfo`](#error-info) object with the failure reason.

</If>

<If lang="csharp">

#### Returns

This method returns a `Task` and 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 presence event history will raise an [`AblyException`](https://ably.com/docs/api/rest-sdk/types.md#ably-exception)

</If>

## Related types 

### <If lang="javascript,nodejs,php,python,go">Message</If><If lang="swift,objc">ARTMessage</If><If lang="ruby">Ably::Models::Message Enum</If><If lang="java">io.ably.lib.types.Message</If><If lang="csharp">IO.Ably.Message</If> 

A `Message` represents an individual message that is sent to or received from Ably.

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

The event name, if provided. <br />_Type: `String`_

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

The message payload, if provided.<br />_Type: <If lang="javascript,nodejs,go">`String`, `StringBuffer`, `JSON Object`</If><If lang="java">`String`, `ByteArray`, `JSONObject`, `JSONArray`</If><If lang="csharp">`String`, `byte[]`, `plain C# object that can be serialized to JSON`</If><If lang="ruby">`String`, `Binary` (ASCII-8BIT String), `Hash`, `Array`</If><If lang="python">`String`, `Bytearray`, `Dict`, `List`</If><If lang="php">`String`, `Binary String`, `Associative Array`, `Array`</If><If lang="objc">`NSString *`, `NSData *`, `NSDictionary *`, `NSArray *`</If><If lang="swift">`String`, `NSData`, `Dictionary`, `Array`</If>_

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

Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](https://ably.com/docs/push/publish.md#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](https://ably.com/docs/pub-sub/advanced.md#ephemeral), and [`privileged`](https://ably.com/docs/platform/integrations/webhooks.md#skipping) objects.<br />_Type: <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="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="go">`String`, `[]byte`</If>_

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

A Unique ID assigned by Ably to this message.<br />_Type: `String`_

### <If lang="javascript,nodejs,php,java,objc,swift,go">clientId</If><If lang="ruby,python">client_id</If><If lang="csharp">ClientId</If> 

The client ID of the publisher of this message.<br />_Type: `String`_

### <If lang="javascript,nodejs,php,java,objc,swift,go">connectionId</If><If lang="ruby,python">connection_id</If><If lang="csharp">ConnectionId</If> 

The connection ID of the publisher of this message.<br />_Type: `String`_

### <If lang="javascript,nodejs,php,java,objc,swift">connectionKey</If><If lang="csharp,go">ConnectionKey</If><If lang="ruby,python">connection_key</If> 

A connection key, which can optionally be included for a REST publish as part of the [publishing on behalf of a realtime client functionality](https://ably.com/docs/pub-sub/advanced.md#publish-on-behalf).<br />_Type: `String`_

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

Timestamp when the message was first received by the Ably, as <If lang="javascript,nodejs,php,python,go,java">milliseconds since the epoch</If><If lang="ruby">a `Time` object</If>.<br />_Type: <If lang="javascript,nodejs,php,python">`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="go">Integer</If>_

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

This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.<br />_Type: `String`_

<If lang="javascript,nodejs">

### action 

The action type of the message, one of the [`MessageAction`](https://ably.com/docs/api/realtime-sdk/types.md#message-action) enum values.<br />_Type: `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }`_

### serial 

A server-assigned identifier that will be the same in all future updates of this message. It  can be used to add annotations to a message. Serial will only be set if you enable annotations in [channel rules](https://ably.com/docs/channels.md#rules).<br />_Type: `String`_

### annotations 

An object containing information about annotations that have been made to the object.<br />_Type: [`MessageAnnotations`](https://ably.com/docs/api/realtime-sdk/types.md#message-annotations)_

</If>

### Message constructors 

#### Message.fromEncoded 

`Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message`

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

#### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| encodedMsg | a `Message`-like deserialized object. | `Object` |
| channelOptions | an optional [`ChannelOptions`](https://ably.com/docs/api/realtime-sdk/types.md#channel-options). If you have an encrypted channel, use this to allow the library to decrypt the data. | `Object` |

#### Returns

A [`Message`](https://ably.com/docs/api/realtime-sdk/types.md#message) object

#### Message.fromEncodedArray 

`Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[]`

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

#### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| encodedMsgs | an array of `Message`-like deserialized objects. | `Array` |
| channelOptions | an optional [`ChannelOptions`](https://ably.com/docs/api/realtime-sdk/types.md#channel-options). If you have an encrypted channel, use this to allow the library to decrypt the data. | `Object` |

#### Returns

An `Array` of [`Message`](https://ably.com/docs/api/realtime-sdk/types.md#message) objects

### <If lang="javascript,nodejs,php,python,go">PresenceMessage</If><If lang="swift,objc">ARTPresenceMessage</If><If lang="ruby">Ably::Models::PresenceMessage Enum</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,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">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">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">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="javascript,nodejs,java,objc,swift,php,python,ruby">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">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">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">timestamp</If><If lang="csharp,go">Timestamp</If> | Timestamp when the presence update was received by Ably<If lang="javascript,nodejs,java,php,python">, as milliseconds since the epoch</If>. | <If lang="javascript,nodejs,php,python">`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="go">Integer</If> |
| <If lang="javascript,nodejs,java,objc,swift,php,python,ruby">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">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">

### IO.Ably.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">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,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">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`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | <If lang="javascript,nodejs,java,objc,swift,php,ruby">`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">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,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">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">

`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">`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">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">

`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">`next`</If><If lang="csharp,go">`Next`</If> available.

##### <If lang="javascript,nodejs,java,objc,swift,php,python,ruby,go">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,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">`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>