Message Actions API for Python 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.

Request execution and return values

You can decide whether to perform the Python SDK operations synchronously or asynchronously.

• .sync() returns an Envelope object, which has two fields: Envelope.result, whose type differs for each API, and Envelope.status of type PnStatus.

  pubnub.publish() \
      .channel("myChannel") \
      .message("Hello from PubNub Python SDK") \
      .sync()

• .pn_async(callback) returns None and passes the values of Envelope.result and Envelope.status to a callback you must define beforehand.

  def my_callback_function(result, status):
      print(f'TT: {result.timetoken}, status: {status.category.name}')
  
  pubnub.publish() \
      .channel("myChannel") \
      .message("Hello from PubNub Python SDK") \
      .pn_async(my_callback_function)

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

This method requires that Message Persistence is enabled for your key in the Admin Portal.

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

Method(s)

Use this Python 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.
message_action.value * Type: String	Message action value.
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.

Builder Pattern

import os
import time
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub
from pubnub.models.consumer.message_actions import PNMessageAction


def add_message_action(pubnub: PubNub):
    msg_action = PNMessageAction()
    msg_action.type = "reaction"
    msg_action.value = "smiley_face"
    msg_action.message_timetoken = str(int(time.time()))

    result = pubnub.add_message_action() \
        .channel("chats.room1") \

show all 42 lines

Named Arguments

import os
import time
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub
from pubnub.models.consumer.message_actions import PNMessageAction


def add_message_action(pubnub: PubNub):
    msg_action = PNMessageAction()
    msg_action.type = "reaction"
    msg_action.value = "smiley_face"
    msg_action.message_timetoken = str(int(time.time()))

    result = pubnub.add_message_action(
        channel="chats.room1",

show all 42 lines

Returns

The add_message_action() operation returns an Envelope with the following fields:

Field	Type	Description
result	PNAddMessageActionResult	Operation result.
status	PNStatus	Operation status.

PNAddMessageActionResult

{
  'action_timetoken': '15956343330507960',
  'message_timetoken': '1595634332',
  'type': 'reaction',
  'uuid': 'my_uuid',
  'value': 'smiley_face'
}

Remove message action

Requires Message Persistence

This method requires that Message Persistence is enabled for your key in the Admin Portal.

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

Method(s)

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

Sample code

Builder Pattern

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

Named Arguments

from pubnub.models.consumer.message_actions import PNMessageAction

msg_action = PNMessageAction()
msg_action.type = "reaction"
msg_action.value = "smiley_face"
msg_action.message_timetoken = str(int(time.time()))

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

Returns

The remove_message_action() operation returns an Envelope with the following fields:

Field	Type	Description
result	PNRemoveMessageActionResult	Operation result.
status	PNStatus	Operation status.

PNRemoveMessageActionResult

# in case of success (empty object)
{}

Get message actions

Requires Message Persistence

This method requires that Message Persistence is enabled for your key in the Admin Portal.

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

Method(s)

Use this Python 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).
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

Builder Pattern

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

Named Arguments

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

Returns

The get_message_actions operation returns an Envelope with the following fields:

Field	Type	Description
result	PNGetMessageActionsResult	Operation result.
status	PNStatus	Operation status.

PNGetMessageActionsResult

{
  'actions': [
    {
      'actionTimetoken': '15956373593404068',
      'messageTimetoken': '15956342921084730',
      'type': 'reaction',
      'uuid': 'my_uuid',
      'value': 'smiley_face'
    }
  ]
}

PNMessageAction

The structure of a PNMessageAction is as follows:

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

The following is a sample message_action_callback method you can use as a starting point for your own implementation:

def message_action_callback(envelope, status):
    if status.is_error():
        print(f"Uh oh. We had a problem sending the message. :( \n {status}")
        return
    if isinstance(envelope, PNAddMessageActionResult):
        print(f"Message Action type: {envelope.type}")
        print(f"Message Action value: {envelope.value}")
        print(f"Message Action timetoken: {envelope.message_timetoken}")
        print(f"Message Action uuid: {envelope.uuid}")
        print(f"Message Action timetoken: {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