---
source_url: https://www.pubnub.com/docs/sdks/javascript/api-reference/message-actions
title: Message Actions API for JavaScript SDK
updated_at: 2026-05-25T11:28:05.357Z
sdk_name: PubNub JavaScript SDK
sdk_version: 11.0.1
---

> 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 JavaScript SDK

PubNub JavaScript SDK, use the latest version: 11.0.1

Install:

```bash
npm install pubnub@11.0.1
```

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, either on demand or when fetching original messages.

:::note Supported and recommended asynchronous patterns
PubNub supports [Callbacks, Promises, and Async/Await](https://javascript.info/async) for asynchronous JS operations. The recommended pattern is Async/Await and all sample requests in this document are based on it. This pattern returns a status only on detecting an error. To receive the error status, you must add the [try...catch](https://javascript.info/try-catch) syntax to your code.
:::

:::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
Enable Message Persistence for your key in the [Admin Portal](https://admin.pubnub.com/) as described in the [support article](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-).
:::

Add an action to a published message. The response includes the added action.

### Method(s)

Use this JavaScript method:

```javascript
addMessageAction({
    channel: string,
    messageTimetoken: string,
    action: {type: string, value: string}
})
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| channel | string | Yes |  | Channel name of the target message. |
| messageTimetoken | string | Yes |  | Timetoken of the target message. |
| action | Hash | Yes |  | Message action payload. |
| action.type | string | Yes |  | Message action type. |
| action.value | string | Yes |  | Message action value. |

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

```javascript
import PubNub from 'pubnub';
// Initialize PubNub with your keys
const pubnub = new PubNub({
  publishKey: 'YOUR_PUBLISH_KEY',
  subscribeKey: 'YOUR_SUBSCRIBE_KEY',
  userId: 'YOUR_USER_ID',
});
```

```javascript
// first publish a message using publish() method to get the message timetoken
try {
  const response = await pubnub.addMessageAction({
    channel: 'channel_name',
    messageTimetoken: 'replace_with_message_timetoken', // Replace with actual message timetoken
    action: {
      type: 'reaction',
      value: 'smiley_face',
    },
  });
  console.log('Message reaction added successfully:', response);
} catch (error) {
  console.error(
    `Error adding reaction: ${error}.${
      (error as PubNubError).status ? ` Additional information: ${(error as PubNubError).status}` : ''
    }`,
  );
}
```

### Returns

```json
// Example of status
{
    "error": false,
    "operation": "PNAddMessageActionOperation",
    "statusCode": 200
}

// Example of response
{
    "data": {
        "type": "reaction",
        "value": "smiley_face",
        "uuid": "user-456",
        "actionTimetoken": "15610547826970050",
        "messageTimetoken": "15610547826969050"
    }
}
```

## Remove message action

:::warning Requires Message Persistence
Enable Message Persistence for your key in the [Admin Portal](https://admin.pubnub.com/) as described in the [support article](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-).
:::

Remove a previously added action from a published message. The response is empty.

### Method(s)

Use this JavaScript method:

```javascript
removeMessageAction({
    channel: string,
    messageTimetoken: string,
    actionTimetoken: string
})
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: string | Channel name of the target message. |
| `messageTimetoken` *Type: string | Timetoken of the target message. |
| `actionTimetoken` *Type: string | Timetoken of the message action to remove. |

### Sample code

```javascript
try {
  const response = await pubnub.removeMessageAction({
    channel: 'channel_name',
    messageTimetoken: 'replace_with_message_timetoken',
    actionTimetoken: 'replace_with_action_timetoken',
  });
  console.log('Message action removed successfully:', response);
} catch (error) {
  console.error(
    `Error removing message action: ${error}.${
      (error as PubNubError).status ? ` Additional information: ${(error as PubNubError).status}` : ''
    }`,
  );
}
```

### Returns

```json
// Example of status
{
    "error": false,
    "operation": "PNRemoveMessageActionOperation",
    "statusCode": 200
}

// Example of response
{
    "data": {}
}
```

## Get message actions

:::warning Requires Message Persistence
Enable Message Persistence for your key in the [Admin Portal](https://admin.pubnub.com/) as described in the [support article](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-).
:::

Get a list of message actions in a channel. The response sorts actions by the action timetoken in ascending order.

:::note Truncated response
The number of message actions in the response may be truncated when internal limits are hit. If the response is truncated, a `more` property is returned with additional parameters. Send iterative calls to Message Persistence, adjusting the parameters to fetch more message actions.
:::

### Method(s)

Use this JavaScript method:

```javascript
getMessageActions({
    channel: string,
    start: string,
    end: string,
    limit: number
})
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: string | Channel name to list message actions for. |
| `start`Type: string | Message action timetoken for the start of the range (exclusive). |
| `end`Type: string | Message action timetoken for the end of the range (inclusive). |
| `limit`Type: number | Number of message actions to return. |

### Sample code

```javascript
// to get some data in response, first publish a message and then add a message action
// using addMessageAction() method.
try {
  const response = await pubnub.getMessageActions({
    channel: 'channel_name',
    start: 'replace_with_start_timetoken',
    end: 'replace_with_end_timetoken',
    limit: 100,
  });
  console.log('Message actions retrieved successfully:', response);
} catch (error) {
  console.error(
    `Error retrieving message actions: ${error}.${
      (error as PubNubError).status ? ` Additional information: ${(error as PubNubError).status}` : ''
    }`,
  );
}
```

### Returns

```json
// Example of status
{
    "error": false,
    "operation": "PNGetMessageActionsOperation",
    "statusCode": 200
}

// Example of response
{
    "data": [
        {
            "type": "reaction",
            "value": "smiley_face",
            "uuid": "user-456",
            "actionTimetoken": "15610547826970050",
            "messageTimetoken": "15610547826969050"
        }
    ],
    "start": "15646822873784630",
    "end": "15645905639093361",
}
```

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