Message Actions in PubNub

A message action is a piece of user-defined metadata (such as an emoji reaction or a read receipt) that you attach to a message after it has been published. This page explains:

• what an action's type and value carry, and how an action references the message it annotates
• how an added or removed action reaches a subscriber as its own event
• the Message Persistence requirement that applies to every message action operation

One rule holds throughout: an action always references an existing message by that message's timetoken, so a message action cannot exist on its own. For the calls that add, remove, and retrieve one, refer to Add message actions, Remove message actions, and Retrieve historical message actions.

What an action carries

A message action has two string fields, type and value. PubNub stores both without interpreting them, so you define the vocabulary. A read receipt might use type: "receipt" and value: "read". An emoji reaction might use type: "reaction" and value: "smiley_face". Because you choose the strings, a message action can also cover other annotations, such as an edit marker or a moderation flag, not only receipts and reactions.

Adding an action returns the action PubNub stored:

1{
2  "type": "reaction",
3  "value": "smiley_face",
4  "uuid": "user-456",
5  "actionTimetoken": "15610547826970050",
6  "messageTimetoken": "15610547826969050"
7}

messageTimetoken identifies the message the action annotates, and actionTimetoken is the timetoken PubNub assigned to the action itself when it was added. uuid is the User ID of the client that added the action. Parameter names for the two timetokens vary by SDK, for example messageTimetoken in JavaScript and message_timetoken in Python.

You can add an action to any message, including one published long before your app came online; nothing requires the target message to be recent.

If your reactions use emoji, bring your own emoji library. PubNub SDKs do not include one, since value is a plain string you supply.

Item	Limit	Notes
Request size	Same limit as Publish.	A message action is sent as a standard PubNub API request, so the publish request-body limit applies.
type and value fields	No dedicated limit	Bounded only by the overall request size.

Prerequisites

All message action operations require Message Persistence enabled on your keyset. PubNub stores each action the way it stores a message. Enable Message Persistence in the Admin Portal before using any message action operation.

If Access Manager is enabled, each operation also needs a specific channel permission:

Operation	PAM permission required
Add a message action	write
Remove a message action	delete
Retrieve message actions	read

PubNub won't add an action without Message Persistence enabled. So if a keyset never produces a live Message Action event, check this setting first.

How an action reaches a subscriber

Adding or removing a message action generates a Message Action event, the same way publishing a message generates a message event. A subscribed client receives it through a dedicated handler, separate from the handler for ordinary messages. SDKs that name handlers this way call it onMessageAction. Refer to Event listeners for how handlers are registered, and Receive message actions for the per-language calls.

A Message Action event carries two timetokens instead of one, data.messageTimetoken and data.actionTimetoken, because it always refers back to a message published earlier. The event payload also names whether the action was added or removed, so one handler covers both operations. Internally, PubNub tags the event with message type 3, the same value a Message Persistence response returns for a stored action. Refer to Events for the full event model.

That event follows the same at-most-once rule as any other event. Only a client subscribed to the channel at the moment the action is added or removed receives it live. Because the action itself is stored, a client that misses the live event can still catch up. Retrieve historical message actions fetches actions for a channel within a timetoken range, sorted oldest first.

No second channel needed

An action attaches to a message that is already published, so a reaction or a receipt needs no channel of its own and no republish of the original message. The original message keeps its content, its timetoken, and its position in the channel's order. Only the annotation is new. That is also why removing an action returns an empty response: there is nothing to roll back on the message itself, only the action record to delete.

Limitations

• No editing of the original message. An action adds metadata alongside a message; it never changes the payload. To change what was said, publish a new message.
• No default actions. There is no way to attach an action at publish time. If you need to send data alongside a message at the moment it is sent, use the meta parameter instead.
• No permission beyond the channel's Access Manager rules. Adding a message action requires the write permission on the channel. Removing one requires delete, and retrieving one requires read. These are the same channel-scoped permissions that gate publishing and reading history. Refer to Access Manager.

Next steps

• Add message actions. Attach a reaction, a receipt, or a custom annotation to a message.
• Receive message actions. Handle the Message Action event on a live subscription.
• Retrieve historical message actions. Fetch actions for a channel or catch up after being offline.
• Remove message actions. Delete a previously added action.
• Pub/Sub overview. The publish/subscribe model that message actions extend.
• Message Persistence. The storage layer message actions depend on.