--- source_url: https://www.pubnub.com/docs/sdks/ruby/api-reference/objects title: App Context API for Ruby SDK updated_at: 2026-06-26T11:06:54.257Z sdk_name: PubNub Ruby SDK sdk_version: 6.1.0 --- > 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 # App Context API for Ruby SDK PubNub Ruby SDK, use the latest version: 6.1.0 Install: ```bash gem install pubnub@6.1.0 ``` App Context provides easy-to-use, serverless storage for user and channel data you need to build innovative, reliable, scalable applications. Use App Context to store metadata about your application users and channels, and their membership associations, without the need to stand up your own databases. PubNub also triggers events when object data is changed: set, updated, or removed from the database. Making a request to set the same data that already exists doesn't trigger an event. Clients can receive these events in real time and update their front-end application accordingly. ## User Manage UUID metadata: list, fetch, set, and remove. Include only the fields you need to reduce payload size. ### Get metadata for all users Get a paginated list of UUID metadata. Use filters and sorting to narrow results. :::warning Required keyset configuration To get all channel and user metadata, you must uncheck the Disallow Get All Channel Metadata and Disallow Get All User Metadata checkboxes in the App Context section of your keyset configuration in the [Admin Portal](https://admin.pubnub.com) . ::: #### Method(s) To `Get All UUID Metadata` you can use the following method(s) in the Ruby SDK: ```ruby get_all_uuid_metadata( sort: sort, include: include, filter: filter, start: start, end: end, limit: limit, http_sync: http_sync, callback: callback ) ``` | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | sort | Array | Optional | | List of criteria (name of field) which should be used for sorting in ascending order. Available options are `id`, `name`, and `updated`. Use `asc` or `desc` to specify sort direction. | | include | Object | Optional | `{ count: true }` | Additional information which should be included in response. Available options: count - include how many UUID has been associated with metadata., custom - include field with additional information from metadata which has been used during UUID metadata set requests., type - include the type of the metadata., status - include the status of the metadata. | | filter | String | Optional | | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [here](https://www.pubnub.com/docs/general/metadata/filtering) | | start | String | Optional | | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | end | String | Optional | | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | limit | Integer | Optional | `100` | Number of objects to return in response. Default is `100`, which is also the maximum value. | | http_sync | Boolean | Optional | `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 | 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 :::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 get_all_uuid_metadata(pubnub) pubnub.get_all_uuid_metadata( limit: 5, include: { custom: true } ) do |envelope| if envelope.status[:error] puts "Error fetching UUID metadata: #{envelope.status[:error]}" else envelope.result[:data][:metadata].each do |uuid_data| puts "UUID: #{uuid_data[:id]}" puts "Name: #{uuid_data[:name]}" puts "Custom: #{uuid_data[:custom]}" puts "Updated: #{uuid_data[:updated]}" end end end end def main # Configuration for PubNub instance pubnub = Pubnub.new( subscribe_key: ENV.fetch('SUBSCRIBE_KEY', 'demo'), user_id: 'myUniqueUserId' ) # Get all UUID metadata get_all_uuid_metadata(pubnub) sleep 1 # Allow time for the async operation to complete end if __FILE__ == $0 main end ``` #### Response ```ruby # { :metadata => [ { :id => "mg", :name => "magnum", :externalId => nil, :profileUrl => nil, :email => nil, :custom => { "XXX" => "YYYY" }, :updated => , :eTag => "Ad2eyIWXwJzBqAE" } ], :totalCount => 1, :next => "MQ", :prev => nil } }, @status = { :code => 200 } > ``` ### Get user metadata Fetch metadata for a single UUID. Include the Custom object if you need custom fields. #### Method(s) To `Get UUID Metadata` you can use the following method(s) in the Ruby SDK: ```ruby get_uuid_metadata( uuid: uuid, include: include, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `uuid`Type: StringDefault: Client UUID | Identifier for which associated `metadata` should be fetched. Default: configured PubNub client `uuid`. | | `include`Type: ObjectDefault: `{ custom: true }` | Additional information which should be included in response. Available options: custom - include field with additional information from metadata which has been used during UUID metadata set requests., type - include the type of the metadata., status - include the status of the metadata. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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.get_uuid_metadata(include: { custom: true }) do |envelope| puts envelope end ``` #### Response ```ruby # { :id => "mg", :name => "magnum", :externalId => nil, :profileUrl => nil, :email => nil, :custom => { "XXX" => "YYYY" }, :updated => , :eTag => "Ad2eyIWXwJzBqAE" } }, @status = { :code => 200 } > ``` ### Set user metadata Create or update metadata for a UUID. Use the eTag (if available in the SDK) to avoid overwriting concurrent updates. :::warning Unsupported partial updates of custom metadata The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must: 1. Get the existing metadata and store it locally. 2. Append the new custom metadata to the existing one. 3. Set the entire updated custom object. ::: Set metadata for a UUID in the database, optionally including the custom data object for each. #### Method(s) To `Set UUID Metadata` you can use the following method(s) in the Ruby SDK: ```ruby set_uuid_metadata( uuid: uuid, metadata: metadata, include: include, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `uuid`Type: StringDefault: Client UUID | Identifier with which new `metadata` should be associated. Default: configured PubNub client `uuid`. | | `metadata` *Type: ObjectDefault: n/a | Metadata information which should be associated with `UUID`. **Available options:** name - Name which should be stored in metadata associated with specified UUID., externalId - External identifier (database, auth service) associated with specified UUID., profileUrl - External URL with information for specified UUID representation., custom - Additional information which should be stored in metadata associated with specified UUID. App Context filtering language doesn’t support filtering by custom properties., email - Email address which should be stored in metadata associated with specified UUID., type - Type of the metadata associated with specified UUID., status - Status of the metadata associated with specified UUID. | | `include`Type: ObjectDefault: `{ custom: true }` | Additional information which should be included in response. **Available options:** custom - include field with additional information from metadata which has been used during UUID metadata set requests. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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 API limits To learn about the maximum length of parameters used to set user metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-user-metadata). ::: #### Sample code ```ruby pubnub.set_uuid_metadata( uuid: 'mg', metadata: { name: 'magnum', custom: { XXX: 'YYYY' } }, include: { custom: true } ) do |envelope| puts envelope end ``` #### Response ```ruby # { :id => "mg", :name => "magnum", :externalId => nil, :profileUrl => nil, :email => nil, :custom => { "XXX" => "YYYY" }, :updated => , :eTag => "Ad2eyIWXwJzBqAE" } }, @status = { :code => 200 } > ``` ### Remove user metadata Delete metadata for the specified UUID. #### Method(s) To `Remove UUID Metadata` you can use the following method(s) in the Ruby SDK: ```ruby remove_uuid_metadata( uuid: uuid, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `uuid`Type: StringDefault: Client UUID | Identifier for which associated `metadata` should be removed. Default: configured PubNub client `uuid`. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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.remove_uuid_metadata(uuid: 'mg') do |envelope| puts envelope end ``` #### Response ```ruby # 200, :operation => :remove_uuid_metadata, :category => :ack, :error => false, # [...] }, # [...] > ``` ## Channel Manage channel metadata: list, fetch, set, and remove. ### Get metadata for all channels Get a paginated list of channel metadata. Use filters and sorting to narrow results. #### Method(s) To `Get All Channel Metadata` you can use the following method(s) in the Ruby SDK: ```ruby get_all_channels_metadata( sort: sort, include: include, filter: filter, start: start, end: end, limit: limit, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `sort`Type: ArrayDefault: n/a | List of criteria (name of field) which should be used for sorting in ascending order. Available options are `id`, `name`, and `updated`. Use `asc` or `desc` to specify sort direction. | | `include`Type: ObjectDefault: `{ count: true }` | Additional information which should be included in response. **Available options:** count - include how many channels has been associated with metadata., custom - include field with additional information from metadata which has been used during channel metadata set requests., type - include the type of the metadata., status - include the status of the metadata. | | `filter`Type: StringDefault: n/a | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [here](https://www.pubnub.com/docs/general/metadata/filtering) | | `start`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: IntegerDefault: 100 | Number of objects to return in response. Default is `100`, which is also the maximum value. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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.get_all_channels_metadata( limit: 5, include: { custom: true } ) do |envelope| puts envelope end ``` #### Response ```ruby # { :metadata => [ { :id => "rb_channel1", :name => "some_name", :description => nil, :custom => { "XXX" => "YYYY" }, :updated => , :eTag => "AZTUtcvx6NDGLQ" }, # {...} ], :totalCount => 2, :next => "MQ", :prev => nil } }, @status = { :code => 200 } > ``` ### Get channel metadata Fetch metadata for a single channel. Include the Custom object if you need custom fields. #### Method(s) To `Get Channel Metadata` you can use the following method(s) in the Ruby SDK: ```ruby get_channel_metadata( channel: channel, include: include, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `channel` *Type: StringDefault: n/a | Name of channel for which associated `metadata` should be fetched. | | `include`Type: ObjectDefault: `{ custom: true }` | Additional information which should be included in response. **Available options:** custom - include field with additional information from metadata which has been used during channel metadata set requests., type - include the type of the metadata., status - include the status of the metadata. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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.get_channel_metadata( channel: 'channel', include: { custom: true } ) do |envelope| puts envelope end ``` #### Response ```ruby # { :id => "channel", :name => "some_name", :description => nil, :custom => { "XXX" => "YYYY" }, :updated => , :eTag => "AZTUtcvx6NDGLQ" } }, @status = { :code => 200 } > ``` ### Set channel metadata Create or update metadata for a channel. Use concurrency controls if available. :::warning Unsupported partial updates of custom metadata The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must: 1. Get the existing metadata and store it locally. 2. Append the new custom metadata to the existing one. 3. Set the entire updated custom object. ::: #### Method(s) To `Set Channel Metadata` you can use the following method(s) in the Ruby SDK: ```ruby set_channel_metadata( channel: channel, metadata: metadata, include: include, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `channel` *Type: StringDefault: n/a | Name of channel with which new `metadata` should be associated. | | `metadata` *Type: ObjectDefault: n/a | Metadata information which should be associated with `channel`. **Available options:** name - Name which should stored in metadata associated with specified channel., information - Description which should be stored in metadata associated with specified channel., custom - Additional information which should be stored in metadata associated with specified channel. App Context filtering language doesn’t support filtering by custom properties., type - Type of the metadata associated with specified channel., status - Status of the metadata associated with specified channel. | | `include`Type: ObjectDefault: `{ custom: true }` | Additional information which should be included in response. **Available options:** custom - include field with additional information from metadata which has been used during UUID metadata set requests. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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 API limits To learn about the maximum length of parameters used to set channel metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-channel-metadata). ::: #### Sample code ```ruby pubnub.set_channel_metadata( channel: 'channel', metadata: { name: 'some_name', custom: { XXX: 'YYYY' } } ) do |envelope| puts envelope end ``` #### Response ```ruby # { :id => "channel", :name => "some_name", :description => nil, :custom => { "XXX" => "YYYY" }, :updated => , :eTag => "AZTUtcvx6NDGLQ" } }, @status = { :code => 200 } > ``` #### Other examples ##### Iteratively update existing metadata ```ruby require 'pubnub' require 'json' pubnub = Pubnub.new( publish_key: 'demo', subscribe_key: 'demo', uuid: 'example' ) channel = 'demo_example' help_string = <<-HELP To exit type '/exit' To show the current object type '/show' To show this help type '/help' HELP puts "We're setting the channel's #{channel} additional info. \n#{help_string}\n" puts 'Enter the channel name:' name = gets.chomp puts 'Enter the channel description:' description = gets.chomp # Setting the basic channel info pubnub.set_channel_metadata( channel: channel, metadata: { name: name, information: description } ) do |envelope| puts "The channel has been created with name and description.\n" if envelope.status[:code] == 200 end # We start to iterate over the custom fields loop do # First we have to get the current object to know what fields are already set current_object = nil pubnub.get_channel_metadata( channel: channel, include: { custom: true } ) do |envelope| current_object = envelope.result[:data] if envelope.status[:code] == 200 end # Ask for new data puts 'Enter the field name:' field_name = gets.chomp break if field_name == '/exit' if field_name == '/show' puts JSON.pretty_generate(current_object) puts "\n" next end if field_name == '/help' puts help_string next end puts 'Enter the field value:' field_value = gets.chomp custom = current_object[:custom] || {} if custom.key?(field_name) puts "Field #{field_name} already has a value. Overwrite? (y/n):" confirm = gets.chomp.downcase until %w[y n].include?(confirm) puts "Please enter 'y' or 'n':" confirm = gets.chomp.downcase end if confirm == 'n' puts "Object will not be updated.\n" next else custom[field_name] = field_value end else custom[field_name] = field_value end # Writing the updated object back to the server pubnub.set_channel_metadata( channel: channel, metadata: { custom: custom, name: current_object[:name], information: current_object[:description] } ) do |envelope| puts "Object has been updated.\n" if envelope.status[:code] == 200 end end ``` ### Remove channel metadata Delete metadata for the specified channel. #### Method(s) To `Remove Channel Metadata` you can use the following method(s) in the Ruby SDK: ```ruby remove_channel_metadata( channel: channel, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `channel` *Type: StringDefault: n/a | Name of channel with which the `metadata` should be removed. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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.remove_channel_metadata(channel: 'channel') do |envelope| puts envelope end ``` #### Response ```ruby # 200, :operation => :remove_channel_metadata, :category => :ack, :error => false, # [...] }, # [...] > ``` ## Channel memberships Manage the channels a UUID belongs to: list, set, and remove. ### Get channel memberships List channel memberships for a UUID. This doesn't return subscriptions. #### Method(s) To `Get Memberships` you can use the following method(s) in the Ruby SDK: ```ruby get_memberships( uuid: uuid, sort: sort, include: include, filter: filter, start: start, end: end, limit: limit, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `uuid`Type: StringDefault: Client UUID | Identifier for which memberships in `channels` should be fetched. Default: configured PubNub client `uuid`. | | `sort`Type: ArrayDefault: n/a | List of criteria (name of field) which should be used for sorting in ascending order. Available options are `id`, `name`, and `updated`. Use `asc` or `desc` to specify sort direction. | | `include`Type: ObjectDefault: `{ count: true }` | Additional information which should be included in response. Available options: count - include how many memberships UUID has., custom - include field with additional information from metadata which has been associated with UUID during membership add requests., channel_metadata - include channel's metadata into response (not only name)., channel_custom - include channel's additional information which has been used during channel metadata set requests., status - include the status of the membership., type - include the type of the membership., channel_type - include the type of the channel., channel_status - include the status of the channel. | | `filter`Type: StringDefault: n/a | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [here](https://www.pubnub.com/docs/general/metadata/filtering) | | `start`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: IntegerDefault: 100 | Number of objects to return in response. Default is `100`, which is also the maximum value. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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.get_memberships( uuid: 'mg', include: { count: true, custom: true, channel_metadata: true } ) do |envelope| puts envelope end ``` #### Response ```ruby # { :memberships => [ { :channel => { :id => "channel-identifier1", :name => "Channel1", :description => nil, # {...} }, :custom => { "membership-custom" => "custom-data-1" }, :updated => , :eTag => "AYbepevg39XeDA" }, # {...} ], :totalCount => 2, :next => "MQ", :prev => nil } }, @status = { :code => 200 } > ``` ### Set channel memberships Replace or add memberships for a UUID. Provide channels (optionally with custom data). #### Method(s) To `Set Memberships` you can use the following method(s) in the Ruby SDK: ```ruby set_memberships( uuid: uuid, channels: channels, sort: sort, include: include, filter: filter, start: start, end: end, limit: limit, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `uuid`Type: StringDefault: Client UUID | Identifier for which memberships in `channels` should be set. Default: configured PubNub client `uuid`. | | `channels` *Type: ArrayDefault: n/a | List of `channels` for which `metadata` associated with each of them in context of `UUID` should be set. Each entry is a dictionary with `channel` and optional fields: custom - A dictionary with simple objects: String and Integer., type - Type of the metadata associated with specified membership., status - Status of the metadata associated with specified membership. | | `sort`Type: ArrayDefault: n/a | List of criteria (name of field) which should be used for sorting in ascending order. Available options are `id`, `name`, and `updated`. Use `asc` or `desc` to specify sort direction. | | `include`Type: ObjectDefault: `{ count: true }` | Additional information which should be included in response. Available options: count - include how many memberships UUID has., custom - include field with additional information from metadata which has been associated with UUID during membership add requests., channel_metadata - include channel's metadata into response (not only name)., channel_custom - include channel's additional information which has been used during channel metadata set requests., status - include the status of the membership., type - include the type of the membership., channel_type - include the type of the channel., channel_status - include the status of the channel. | | `filter`Type: StringDefault: n/a | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [here](https://www.pubnub.com/docs/general/metadata/filtering) | | `start`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: IntegerDefault: 100 | Number of objects to return in response. Default is `100`, which is also the maximum value. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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 API limits To learn about the maximum length of parameters used to set channel membership metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-membership-metadata). ::: #### Sample code ```ruby pubnub.set_memberships( uuid: 'mg', channels: [ { channel: 'channel-1' } ], include: { custom: true } ) do |envelope| puts envelope end ``` #### Response ```ruby # { :memberships => [ { :channel => { :id => "channel-1", # {...} }, :custom => nil, :updated => , :eTag => "AY39mJKK//C0VA" } ], :totalCount => 1, :next => "MQ", :prev => nil } }, @status = { :code => 200 } > ``` ### Remove channel memberships Remove memberships for a UUID. Provide the channels to remove. #### Method(s) To `Remove Memberships` you can use the following method(s) in the Ruby SDK: ```ruby remove_memberships( uuid: uuid, channels: channels, sort: sort, include: include, filter: filter, start: start, end: end, limit: limit, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `uuid`Type: StringDefault: Client UUID | Identifier for which memberships in `channels` should be removed. Default: configured PubNub client `uuid`. | | `channels` *Type: ArrayDefault: n/a | List of `channels` from which `UUID` should be removed as `member`. | | `sort`Type: ArrayDefault: n/a | List of criteria (name of field) which should be used for sorting in ascending order. Available options are `id`, `name`, and `updated`. Use `asc` or `desc` to specify sort direction. | | `include`Type: ObjectDefault: `{ count: true }` | Additional information which should be included in response. **Available options:** count - include how many memberships UUID has., custom - include field with additional information from metadata which has been associated with UUID during membership add requests., channel_metadata - include channel's metadata into response (not only name)., channel_custom - include channel's additional information which has been used during channel metadata set requests.. | | `filter`Type: StringDefault: n/a | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [here](https://www.pubnub.com/docs/general/metadata/filtering) | | `start`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: IntegerDefault: 100 | Number of objects to return in response. Default is `100`, which is also the maximum value. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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.remove_memberships( uuid: 'mg', channels: [ 'channel-1' ], include: { custom: true } ) do |envelope| puts envelope end ``` #### Response ```ruby # { :memberships => [ { :channel => { :id => "channel-2", # {...} }, :custom => nil, :updated => , :eTag => "AY39mJKK//C0VA" } ], :totalCount => 1, :next => "MQ", :prev => nil } }, @status = { :code => 200 } > ``` ## Channel members Manage the users in a channel: list, set, and remove. ### Get channel members List users in a channel. Include user metadata if needed. #### Method(s) To `Get Channel Members` you can use the following method(s) in the Ruby SDK: ```ruby get_channel_members( channel: channel, sort: sort, include: include, filter: filter, start: start, end: end, limit: limit, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `channel` *Type: StringDefault: n/a | Name of channel from which members should be fetched. | | `sort`Type: ArrayDefault: n/a | List of criteria (name of field) which should be used for sorting in ascending order. Available options are `id`, `name`, and `updated`. Use `asc` or `desc` to specify sort direction. | | `include`Type: ObjectDefault: `{ count: true }` | Additional information which should be included in response. Available options: count - include how many members channel has., custom - include field with additional information from metadata which has been associated with UUID during channel member add requests., uuid_metadata - include UUID's metadata into response (not only identifier)., uuid_custom - include UUID's additional information which has been used during UUID metadata set requests., status - include the status of the member., type - include the type of the member., uuid_status - include the status of the UUID., uuid_type - include the type of the UUID. | | `filter`Type: StringDefault: n/a | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [here](https://www.pubnub.com/docs/general/metadata/filtering) | | `start`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: IntegerDefault: 100 | Number of objects to return in response. Default is `100`, which is also the maximum value. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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.get_channel_members( channel: 'channel-1', include: { count: true, custom: true, uuid_metadata: true } ) do |envelope| puts envelope end ``` #### Response ```ruby # { :members => [ { :uuid => { :id => "uuid-identifier1", :name => "uuid1", :externalId => nil, :profileUrl => nil, :email => nil, :updated => , :eTag => "AYfwuq+u+4C01gE", # {...} }, :custom => nil, :updated => , :eTag => "AY39mJKK//C0VA" }, # {...} ], :totalCount => 6, :next => "Ng", :prev => nil } }, @status = { :code => 200 } > ``` ### Set channel members Set users in a channel. Provide UUIDs (optionally with custom data). #### Method(s) To `Set Channel Members` you can use the following method(s) in the Ruby SDK: ```ruby set_channel_members( channel: channel, uuids: uuids, sort: sort, include: include, filter: filter, start: start, end: end, limit: limit, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `channel` *Type: StringDefault: n/a | Name of channel for which members should be set. | | `uuids` *Type: ArrayDefault: n/a | List of `UUIDs` for which `metadata` associated with each of them in context of `channel` should be set. Each entry is a dictionary with `UUID` and optional fields: custom - A dictionary with simple objects: String and Integer., type - Type of the metadata associated with specified UUID., status - Status of the metadata associated with specified UUID. | | `sort`Type: ArrayDefault: n/a | List of criteria (name of field) which should be used for sorting in ascending order. Available options are `id`, `name`, and `updated`. Use `asc` or `desc` to specify sort direction. | | `include`Type: ObjectDefault: `{ count: true }` | Additional information which should be included in response. Available options: count - include how many members channel has., custom - include field with additional information from metadata which has been associated with UUID during channel member add requests., uuid_metadata - include UUID's metadata into response (not only identifier)., uuid_custom - include UUID's additional information which has been used during UUID metadata set requests., status - include the status of the member., type - include the type of the member., uuid_status - include the status of the UUID., uuid_type - include the type of the UUID. | | `filter`Type: StringDefault: n/a | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [here](https://www.pubnub.com/docs/general/metadata/filtering) | | `start`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: IntegerDefault: 100 | Number of objects to return in response. Default is `100`, which is also the maximum value. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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 API limits To learn about the maximum length of parameters used to set channel members metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-channel-members-metadata). ::: #### Sample code ```ruby pubnub.set_channel_members( channel: 'channel', uuids: [ { uuid: 'uuid1' } ], include: { custom: true } ) do |envelope| puts envelope end ``` #### Response ```ruby # { :members=>[ { :uuid => { :id => "mg2", # {...} }, :custom => nil, :updated=>, :eTag => "AY39mJKK//C0VA" } ], :totalCount => 1, :next => "MQ", :prev => nil } }, @status = { :code => 200 } > ``` ### Remove channel members Remove users from a channel. Provide the UUIDs to remove. #### Method(s) To `Remove Channel Members` you can use the following method(s) in the Ruby SDK: ```ruby remove_channel_members( channel: channel, uuids: uuids, sort: sort, include: include, filter: filter, start: start, end: end, limit: limit, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `channel` *Type: StringDefault: n/a | Name of channel from which members should be removed. | | `uuids` *Type: ArrayDefault: n/a | List of `UUIDs` which should be removed from `channel's` list. | | `sort`Type: ArrayDefault: n/a | List of criteria (name of field) which should be used for sorting in ascending order. Available options are `id`, `name`, and `updated`. Use `asc` or `desc` to specify sort direction. | | `include`Type: ObjectDefault: `{ count: true }` | Additional information which should be included in response. **Available options:** count - include how many members channel has., custom - include field with additional information from metadata which has been associated with UUID during channel member add requests., uuid_metadata - include UUID's metadata into response (not only identifier)., uuid_custom - include UUID's additional information which has been used during UUID metadata set requests. | | `filter`Type: StringDefault: n/a | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [here](https://www.pubnub.com/docs/general/metadata/filtering) | | `start`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: StringDefault: n/a | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: IntegerDefault: 100 | Number of objects to return in response. Default is `100`, which is also the maximum value. | | `http_sync`Type: BooleanDefault: 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 parameterDefault: n/a | `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.remove_channel_members( channel: 'channel', uuids: [ 'mg1' ], include: { custom: true } ) do |envelope| puts envelope end ``` #### Response ```ruby # { :members=>[ { :uuid => { :id => "uuid-identifier", # {...} }, :custom => nil, :updated => , :eTag => "AY39mJKK//C0VA" } ], :totalCount => 1, :next => "MQ", :prev => nil } }, @status = { :code => 200 } > ``` ## 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. * **Channel pattern** - A way to group and analyze channel data to track performance metrics like message counts and user engagement over time with PubNub Insights. * **User** - An individual or entity that interacts with a system, application, or service. In PubNub, a user typically refers to someone who sends or receives messages through the platform, identified by a unique user ID or username. * **User ID** - UTF-8 encoded, unique string of up to 92 characters used to identify a single client (end user, device, or server) that connects to PubNub.