--- source_url: https://www.pubnub.com/docs/sdks/ruby/api-reference/presence title: Presence API for Ruby SDK updated_at: 2026-05-25T11:29:15.581Z 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 # Presence API for Ruby SDK PubNub Ruby SDK, use the latest version: 6.0.2 Install: ```bash gem install pubnub@6.0.2 ``` Presence lets you track who is online or offline and store custom state information. Presence shows: * When a user has joined or left a channel * How many users are subscribed to a particular channel (occupancy) * Which channels a user or device is subscribed to * Presence state associated with these users Learn more about our Presence feature in the [Presence overview](https://www.pubnub.com/docs/general/presence/overview). ## Here now :::warning Requires Presence This method requires that the Presence add-on 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/). For information on how to receive presence events and what those events are, refer to [Presence Events](https://www.pubnub.com/docs/general/presence/presence-events#subscribe-to-presence-channel). ::: This method returns information about the current state of a channel, including a list of unique user IDs (universally unique identifiers, UUIDs) currently subscribed to the channel and the total occupancy count of the channel. :::note Cache This method has a 3-second response cache time. ::: ### Method(s) To call `Here Now` you can use the following method(s) in the Ruby SDK: ```ruby here_now( channels: channels, channel_groups: channel_groups, limit: limit, offset: offset, http_sync: http_sync, callback: callback ) ``` | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | channels | String, | Optional | | Specify the `channels` name to return occupancy results. If `channels` is not provided, `here_now` will return data for all channels (global `here_now`). | | channel_groups | String, | Optional | | Specify the `channel_groups` name to return occupancy results. Wildcards are not supported. | | limit | Integer | Optional | `1000` | Maximum number of occupants to return per channel. Valid range: `0-1000`. Use `0` to get occupancy counts without user details. | | offset | Integer | Optional | `0` | Zero-based starting index for pagination. Returns occupants starting from this position in the list. Must be `>= 0`. Requires `limit > 0`. Use with `limit` to paginate through large occupant lists. This parameter is only included in the request when `offset > 0`. | | http_sync | Boolean | Optional | `false` | Method will be executed `asynchronously` and will return future, to get it's `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 | Lambda | Optional | | `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 #### Get a list of uuids subscribed to channel :::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. ::: ```ruby require 'pubnub' def fetch_uuids(pubnub) pubnub.here_now( channel: 'my_channel' ) do |envelope| if envelope.status[:error] puts "Error fetching UUIDs: #{envelope.status[:error]}" else puts "UUIDs subscribed to my_channel: #{envelope.result[:data][:uuids]}" puts "Occupancy: #{envelope.result[:data][:occupancy]}" end end end def main # Configuration for PubNub instance pubnub = Pubnub.new( subscribe_key: ENV.fetch('SUBSCRIBE_KEY', 'demo'), user_id: 'myUniqueUserId' ) # Fetch UUIDs fetch_uuids(pubnub) sleep 1 # Allow time for the async operation to complete end if __FILE__ == $0 main end ``` ### Response ```ruby # { :uuids => ["2d588b75-0451-4bde-8952-13128c10e952"], :occupancy => 1 } }, @status = { :code => 200 } > ``` ## Where now :::warning Requires Presence This method requires that the Presence add-on 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/). For information on how to receive presence events and what those events are, refer to [Presence Events](https://www.pubnub.com/docs/general/presence/presence-events#subscribe-to-presence-channel). ::: This method returns the list of channels a UUID is subscribed to. :::note Timeout events If the app restarts (or the page refreshes) within the heartbeat window, no timeout event is generated. ::: ### Method(s) To call `where_now()` you can use the following method(s) in the Ruby SDK: ```ruby where_now( uuid: uuid, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `uuid` *Type: String | `UUID` we are looking for. | | `http_sync`Type: Boolean | Default `false`. Method will be executed `asynchronously` and will return future, to get it's `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.where_now( uuid: "my_uuid" ) do |envelope| puts envelope.result[:data] end ``` ### Response ```ruby # { "channels" => ["whatever"] } }, @status = { :code =>200 } > ``` ## User state :::warning Requires Presence This method requires that the Presence add-on 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/). For information on how to receive presence events and what those events are, refer to [Presence Events](https://www.pubnub.com/docs/general/presence/presence-events#subscribe-to-presence-channel). ::: Clients can set a dynamic custom state (score, game state, location) for their users on one or more channels and store it on a channel as long as the user stays subscribed. The state is not persisted, and when the client disconnects, the state data is lost. For more information, refer to [Presence State](https://www.pubnub.com/docs/general/presence/presence-state). ### Method(s) ```ruby set_state( channels: channels, state: state, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `channels` *Type: String, Symbol | Specify `channels` name to set `state` for. | | `state` *Type: Hash | The `state` to set. | | `http_sync`Type: Boolean | Default `false`. Method will be executed `asynchronously` and will return future, to get it's `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). | ```ruby get_state( channels: channels, uuid: uuid, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `channels` *Type: String, Symbol | Specify `channels` name to get `state` from. | | `uuid`Type: String | Specifies `UUID`. | | `http_sync`Type: Boolean | Default `false`. Method will be executed `asynchronously` and will return future, to get it's `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 #### Set state ```ruby pubnub.set_state(channel: 'my_channel', state: { key: 'value' }) do |envelope| puts envelope.status end ``` #### Get state ```ruby pubnub.state(channel: :my_channel, uuid: 'some-uuid') do |envelope| puts envelope.result[:data][:state] end ``` ### Response ```ruby # { :state => { "age"=>59, "first" => "Robert", "last" => "Plant" }, :channel=>"whatever" } }, @status = { :code => 200 } > ```