---
source_url: https://www.pubnub.com/docs/sdks/ruby/api-reference/storage-and-playback
title: Message Persistence API for Ruby SDK
updated_at: 2026-06-11T11:37:31.436Z
sdk_name: PubNub Ruby SDK
sdk_version: 6.0.2
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Message Persistence API for Ruby SDK

PubNub Ruby SDK, use the latest version: 6.0.2

Install:

```bash
gem install pubnub@6.0.2
```

Message Persistence gives you real-time access to the history of messages published to PubNub. Each message is timestamped to the nearest 10 nanoseconds and stored across multiple availability zones in several geographic locations. You can encrypt stored messages with AES-256 so they are not readable on PubNub’s network. For details, see [Message Persistence](https://www.pubnub.com/docs/general/storage).

You control how long messages are stored through your account’s retention policy. Options include: 1 day, 7 days, 30 days, 3 months, 6 months, 1 year, or Unlimited.

You can retrieve the following:

* Messages
* Message reactions
* Files (using the File Sharing API)

## Batch history

:::note Requires Message Persistence
This method requires that Message Persistence is enabled for your key in the [Admin Portal](https://admin.pubnub.com/). Read the [support page](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) on enabling add-on features on your keys.
:::

This function fetches historical messages from multiple channels. The `include_message_actions` flag also allows you to fetch message actions along with the messages for a single channel.

:::tip fetch_messages() vs history()
Use `fetch_messages()` for retrieving messages from multiple channels simultaneously (up to 500 channels). For single-channel message retrieval with additional options like `reverse` or `include_token`, use the [history()](#history) method instead.
:::

It's possible to control how messages are returned and in what order. For example, you can:

* Search for messages starting on the newest end of the timeline.
* Search for messages from the oldest end of the timeline.
* Page through results by providing a `start` OR `end` timetoken.
* Retrieve a *slice* of the time line by providing both a `start` AND `end` timetoken.
* Retrieve a specific (maximum) number of messages using the `max` parameter.

Batch history returns up to 100 messages on a single channel, or 25 per channel on a maximum of 500 channels. Use the `start` and `end` timestamps to page through the next batch of messages.

:::tip Start & End parameter usage clarity
If you specify only the `start` parameter (without `end`), you will receive messages that are older than the `start` timetoken.
If you specify only the `end` parameter (without `start`), you will receive messages from that `end` timetoken and newer.
Specify values for both `start` and `end` parameters to retrieve messages between those timetokens (inclusive of the `end` value).
Keep in mind that you will still receive a maximum of 100 messages (or 25, for multiple channels) even if there are more messages that meet the timetoken values. Iterative calls to history adjusting the `start` timetoken are necessary to page through the full set of results if more messages meet the timetoken values.
:::

### Method(s)

Use the following method(s) in the Ruby SDK:

```ruby
fetch_messages(
    channel: channel,
    channels: channels,
    max: max,
    start: start,
    end: end,
    include_meta: include_meta,
    include_message_actions: include_message_actions,
    include_uuid: include_uuid,
    include_message_type: include_message_type,
    include_custom_message_type: include_custom_message_type,
    encode_channels: encode_channels,
    cipher_key: cipher_key,
    random_iv: random_iv,
    http_sync: http_sync,
    callback: callback
)
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| channel | String | Optional |  | A single channel to fetch messages from. You can use the `include_message_actions` flag to get message actions history for this channel. |
| channels | Array | Optional |  | Array of channels to fetch messages from. Maximum of 500 channels. Can't be used with `include_message_actions` as you can only get the message actions history for a single channel. |
| max | Integer | Optional |  | Maximum number of messages to return per channel. Default is `25` for multiple channels or `100` for a single channel. |
| start | Integer | Optional |  | timetoken delimiting the `start` of time slice (exclusive) to pull messages from. |
| end | Integer | Optional |  | timetoken delimiting the `end` of time slice (inclusive) to pull messages from. |
| include_meta | Boolean | Optional |  | Include message metadata in the response. Default is `false`. |
| include_message_actions | Boolean | Optional |  | Include message actions in the response. Only works with single channel. Default is `false`. |
| include_uuid | Boolean | Optional |  | Include UUID of the publisher in the response. Default is `true`. |
| include_message_type | Boolean | Optional |  | Whether to include the PubNub message type in the response. Default is `true`. |
| include_custom_message_type | Boolean | Optional |  | Whether to include the custom message type in the response. Default is `false`. |
| encode_channels | Boolean | Optional |  | Whether to encode channel names for URL safety. Default is `true`. Set to `false` when not using `include_message_actions`. |
| cipher_key | String | Optional |  | Custom cipher key for message decryption. If provided, overrides the default crypto configuration. |
| random_iv | Boolean | Optional |  | Whether to use random initialization vector for encryption. Default is `true`. Only used when `cipher_key` is provided. |
| http_sync | Boolean | Optional |  | Default `false`. The method is executed asynchronously and returns a future. To retrieve the value, call the `value` method on the `Envelope` object. If set to `true`, method returns an array of envelopes (even if there's only one `Envelope`). |
| callback | Lambda | Optional |  | Callback that is called for each `Envelope`. For `async` methods, a future is returned. To retrieve the value, call the `value` method on the `Envelope` object. The thread is locked until the `value` is returned. |

### Sample code

:::tip Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
:::

Retrieve the last 25 messages on multiple channels:

```ruby
require 'pubnub'

def fetch_messages(pubnub)
  pubnub.fetch_messages(
    channels: ['demo', 'example'],
    max: 25
  ) do |envelope|
    if envelope.status[:error]
      puts "Error fetching messages: #{envelope.status[:error]}"
    else
      puts "Messages fetched successfully:"
      envelope.result[:data][:channels].each do |channel, messages|
        puts "Channel: #{channel}"
        messages.each do |message|
          puts "Message: #{message['message']}, Timetoken: #{message['timetoken']}"
        end
      end
    end
  end
end

def main
  # Configuration for PubNub instance
  pubnub = Pubnub.new(
    subscribe_key: ENV.fetch('SUBSCRIBE_KEY', 'demo'),
    user_id: 'myUniqueUserId'
  )

  # Fetch messages
  fetch_messages(pubnub)
  sleep 1 # Allow time for the async operation to complete
end

if __FILE__ == $0
  main
end
```

### Response

The Ruby SDK returns false on fail. An array is returned on success.

The `fetch_messages()` function returns a list of messages for each channel. The output below demonstrates the format for a `fetch_messages()` response:

```ruby
    @result = {
        :data => {
            :channels => {
                'channel1' => [
                    { 'message' => 'Message1', 'timetoken' => 15010808292416521 },
                    { 'message' => 'Message2', 'timetoken' => 15010808292416522 }
                ],
                'channel2' => [
                    { 'message' => 'Message3', 'timetoken' => 15010808292416523 },
                    { 'message' => 'Message4', 'timetoken' => 15010808292416524 }
                ]
            }
        }
    },
    @status = {
        :code => 200
    }
>
```

### Other examples

#### Fetch messages with metadata

```ruby
pubnub.fetch_messages(
    channels: ['channel1', 'channel2'],
    include_meta: true
) do |envelope|
    puts envelope.result[:data][:channels]
end
```

#### Fetch messages with message actions

```ruby
pubnub.fetch_messages(
    channel: 'channel1',
    include_message_actions: true
) do |envelope|
    puts envelope.result[:data][:channels]
end
```

#### Fetch messages with custom encryption

```ruby
pubnub.fetch_messages(
    channels: ['channel1', 'channel2'],
    cipher_key: 'my_custom_cipher_key',
    random_iv: true
) do |envelope|
    puts envelope.result[:data][:channels]
end
```

## History

:::warning Requires Message Persistence
This method requires that Message Persistence is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/).
:::

This function fetches historical messages of a channel.

It is possible to control how messages are returned and in what order, for example you can:

* Search for messages starting on the newest end of the timeline (default behavior - `reverse` = `false`)
* Search for messages from the oldest end of the timeline by setting `reverse` to `true`.
* Page through results by providing a `start` OR `end` [timetoken](https://www.pubnub.com/docs/sdks/ruby/api-reference/misc#time).
* Retrieve a *slice* of the time line by providing both a `start` AND `end` timetoken.
* Limit the number of messages to a specific quantity using the `count` parameter.

:::tip Start & End parameter usage clarity
If only the `start` parameter is specified (without `end`), you will receive messages that are **older** than and up to that `start` timetoken value. If only the `end` parameter is specified (without `start`) you will receive messages that match that `end` timetoken value and **newer**. Specifying values for both `start` *and* `end` parameters will return messages between those timetoken values (inclusive on the `end` value). Keep in mind that you will still receive a maximum of 100 messages even if there are more messages that meet the timetoken values. Iterative calls to history adjusting the `start` timetoken is necessary to page through the full set of results if more than 100 messages meet the timetoken values.
:::

### Method(s)

Use the following method(s) in the Ruby SDK:

```ruby
history(
    channels: channels,
    count: count,
    start: start,
    end: end,
    reverse: reverse,
    include_token: include_token,
    include_meta: include_meta,
    http_sync: http_sync,
    callback: callback
)
```

| Parameter | Description |
| --- | --- |
| `channels` *Type: String, Symbol | Specify `channels` to return history messages from. |
| `count`Type: Integer | Specifies the number of historical messages to return. Default/maximum is `100`. |
| `start`Type: Integer | timetoken delimiting the `start` of time slice (exclusive) to pull messages from. |
| `end`Type: Integer | timetoken delimiting the `end` of time slice (inclusive) to pull messages from. |
| `reverse`Type: Boolean | Setting to `true` will traverse the time line in reverse starting with the oldest `message` first.Default is `false`. If both `start` and `end` arguments are provided, `reverse` is ignored and messages are returned starting with the newest `message`. |
| `http_sync`Type: Boolean | Default `false`. Method will be executed `asynchronously` and will return future, to get its `value` you can use `value` method. If set to `true`, method will return array of envelopes (even if there's only one `envelope`). For `sync` methods `Envelope` object will be returned. |
| `include_token`Type: Boolean | With `include_token` parameter set to `true` each envelope will contain timetoken specific for `message` that it holds. Default: `false` |
| `include_meta`Type: Boolean | When set to `true`, the history response will include the `meta` information associated with each message if it was set during [publishing](https://www.pubnub.com/docs/sdks/kotlin/api-reference/publish-and-subscribe#publish). Default: `false`. |
| `callback`Type: Lambda accepting one parameter | `Callback` that will be called for each `envelope`. For `async` methods future will be returned, to retrieve `value` `Envelope` object you have to call `value` method (thread will be locked until the `value` is returned). |

:::tip
Using the
reverse
parameter
Messages are always returned sorted in ascending time direction from history regardless of `reverse`. The `reverse` direction matters when you have more than 100 (or `count`, if it's set) messages in the time interval, in which case `reverse` determines the end of the time interval from which it should start retrieving the messages.
:::

### Sample code

Retrieve the last 100 messages on a channel:

```ruby
pubnub.history(
    channel: 'history_channel',
    count: 100
) do |envelope|
    puts envelope.result[:data][:messages]
end
```

### Response

The Ruby SDK returns false on fail. An array is returned on success.

The `history()` function returns a list of up to 100 messages, the timetoken of the first (oldest) message and the timetoken of the last (newest) message in the resulting set of messages. The output below demonstrates the format for a `history()` response:

```ruby
#<Pubnub::Envelope:0x007fd384da4ad0
    @result = {
        :data => {
            :messages => ["Pub1", "Pub2", "Pub3", "Pub4", "Pub5", "Pub6", "Pub7", "Pub8", "Pub9", "Pub10"],
            :end => 15010808292416521,
            :start => 15010808287349573
        }
    },
    @status = {
        :code => 200
    }
>
```

### Other examples

#### Use history() to retrieve the three oldest messages by retrieving from the time line in reverse

```ruby
pubnub.history(
    channel: :history,
    count: 3,
    reverse: true,
    http_sync: true
)
```

##### Response

```ruby
#<Pubnub::Envelope:0x007fd3858e34c8
    @result = {
        :data => {
            :messages => ["Pub1", "Pub2", "Pub3"],
            :end => 15010808288498250,
            :start => 15010808287349573
        }
    },
    @status = {
        :code => 200
    }
>
```

#### Use history() to retrieve messages newer than a given timetoken by paging from oldest message to newest message starting at a single point in time (exclusive)

```ruby
pubnub.history(
    channel: :history,
    start: 15010808287700000,
    reverse: true,
    http_sync: true
)
```

##### Response

```ruby
#<Pubnub::Envelope:0x007fd38523ced0
    @result = {
        :data => {
            :messages => ["Pub1"],
            :end => 15010808287349573,
            :start => 15010808287349573
        }
    }
    @status = {
        :code => 200
    }
>
```

#### Use history() to retrieve messages until a given timetoken by paging from newest message to oldest message until a specific end point in time (inclusive)

```ruby
pubnub.history(
    channel: :history,
    end: 15010808287700000,
    http_sync: true
)
```

##### Response

```ruby
#<Pubnub::Envelope:0x007fd3860dbce8
    @result = {
        :data => {
            :messages => ["Pub2", "Pub3", "Pub4", "Pub5", "Pub6", "Pub7", "Pub8", "Pub9", "Pub10"],
            :end => 15010808292416521,
            :start => 15010808287951883
        }
    }
    @status = {
        :code => 200
    }
>
```

#### History paging example

:::note Usage
You can call the method by passing 0 or a valid **timetoken** as the argument.
:::

```ruby
pubnub.paged_history(channel: :messages, limit: 10, page: 20) do |envelope|
    puts envelope.result[:data][:messages]
end
```

#### Include timetoken in history response

```ruby
# ASYNC
# Call history with include_token: true
future_envelope = pubnub.history(channel: :demo, include_token: true)
# Get timetoken of first retrieved message
future_envelope.value.result[:data][:messages].first['timetoken']

# SYNC
# Call history with include_token: true
envelope = pubnub.history(channel: :demo, include_token: true, http_sync: true)
# Get timetoken of first retrieved message
envelope.result[:data][:messages].first['timetoken']

# Example response in result[:data][:messages]
# [
#   {"message"=>"Whatever", "timetoken"=>14865606002747651},
#   {"message"=>"Message", "timetoken"=>14865606051899206},
#   {"message"=>"Another", "timetoken"=>14865606101428628}
# ]
```

## Delete messages from history

:::warning Requires Message Persistence
This method requires that Message Persistence is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/).
:::

Removes the messages from the history of a specific channel.

:::note Required setting
There is a setting to accept delete from history requests for a key, which you must enable by checking the Enable `Delete-From-History` checkbox in the key settings for your key in the Admin Portal.
Requires Initialization with secret key.
:::

### Method(s)

To `Delete Messages from History` you can use the following method(s) in the Ruby SDK.

```ruby
delete_messages(
    channels: channels,
    start: start,
    end: end,
    http_sync: http_sync,
    callback: callback
)
```

| Parameter | Description |
| --- | --- |
| `channels` *Type: String, Symbol | `Channels` from which messages will be deleted. |
| `start`Type: String, Integer | `Timestamp` since when messages should be deleted. |
| `end`Type: String, Integer | `Timestamp` until when messages should be deleted. |
| `http_sync`Type: Boolean | Default `false`. Method will be executed `asynchronously` and will return future, to get its `value` you can use `value` method. If set to `true`, method will return array of envelopes (even if there's only one `envelope`). For `sync` methods `Envelope` object will be returned. |
| `callback`Type: Lambda accepting one parameter | `Callback` that will be called for each `envelope`. For `async` methods future will be returned, to retrieve `value` `Envelope` object you have to call `value` method (thread will be locked until the `value` is returned). |

### Sample code

```ruby
pubnub.delete_messages(channel: 'my-channel', start: 1508284800, end: 1508935781, callback: check_response_status)
```

### Response

```ruby
#<Pubnub::Envelope
    @status = {
        :code => 200,
        :operation => :delete,
        :category => :ack,
        :error => false,
        # [...]
    },
    # [...]
>
```

### Other examples

#### Delete specific message from history

To delete a specific message, pass the `publish timetoken` (received from a successful publish) in the `end` parameter and `timetoken +/- 1` in the `start` parameter. For example, if `15526611838554310` is the `publish timetoken`, pass `15526611838554309` in `start` and `15526611838554310` in `end` parameters respectively as shown in the following code snippet.

```ruby
pubnub.delete_messages(channel: 'my-channel', start: 15526611838554309, end: 15526611838554310, callback: check_response_status)
```

## Message counts

:::warning Requires Message Persistence
This method requires that Message Persistence is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/).
:::

Returns the number of messages published on one or more channels since a given time. The `count` returned is the number of messages in history with a `timetoken` value `greater than or equal to` than the passed value in the `channel_timetokens`parameter.

:::note Unlimited message retention
For keys with unlimited message retention enabled, this method considers only messages published in the last 30 days.
:::

### Method(s)

You can use the following method(s) in the Ruby SDK:

```ruby
pubnub.message_counts(
    channels: array_of_channels,
    channel_timetokens: array_of_timetokens
)
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: String, SymbolDefault: n/a | Either array of channels, string with single channel or string with comma separated channels |
| `channel_timetokens` *Type: ArrayDefault: `null` | Array of `timetokens`, in order of the channels list. Specify a single `timetoken` to apply it to all channels. Otherwise, the list of `timetokens` must be the same length as the list of channels, or the function returns a `PNStatus` with an error flag. |
| `http_sync`Type: BooleanDefault: n/a | Default `false`. Method will be executed `asynchronously` and will return future, to get its `value` you can use `value` method. If set to `true`, method will return array of envelopes (even if there's only one `envelope`). For `sync` methods `Envelope` object will be returned. |

### Sample code

```ruby
envelope = pubnub.message_counts(channel:['a', 'b', 'c', 'd'], channel_timetokens: 12123).value
    p envelope.result[:data]
```

### Returns

:::note Channels count
`Channels` without messages have a count of 0. `Channels` with 10,000 messages or more have a count of 10000.
:::

Returns `Concurrent::Future` object if PubNub is configured with `http_sync: false` (default behavior) or `envelope` if it's set to `sync mode`

```ruby
#<Pubnub::Envelope
    @result=
      {
       :data=>
        {
         "channels"=>{"a"=>2, "c"=>0, "b"=>0, "d"=>0}
        }
     @status=
      {
        :code=>200
      }
>
```

### Other examples

#### Retrieve count of messages using different timetokens for each channel

```ruby
envelope = pubnub.message_counts(channel:['a', 'b', 'c', 'd'], channel_timetokens: [123135129, 123135124, 12312312, 123135125]).value
    p envelope.result[:data]
```

## Terms in this document

* **Channel** - A pathway for sending and receiving messages between devices, created automatically when you first use it, that can handle any number of users and messages for different communication needs, like 1-1 text chats, group conversations, and other data streaming.
* **Message** - A unit of data transmitted between clients or between a client and a server in PubNub, containing information such as text, binary data, or structured data formats like JSON. Messages are sent over channels and can be tracked for delivery and read status.
* **PubNub** - PubNub is a real-time messaging platform that provides APIs and SDKs for building scalable applications. It handles the complex infrastructure of real-time communication, including: Message delivery and persistence, Presence detection, Access control, Push notifications, File sharing, Serverless processing with Functions and Events & Actions, Analytics and monitoring with BizOps Workspace, AI-powered insights with Illuminate.
* **Timetoken** - A unique identifier for each message that represents the number of 100-nanosecond intervals since January 1, 1970, for example, 16200000000000000.