Message Actions API for Unreal SDK

Add or remove actions on published messages to build features like receipts, reactions, or to associate custom metadata to messages. Clients can subscribe to a channel to receive message action events on that channel. They can also fetch past message actions from Message Persistence independently or when they fetch original messages.

Reactions

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

You can use PubNub's functionality via Blueprints or directly in C++ code.

• In Blueprints, the SDK is managed by a subsystem. Start by calling the Pubnub Subsystem node, then use Create Pubnub Client to create a UPubnubClient instance.

• In a C++ project, you have to add a dependency to PubnubLibrary:

  1. In your IDE, navigate to Source/_{YourProject}_/_{YourProject}_.Build.cs and add a dependency to PubnubLibrary.

     PrivateDependencyModuleNames.AddRange(new string[] { "PubnubLibrary" });

  2. Compile the code and run the project.

• In C++, start by getting the UPubnubSubsystem (a Game Instance Subsystem), then create a UPubnubClient with your configuration.

  #include "Kismet/GameplayStatics.h"
  #include "PubnubSubsystem.h"
  #include "PubnubClient.h"
  
  
  UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
  UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();
  
  
  FPubnubConfig Config;
  Config.PublishKey = "pub-c-...";
  Config.SubscribeKey = "sub-c-...";
  Config.UserId = "my-user-id";
  
  
  UPubnubClient* PubnubClient = PubnubSubsystem->CreatePubnubClient(Config);

  PubnubClient allows you to call PubNub SDK functions, for example:

  PubnubClient->PublishMessageAsync("my-channel", "Hello!", OnPublishMessageResponseDelegate);

  The SDK supports multiple UPubnubClient instances within the same game for different contexts such as different users or keysets. For more information, refer to Configuration.

Usage in Blueprints and C++

Asynchronous and synchronous method execution

Most PubNub Unreal SDK methods are available in both asynchronous and synchronous variants.

• Asynchronous methods (Async suffix) return void and take an optional delegate parameter that fires when the operation completes.

  1PubnubClient->AddMessageActionAsync(Channel, MessageTimetoken, ActionType, Value, OnAddMessageActionResponseDelegate);

  You can also use native callbacks that accept lambdas instead of dynamic delegates. Native callback types have the Native suffix (for example, FOnPubnubAddMessageActionResponseNative).

• Synchronous methods (no suffix) block the main game thread until the operation completes and return a result struct directly.

  1FPubnubAddMessageActionResult Result = PubnubClient->AddMessageAction(Channel, MessageTimetoken, ActionType, Value);

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.

Method(s)

1// Synchronous
2FPubnubAddMessageActionResult Result = PubnubClient->AddMessageAction(
3    FString Channel, 
4    FString MessageTimetoken, 
5    FString ActionType,  
6    FString Value
7);
8

9// Asynchronous
10PubnubClient->AddMessageActionAsync(
11    FString Channel, 
12    FString MessageTimetoken, 
13    FString ActionType,  
14    FString Value,
15    FOnPubnubAddMessageActionResponse OnAddMessageActionResponse
16);

show all 16 lines

* required

Parameter	Description
Channel * Type: FString	Channel to publish the message action to.
MessageTimetoken * Type: FString	Timetoken of the published message to apply the action to.
ActionType * Type: FString	Message action type.
Value * Type: FString	Message action value.
OnAddMessageActionResponse Type: FOnPubnubAddMessageActionResponse	Delegate for the operation result. You can also use a native callback of the type FOnPubnubAddMessageActionResponseNative to handle the result using a lambda.

Sample code

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

C++

Actor.h

1

Actor.cpp

1

Blueprint

Returns

• Synchronous: returns FPubnubAddMessageActionResult (Result, MessageActionData).
• Asynchronous: delegate FOnPubnubAddMessageActionResponse receives (Result, MessageActionData).

FPubnubAddMessageActionResult

Field	Type	Description
Result	FPubnubOperationResult	Result of the operation.
MessageActionData	FPubnubMessageActionData	The added message action data.

FOnPubnubAddMessageActionResponse

Field	Type	Description
Result	FPubnubOperationResult	Result of the operation.
MessageActionData	FPubnubMessageActionData	Message action data.

FOnPubnubAddMessageActionResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	Result of the operation.
MessageActionData	const FPubnubMessageActionData&	Message action data.

FPubnubMessageActionData

Field	Type	Description
Type	FString	Message action type.
Value	FString	Message action value.
UserID	FString	User ID of the user who added the action.
ActionTimetoken	FString	Timetoken indicating when the message action was added.
MessageTimetoken	FString	Timetoken indicating when the message the action was added to had been sent.

Other examples

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

Add a message action with lambda

You can use a lambda function to handle the response:

Actor.h

1

Actor.cpp

1

Add a message action with result struct

You can use the result struct to handle the response:

Actor.h

1

Actor.cpp

1

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)

1// Synchronous
2FPubnubOperationResult Result = PubnubClient->RemoveMessageAction(
3    FString Channel, 
4    FString MessageTimetoken, 
5    FString ActionTimetoken
6);
7

8// Asynchronous
9PubnubClient->RemoveMessageActionAsync(
10    FString Channel, 
11    FString MessageTimetoken, 
12    FString ActionTimetoken,
13    FOnPubnubRemoveMessageActionResponse OnRemoveMessageActionResponse
14);

* required

