---
source_url: https://www.pubnub.com/docs/pub-sub/message-actions/overview
title: Message Actions in PubNub
updated_at: 2026-09-30T07:20:08.000Z
---

# Message Actions in PubNub

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

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](https://www.pubnub.com/docs/architecture/core-concepts.md#timetoken), so a message action cannot exist on its own. For the calls that add, remove, and retrieve one, refer to [Add message actions](https://www.pubnub.com/docs/pub-sub/message-actions/add-message-actions.md), [Remove message actions](https://www.pubnub.com/docs/pub-sub/message-actions/remove-message-actions.md), and [Retrieve historical message actions](https://www.pubnub.com/docs/pub-sub/message-actions/retrieve-historical-message-actions.md).

## 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:

```json
{
  "type": "reaction",
  "value": "smiley_face",
  "uuid": "user-456",
  "actionTimetoken": "15610547826970050",
  "messageTimetoken": "15610547826969050"
}
```

`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](https://www.pubnub.com/docs/architecture/core-concepts.md#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](https://www.pubnub.com/docs/architecture/limits.md#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](https://www.pubnub.com/docs/data-storage/message-history/overview.md) enabled on your keyset. PubNub stores each action the way it stores a message. Enable Message Persistence in the [Admin Portal](https://admin.pubnub.com/) before using any message action operation.

If [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) 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](https://www.pubnub.com/docs/pub-sub/subscribe/event-listeners.md) for how handlers are registered, and [Receive message actions](https://www.pubnub.com/docs/pub-sub/message-actions/receive-message-actions.md) 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](https://www.pubnub.com/docs/data-storage/message-history/overview.md) response returns for a stored action. Refer to [Events](https://www.pubnub.com/docs/architecture/events.md#message-action) for the full event model.

That event follows the same [at-most-once](https://www.pubnub.com/docs/pub-sub/overview.md#at-most-once-live-delivery) 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](https://www.pubnub.com/docs/pub-sub/message-actions/retrieve-historical-message-actions.md) 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](https://www.pubnub.com/docs/pub-sub/publish/overview.md#publish-metadata) 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](https://www.pubnub.com/docs/security/access-control/overview.md).

## Next steps

* [Add message actions](https://www.pubnub.com/docs/pub-sub/message-actions/add-message-actions.md). Attach a reaction, a receipt, or a custom annotation to a message.
* [Receive message actions](https://www.pubnub.com/docs/pub-sub/message-actions/receive-message-actions.md). Handle the Message Action event on a live subscription.
* [Retrieve historical message actions](https://www.pubnub.com/docs/pub-sub/message-actions/retrieve-historical-message-actions.md). Fetch actions for a channel or catch up after being offline.
* [Remove message actions](https://www.pubnub.com/docs/pub-sub/message-actions/remove-message-actions.md). Delete a previously added action.
* [Pub/Sub overview](https://www.pubnub.com/docs/pub-sub/overview.md). The publish/subscribe model that message actions extend.
* [Message Persistence](https://www.pubnub.com/docs/data-storage/message-history/overview.md). The storage layer message actions depend on.

Last updated at: 2026-09-30T07:20:08.000Z