Message Actions API for Dart 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 Enable the features your app calls.

This method adds a message action to a parent message. A parent message is identified by subscribeKey, channel, and timetoken. The response includes the added action.

Parent message existence

The server doesn't validate if the parent message exists when adding a message action. It does check whether the same action already exists on the parent message. Only one message action with a given type and value can exist for a parent message.

Method(s)

Use this Dart method:

1pubnub.addMessageAction(
2  {String type,
3  String value,
4  String channel,
5  Timetoken timetoken,
6  Keyset? keyset,
7  String? using}
8) 

* required

Parameter	Description
type * Type: String	Message action type.
value * Type: String	Message action value.
channel * Type: String	Channel name to add the message action to.
timetoken * Type: Timetoken	Timetoken of the target message.
keyset Type: Keyset	Override for the default keyset configuration.
using Type: String	Keyset name from the keysetStore to use for this call.

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.

1import 'package:pubnub/pubnub.dart';
2

3void main() async {
4  // Create PubNub instance with default keyset.
5  var pubnub = PubNub(
6    defaultKeyset: Keyset(
7      subscribeKey: 'demo',
8      publishKey: 'demo',
9      userId: UserId('myUniqueUserId'),
10    ),
11  );
12

13  // Channel and message details
14  String channel = 'my_channel';
15  Timetoken messageTimetoken = Timetoken(BigInt.from(15610547826969050));
16

17  // Add a message action
18  var result = await pubnub.addMessageAction(
19    type: 'reaction',
20    value: 'smiley',
21    channel: channel,
22    timetoken: messageTimetoken,
23  );
24

25  // Print the added message action details
26  print('Added message action: ${result.action}');
27}

show all 27 lines

Returns

The addMessageAction() operation returns an AddMessageActionResult with the following property:

Property Name	Type	Description
action	MessageAction	Added message action.

The MessageAction object contains the following properties:

Property Name	Type	Description
type	String	Message action type.
value	String	Message action value.
actionTimetoken	String	Timetoken assigned to the added message action.
messageTimetoken	String	Timetoken of the target message.
uuid	String	UUID of the sender.

Remove message action

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in Enable the features your app calls.

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

Method(s)

Use this Dart method:

1pubnub.deleteMessageAction(String channel,
2      {Timetoken messageTimetoken,
3      Timetoken actionTimetoken,
4      Keyset? keyset,
5      String? using})

* required

Parameter	Description
channel * Type: String	Channel the message was sent to.
messageTimetoken * Type: Timetoken	Timetoken of the target message.
actionTimetoken * Type: Timetoken	Timetoken of the message action to remove.
keyset Type: Keyset	Override for the default keyset configuration.
using Type: String	Keyset name from the keysetStore to use for this call.

Sample code

1  var result = await pubnub.deleteMessageAction(
2      'my_channel', Timetoken(15610547826969050), Timetoken(15610547826969159));

Returns

The deleteMessageAction() operation returns a DeleteMessageActionResult without actionable data.

Get message actions

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in Enable the features your app calls.

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

How to use the start and end parameters

PubNub retrieves messages by searching backward through time (newest to oldest). Because of this, the parameter names are the reverse of their intuitive meaning:

• start is the newer boundary (higher timetoken value) - search begins here, exclusive
• end is the older boundary (lower timetoken value) - search stops here, inclusive

When you provide both parameters, start must be a higher timetoken than end.

9:00 AM10:00 AM11:00 AM11:59 AM

Results are always returned in oldest-first order.

Method(s)

Use this Dart method:

1pubnub.fetchMessageActions(
2  String channel,
3  {Timetoken? from,
4  Timetoken? to,
5  int? limit,
6  Keyset? keyset,
7  String? using})

* required

Parameter	Description
channel * Type: String Default: n/a	Channel name to list message actions for.
from Type: Timetoken Default: n/a	Message action timetoken for the start of the range (exclusive).
to Type: Timetoken Default: n/a	Message action timetoken for the end of the range (inclusive).
limit Type: int Default: 100	Maximum number of actions to return. Default/Maximum is 100.
keyset Type: Keyset Default: n/a	Override for the default keyset configuration.
using Type: String Default: n/a	Keyset name from the keysetStore to use for this call.

Sample code

1  var result = await pubnub.fetchMessageActions('my_channel');

Response

1{
2  "status": 200,
3  "data": [
4    {
5      "type": "reaction",
6      "value": "smiley_face",
7      "actionTimetoken": "15610547826970050",
8      "messageTimetoken": "15610547826969050",
9      "uuid": "terryterry69420"
10    }
11  ],
12  "more": {
13    "url": "/v1/actions/sub-c-6ba5f838-6456-11e8-9307-eaaa55e2558c/channel/my_channel?start=15610547826970050&end=15645905639093361&limit=2",
14    "start": "15610547826970050",
15    "end": "15645905639093361",
16    "limit": 2
17  }
18}

show all 18 lines

Returns

The fetchMessageActions() operation returns a list of FetchMessageActionsResult objects containing the following properties:

Property Name	Type	Description
actions	List<MessageAction>	List of message actions.
moreActions	MoreAction	Pagination information.

The MessageAction has the following properties:

Property Name	Type	Description
type	String	Message action type.
value	String	Message action value.
actionTimetoken	String	Timetoken assigned to the added message action.
messageTimetoken	String	Timetoken of the target message.
uuid	String	UUID of the sender.

The MoreAction has the following properties:

Property Name	Type	Description
url	String	URL to fetch the next page of message actions.
start	String	Start timetoken for the next page.
limit	int	Limit for the next page.

Other examples

Fetch message actions with paging

1// this loop continues fetching message actions when the next batch is available
2var fetchMessageActionsResult = FetchMessageActionsResult(<MessageAction>[]);
3var loopResult, from, to, limit;
4do {
5  loopResult = await pubnub.fetchMessageActions('my_channel',
6      from: from, to: to, limit: limit);
7

8  fetchMessageActionsResult.actions.addAll(loopResult.actions);
9

10  if (loopResult.moreActions != null) {
11    var more = loopResult.moreActions;
12    from = Timetoken(BigInt.parse(more.start));
13    to = Timetoken(BigInt.parse(more.end));
14    limit = more.limit;
15  }
16} while (loopResult.moreActions != null);
17// now `fetchMessageActionsResult` contains all message actions

show all 17 lines