Parameter	Description
Channel * Type: FString	Channel the message action was published to.
MessageTimetoken * Type: FString	Timetoken of the published message to delete the action of.
ActionTimetoken * Type: FString	Timetoken of the published action to delete.
OnRemoveMessageActionResponse Type: FOnPubnubRemoveMessageActionResponse	Delegate for the operation result. You can also use a native callback of the type FOnPubnubRemoveMessageActionResponseNative to handle the result using a lambda.

Returns

• Synchronous: returns FPubnubOperationResult.
• Asynchronous: delegate FOnPubnubRemoveMessageActionResponse receives Result only.

FOnPubnubRemoveMessageActionResponse

Field	Type	Description
Result	FPubnubOperationResult	Result of the operation.

FOnPubnubRemoveMessageActionResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	Result of the operation.

Sample code

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

C++

Actor.h

1

Actor.cpp

1

Blueprint

Other examples

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

Remove a message action with lambda

You can use a lambda function to handle the response:

Actor.h

1

Actor.cpp

1

Remove a message action with result struct

You can use the result struct to handle the response:

Actor.h

1

Actor.cpp

1

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's timetoken in ascending order.

Truncated response

The number of message actions in the response may be truncated when internal limits are hit. If the response is truncated, a more property is returned with additional parameters. Send iterative calls to Message Persistence, adjusting the parameters to fetch more message actions.

Method(s)

1// Synchronous
2FPubnubGetMessageActionsResult Result = PubnubClient->GetMessageActions(
3    FString Channel,
4    FString Start = "", 
5    FString End = "", 
6    int Limit = 0
7);
8

9// Asynchronous
10PubnubClient->GetMessageActionsAsync(
11    FString Channel,
12    FOnPubnubGetMessageActionsResponse OnGetMessageActionsResponse,
13    FString Start = "", 
14    FString End = "", 
15    int Limit = 0
16);

show all 16 lines

* required

Parameter	Description
Channel * Type: FString	Channel the message action was published to.
OnGetMessageActionsResponse Type: FOnPubnubGetMessageActionsResponse	Delegate for the operation result. You can also use a native callback of the type FOnPubnubGetMessageActionsResponseNative to handle the result using a lambda.
Start Type: FString	Previously returned cursor bookmark for fetching the next page. Use "" to avoid paginating with a start bookmark.
End Type: FString	Previously returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter. Use "" to avoid paginating with an end bookmark.
Limit Type: int	Number of objects to return in the response. Default is 100.

Sample code

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

C++

Actor.h

1

Actor.cpp

1

Blueprint

Returns

• Synchronous: returns FPubnubGetMessageActionsResult (Result, MessageActions).
• Asynchronous: delegate FOnPubnubGetMessageActionsResponse receives (Result, MessageActions).

FPubnubGetMessageActionsResult

Field	Type	Description
Result	FPubnubOperationResult	Result of the operation.
MessageActions	TArray<FPubnubMessageActionData>	Array of FPubnubMessageActionData structs for the actions sent on a given channel.

FOnPubnubGetMessageActionsResponse

Field	Type	Description
Result	FPubnubOperationResult	Result of the operation.
MessageActions	const TArray<FPubnubMessageActionData>&	Array of FPubnubMessageActionData structs for the actions sent on a given channel.

FOnPubnubGetMessageActionsResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	Result of the operation.
MessageActions	const TArray<FPubnubMessageActionData>&	Array of FPubnubMessageActionData structs for the actions sent on a given channel.

FPubnubMessageActionData

Field	Type	Description
Type	FString	Message action type.
Value	FString	Message action value.
UserID	FString	User identifier of the user who added the action.
ActionTimetoken	FString	Timetoken indicating when the message action was added.
MessageTimetoken	FString	Timetoken indicating when the message, to which the action was added, had been sent.

Other examples

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

Get message actions with lambda

You can use a lambda function to handle the response:

Actor.h

1

Actor.cpp

1

Get message actions from a channel with a specific time window and limit

You can add a time window and limit to the request:

Actor.h

1

Actor.cpp

1

History with message reactions

You can choose to return message actions when fetching historical messages. Refer to Fetch History for more details.

Complete example

Reference code

Set up your Unreal project and follow the instructions in the lines marked with ACTION REQUIRED before running the code.

ASample_MessageActionsFull.h

1

ASample_MessageActionsFull.cpp

1

Deprecated methods

Add message action (deprecated)

Deprecated

Use PubnubClient->AddMessageAction or PubnubClient->AddMessageActionAsync instead.

1PubnubSubsystem->AddMessageAction(
2    FString Channel, 
3    FString MessageTimeToken, 
4    FString ActionType,  
5    FString Value,
6    FOnAddMessageActionResponse OnAddMessageActionResponse
7);

Remove message action (deprecated)

Deprecated

Use PubnubClient->RemoveMessageAction or PubnubClient->RemoveMessageActionAsync instead.

1PubnubSubsystem->RemoveMessageAction(
2    FString Channel, 
3    FString MessageTimeToken, 
4    FString ActionTimeToken,
5    FOnRemoveMessageActionResponse OnRemoveMessageActionResponse
6);

Get message actions (deprecated)

Deprecated

Use PubnubClient->GetMessageActions or PubnubClient->GetMessageActionsAsync instead.

1PubnubSubsystem->GetMessageActions(
2    FString Channel,
3    FOnGetMessageActionsResponse OnGetMessageActionsResponse,
4    FString Start = "", 
5    FString End = "", 
6    int Limit = 0
7);