Message Actions API for Python-Asyncio SDK

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.

Reactions

"Message Reactions" is a specific application of the Message Actions API for emoji or social reactions.

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 and Chat 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

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in the support article.

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

Method(s)

Use this Python-Asyncio method:

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

* required

Parameter	Description
channel * Type: String	Channel name to add the message action to.
message_action * Type: PNMessageAction	Message action payload.
message_action.type * Type: String	Message action type (for example, reaction).
message_action.value * Type: String	Message action value (for example, emoji name).
message_action.message_timetoken * Type: Integer	Timetoken of the target message.
message_action_callback * Type: Function	Callback for success or error. Details in PNMessageAction callback.

Sample code

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.

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"

show all 49 lines

Returns

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

show all 25 lines

Remove message action

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in the support article.

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

Method(s)

Use this Python-Asyncio method:

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

* required

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.

Sample code

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

Returns

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

show all 19 lines

Get message actions

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in the support article.

Get message actions in a channel. Results are sorted by action timetoken in ascending order.

Method(s)

Use this Python-Asyncio method:

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

* required

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.
message_action_callback * Type: Function	Callback for success or error. Details in PNMessageAction callback.

Sample code

# 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

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

show all 29 lines

PNMessageAction callback

PNMessageAction is structured as follows:

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:

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")

show all 22 lines