--- source_url: https://www.pubnub.com/docs/sdks/ruby/api-reference/message-actions title: Message Actions API for Ruby SDK updated_at: 2026-06-12T11:26:40.071Z 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 Actions API for Ruby SDK PubNub Ruby SDK, use the latest version: 6.0.2 Install: ```bash gem install pubnub@6.0.2 ``` Use message actions to add or remove metadata on published messages. Common uses include receipts and reactions. Clients subscribe to a channel to receive message action events. Clients can also fetch past message actions from Message Persistence independently or when they fetch original messages. :::tip Reactions "Message Reactions" is a specific application of the Message Actions API for emoji or social reactions. ::: :::note Message Actions vs. Message Reactions **Message Actions** is the flexible, low-level API for adding any metadata to messages (read receipts, delivery confirmations, custom data), while **Message Reactions** specifically refers to using Message Actions for emoji/social reactions. In PubNub [Core](https://www.pubnub.com/docs/sdks) and [Chat](https://www.pubnub.com/docs/chat/overview) SDKs, the same underlying Message Actions API is referred to as **Message Reactions** when used for emoji reactions - it's the same functionality, just different terminology depending on the use case. ::: ## Add message action :::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/). ::: Add an action to a published message. The response includes the added action. ### Method(s) Use this Ruby method: ```ruby add_message_action( channel: channel, type: type, value: value, message_timetoken: message_timetoken, http_sync: http_sync, callback: callback ) ``` | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | channel | String | Yes | | Channel name to add the message action to. | | type | String | Yes | | Message action type (max `15` characters). | | value | String | Yes | | Message action value. | | message_timetoken | Integer | Yes | | Timetoken of the target message. | | http_sync | Boolean | Optional | `false` | When `true`, executes synchronously and returns an array of envelopes. | | callback | Lambda | Optional | | Callback invoked for each envelope (for async calls, use `value` to retrieve the envelope). | ### 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 add_message_action(pubnub) puts "Adding message action..." pubnub.add_message_action( channel: 'chat', type: 'emotion', value: 'smile', message_timetoken: 16701562382648731 ) do |envelope| if envelope.status[:error] puts "Error adding message action: #{envelope.status[:data]}" else puts "Message action added successfully:" puts "Type: #{envelope.result[:data][:type]}" puts "Value: #{envelope.result[:data][:value]}" puts "UUID: #{envelope.result[:data][:uuid]}" puts "Action Timetoken: #{envelope.result[:data][:action_timetoken]}" puts "Message Timetoken: #{envelope.result[:data][:message_timetoken]}" end end sleep 1 # Allow time for the async operation to complete end def main # Configuration for PubNub instance pubnub = Pubnub.new( subscribe_key: ENV.fetch('SUBSCRIBE_KEY', 'demo'), user_id: 'myUniqueUserId' ) # Add message action add_message_action(pubnub) end if __FILE__ == $0 main puts "Done." end ``` ### Response ```ruby # { :type => "emotion", :value => "smile", :uuid => "sender-uuid", :action_timetoken => 16701656660127890, :message_timetoken => 16701562382648731 } }, @status = { :code => 200 } > ``` ## Remove message action :::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/). ::: Remove a previously added action from a published message. The response is empty. ### Method(s) Use this Ruby method: ```ruby remove_message_action( channel: channel, message_timetoken: message_timetoken, action_timetoken: action_timetoken, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `channel` *Type: StringDefault: n/a | Channel name to remove the message action from. | | `message_timetoken` *Type: IntegerDefault: n/a | Timetoken of the target message. | | `action_timetoken` *Type: IntegerDefault: n/a | Timetoken of the message action to remove. | | `http_sync`Type: BooleanDefault: false | When `true`, executes synchronously and returns an array of envelopes. | | `callback`Type: Lambda accepting one parameterDefault: n/a | Callback invoked for each envelope (for async calls, use `value` to retrieve the envelope). | ### Sample code ```ruby pubnub.add_message_action( channel: 'chat', message_timetoken: 16701562382648731, action_timetoken: 16701656660127890 ) do |envelope| puts envelope end ``` ### Response ```ruby # 200, :category => :ack, :error => false, } > ``` ## Get message actions :::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/). ::: Get a list of message actions in a channel. The response sorts actions by the action timetoken in ascending order. ### Method(s) Use this Ruby method: ```ruby get_message_actions( channel: channel, start: start, end: end, limit: limit, http_sync: http_sync, callback: callback ) ``` | Parameter | Description | | --- | --- | | `channel` *Type: StringDefault: n/a | Channel name to list message actions for. | | `start`Type: IntegerDefault: n/a | Message action timetoken for the start of the range (exclusive). | | `end`Type: IntegerDefault: n/a | Message action timetoken for the end of the range (inclusive). | | `limit`Type: IntegerDefault: n/a | Number of message actions to return. | | `http_sync`Type: BooleanDefault: false | When `true`, executes synchronously and returns an array of envelopes. | | `callback`Type: Lambda accepting one parameterDefault: n/a | Callback invoked for each envelope (for async calls, use `value` to retrieve the envelope). | ### Sample code ```ruby pubnub.get_message_actions( channel: 'chat', start: 16701562382648731, end: 16701562382348728 ) do |envelope| puts envelope end ``` ### Response ```ruby # { :message_actions => [ { :type => "emotion_type_2", :uuid => "sender-uuid-1", :value => "surprised", :message_timetoken => 16703307481706612, :action_timetoken => 16703307649086202, }, { :type => "emotion_type_3", :uuid => "sender-uuid-2", :value => "lol", :message_timetoken => 16703307492166434, :action_timetoken => 16703307659619240, }, { :type => "emotion_type_1", :uuid => "sender-uuid-1", :value => "tada", :message_timetoken => 16703307461212395, :action_timetoken => 16703307702035502, } ], :more => { :start => 16703307481706612, :end => 16703307481706612, :limit => 3 } } }, @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.