Receive message actions

Showing JavaScript examples.

This guide shows you how to handle the Message Action event PubNub delivers when someone adds or removes a message action on a channel you're subscribed to.

• Register the dedicated handler for this event on an existing subscription.
• Tell an added action from a removed one, and read the type, value, and timetokens it carries.
• Recognize when the handler won't fire, and where to go to catch up.

This page covers only the handler specific to message actions and assumes you already have a subscription. For creating one and registering handlers in general, refer to Receive messages. Examples use the JavaScript, Java, Kotlin, C#, and Python SDKs, which have entity-based subscriptions. If yours doesn't, skip to Register the handler without entities.

Register the handler

Register the handler on your subscription the same way you would for any other event type.

• JavaScript
• Java
• Kotlin
• C#
• Python

1subscription.onMessageAction = (event) => {
2  console.log(`${event.event}: ${event.data.type} = ${event.data.value}`);
3};

Registering this handler doesn't start anything by itself. Nothing arrives until subscribe() runs on this subscription, the same as for any other handler. Refer to A listener is a callback, not a connection.

Read the event payload

The event carries two timetokens instead of one, because it always refers back to a message published earlier:

Field	Description
channel	Channel the message action was added to or removed from
publisher	User ID that added or removed the action
event	added or removed
data.type	The action's type
data.value	The action's value
data.messageTimetoken	Timetoken of the message the action refers to
data.actionTimetoken	Timetoken of the action itself

This table matches the field names JavaScript uses. Other SDKs expose the same fields through their own accessors. Check your language's Message Actions API reference for the exact getter or property name. For the complete client-side event model, refer to Message Action.

Tell an add from a removal

Branch on the event field to handle an added action differently from a removed one, for example to increment or decrement a reaction count in your UI:

1subscription.onMessageAction = (event) => {
2  if (event.event === 'added') {
3    // Show the new reaction or receipt
4  } else if (event.event === 'removed') {
5    // Take the reaction or receipt back off the message
6  }
7};

Register the handler without entities

SDKs that predate entities register every listener on the PubNub client object instead of on a subscription.

No JavaScript example here. This one is Objective-C only.

Objective-C

1- (void)client:(PubNub *)client didReceiveMessageAction:(PNMessageActionResult *)action {
2    NSLog(@"Action type: %@, value: %@", action.data.action.type, action.data.action.value);
3}

For how listener scope works on these SDKs, and the tradeoffs against entity-based scoping, refer to Listener scope follows the subscription, not the channel name.

Catch up on missed events

A Message Action event follows the same at-most-once live delivery rule as any other event: only a client subscribed at the moment of the add or remove receives it. Because the action itself is stored, a client that misses the live event can still catch up. Call Retrieve historical message actions for the channel to fetch what it missed.

Related tasks

• Message Actions in PubNub. The type/value model, the event model, and the Message Persistence requirement.
• Add message actions. Generate the event this handler receives.
• Retrieve historical message actions. Fetch actions added while a client was offline.
• Event listeners. The listener model, both registration styles, and how handler scope works.
• Receive messages. Create a subscription and register handlers on it.