---
source_url: https://www.pubnub.com/docs/sdks/asyncio/api-reference/message-actions
title: Message Actions API for Python-Asyncio SDK
updated_at: 2026-05-25T11:27:12.539Z
sdk_name: PubNub Python Asyncio SDK
---

> 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 Python-Asyncio SDK

PubNub Python Asyncio SDK

Install:

```bash
pip install pubnub
```

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.

:::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 Python-Asyncio method:

```python
pubnub.add_message_action() \
  .channel(String) \
  .message_action(PNMessageAction) \
  .pn_async(Function message_action_callback)
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| channel | String | Yes |  | Channel name to add the message action to. |
| message_action | PNMessageAction | Yes |  | Message action payload. |
| message_action.type | String | Yes |  | Message action type (for example, reaction). |
| message_action.value | String | Yes |  | Message action value (for example, emoji name). |
| message_action.message_timetoken | Integer | Yes |  | Timetoken of the target message. |
| message_action_callback | Function | Yes |  | Callback for success or error. Details in [PNMessageAction callback](#pnmessageaction-callback). |

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

```python
import asyncio
import os
import time
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub_asyncio import PubNubAsyncio
from pubnub.exceptions import PubNubException
from pubnub.models.consumer.pubsub import PNMessageAction

async def add_message_action(pubnub: PubNubAsyncio):
    try:
        # Create a message action
        msg_action = PNMessageAction()
        msg_action.type = "reaction"
        msg_action.value = "smiley_face"
        msg_action.message_timetoken = str(int(time.time()))

        # Add message action
        envelope = await pubnub.add_message_action() \
            .channel("chats.room1") \
            .message_action(msg_action) \
            .future()

        if envelope.status.is_error():
            print("Error adding message action")
        else:
            print(f"Added action at timetoken: {envelope.result.action_timetoken}")

    except PubNubException as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    loop = asyncio.new_event_loop()
    asyncio.set_event_loop(loop)

    # Configuration for PubNub instance
    pn_config = PNConfiguration()
    pn_config.subscribe_key = os.getenv('SUBSCRIBE_KEY', 'demo')
    pn_config.publish_key = os.getenv('PUBLISH_KEY', 'demo')
    pn_config.user_id = "my_custom_user_id"

    pubnub = PubNubAsyncio(pn_config)

    try:
        loop.run_until_complete(add_message_action(pubnub))
    finally:
        loop.run_until_complete(pubnub.stop())
        loop.close()
```

### Returns

```python
# Example of status
{
  'affected_channels': None,
  'affected_channels_groups': None,
  'affected_groups': None,
  'auth_key': None,
  'category': 2,
  'client_response': None,
  'error': None,
  'error_data': None,
  'operation': 42,
  'origin': 'ps.pndsn.com',
  'status_code': 200,
  'tls_enabled': True,
  'uuid': 'my_uuid'
}

# Example of envelope
{
  'action_timetoken': '15956343330507960',
  'message_timetoken': '1595634332',
  'type': 'reaction',
  'uuid': 'my_uuid',
  'value': 'smiley_face'
}
```

## 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 Python-Asyncio method:

```python
pubnub.remove_message_action() \
  .channel(String) \
  .action_timetoken(Integer) \
  .message_timetoken(Integer) \
  .pn_async(message_action_callback)
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: String | Channel name to remove the message action from. |
| `action_timetoken` *Type: Integer | Timetoken of the message action to remove. |
| `message_timetoken` *Type: Integer | Timetoken of the message that contains the action. |
| `message_action_callback` *Type: Function | Callback for success or error. Details in [PNMessageAction callback](#pnmessageaction-callback). |

### Sample code

```python
pubnub.remove_message_action()\
  .channel("chats.room1")\
  .action_timetoken(15956346328442840)\
  .message_timetoken(1595634632)\
  .pn_async(message_action_callback)
```

### Returns

```python
# Example of status
{
  'affected_channels': None,
  'affected_channels_groups': None,
  'affected_groups': None,
  'auth_key': None,
  'category': 2,
  'client_response': None,
  'error': None,
  'error_data': None,
  'operation': 44,
  'origin': 'ps.pndsn.com',
  'status_code': 200,
  'tls_enabled': True,
  'uuid': 'my_uuid'
}

# Example of envelope in case of success (empty object)
{}
```

## 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 message actions in a channel. Results are sorted by action timetoken in ascending order.

### Method(s)

Use this Python-Asyncio method:

```python
pubnub.get_message_actions() \
  .channel(String) \
  .start(String) \
  .end(String) \
  .limit(Integer) \
  .pn_async(message_action_callback)
```

| 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). Must be ≤ `start` when `start` is provided. |
| `limit`Type: Integer | Maximum number of actions to return. If exceeded, results include a `more` token. See the [REST API documentation](https://www.pubnub.com/docs/sdks/rest-api/get-actions). |
| `message_action_callback` *Type: Function | Callback for success or error. Details in [PNMessageAction callback](#pnmessageaction-callback). |

### Sample code

```python
# Retrieve all actions on a single message

pubnub.get_message_actions()\
  .channel("chats.room1")\
  .start("15956342921084731")\
  .end("15956342921084730")\
  .limit(50)\
  .pn_async(message_action_callback)
```

### Returns

```python
# Example of status
{
  'affected_channels': None,
  'affected_channels_groups': None,
  'affected_groups': None,
  'auth_key': None,
  'category': 2,
  'client_response': None,
  'error': None,
  'error_data': None,
  'operation': 43,
  'origin': 'ps.pndsn.com',
  'status_code': 200,
  'tls_enabled': True,
  'uuid': 'my_uuid'
}

# Example of envelope
{
  'actions': [
    {
      'actionTimetoken': '15956373593404068',
      'messageTimetoken': '15956342921084730',
      'type': 'reaction',
      'uuid': 'my_uuid',
      'value': 'smiley_face'
    }
  ]
}
```

## PNMessageAction callback

`PNMessageAction` is structured as follows:

```python
action = PNMessageAction({
        'uuid': 'user1',
        'type': 'reaction',
        'value': 'smiley_face',
        'actionTimetoken': '15901706735798836',
        'messageTimetoken': '15901706735795200',
    })
```

Use the following method as a starting point for your own implementation:

```python
def message_action_callback(envelope, status):
    if status.is_error():
        print("Uh oh. We had a problem sending the message. :( \n %s" % status)
    else:
        if isinstance(envelope, PNAddMessageActionResult):
            print("Message Action type: %s" % envelope.type)
            print("Message Action value: %s" % envelope.value)
            print("Message Action timetoken: %s" % envelope.message_timetoken)
            print("Message Action uuid: %s" % envelope.uuid)
            print("Message Action timetoken: %s" % envelope.action_timetoken)
        elif isinstance(envelope, PNRemoveMessageActionResult):
            # Envelope here is an empty dictionary {}
            pass
        elif isinstance(envelope, PNGetMessageActionsResult):
            print("Message Actions Result:\n")
            for action in envelope.actions:
                print("Message Action type: %s" % action.type)
                print("Message Action value: %s" % action.value)
                print("Message Action timetoken: %s" % action.message_timetoken)
                print("Message Action uuid: %s" % action.uuid)
                print("Message Action timetoken: %s" % action.action_timetoken)
                print("")
```

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