Message Persistence API for Unreal SDK

Message Persistence provides real-time access to the history of all messages published to PubNub. Each published message is timestamped to the nearest 10 nanoseconds and is stored across multiple availability zones in several geographical locations. Stored messages can be encrypted with AES-256 message encryption, ensuring that they are not readable while stored on PubNub's network. For more information, refer to Message Persistence.

Messages can be stored for a configurable duration or forever, as controlled by the retention policy that is configured on your account. The following options are available: 1 day, 7 days, 30 days, 3 months, 6 months, 1 year, or Unlimited.

You can retrieve the following:

• Messages
• Message reactions
• File Sharing (using File Sharing API)

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

• In Blueprints, the whole SDK is managed by a subsystem, so start by calling the Pubnub Subsystem node.

• 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++, you can use the PubNub SDK as any other Game Instance Subsystem.

  #include "Kismet/GameplayStatics.h"
  #include "PubnubSubsystem.h"
  
  UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
  UPubnubSubsystem* PubnubSubsystem = GameInstance->GetSubsystem<UPubnubSubsystem>();

  PubnubSubsystem now allows you to call all PubNub SDK functions, for example:

  PubnubSubsystem->SubscribeToChannel("MyChannel");

Usage in Blueprints and C++

Fetch history

Requires Message Persistence

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

This function fetches historical messages from one or multiple channels. The IncludeMessageActions flag also allows you to fetch message actions along with the messages.

It's possible to control how messages are returned and in what order.

• if you specify only the Start parameter (without End), you will receive messages that are older than the Start timetoken
• if you specify only the End parameter (without Start), you will receive messages from that End timetoken and newer
• if you specify values for both Start and End parameters, you will retrieve messages between those timetokens (inclusive of the End value)

You will receive a maximum of 100 messages for a single channel or 25 messages for multiple channels (up to 500). If more messages meet the timetoken criteria, make iterative calls while adjusting the start timetoken to fetch the entire list of messages from Message Persistence.

Method(s)

PubnubSubsystem->FetchHistory(
    FString Channel, 
    FOnFetchHistoryResponse OnFetchHistoryResponse, 
    FPubnubFetchHistorySettings FetchHistorySettings = FPubnubFetchHistorySettings()
);

* required

Parameter	Description
Channel * Type: FString	The channel to get the historical messages of.
OnFetchHistoryResponse * Type: FOnFetchHistoryResponse	The delegate for the operation's result. You can also use a native callback of the type FOnFetchHistoryResponseNative to handle the result using a lambda.
FetchHistorySettings Type: FPubnubFetchHistorySettings	Struct defining history configuration.

FPubnubFetchHistorySettings

* required

Parameter	Description
MaxPerChannel Type: int	Specifies the number of historical messages to return. Default and maximum is 100 for a single channel, 25 for multiple channels, and 25 if IncludeMessageActions is true.
Reverse Type: bool	Setting to true will traverse the time line in reverse starting with the oldest message first. Default is false.
Start Type: FString	Timetoken delimiting the start of time slice (exclusive) to pull messages from.
End Type: FString	Timetoken delimiting the end of time slice (inclusive) to pull messages from.
IncludeMeta Type: bool	Whether meta (passed when Publishing the message) should be included in response or not.
IncludeMessageType Type: bool	Pass true to receive the message type with each history message. Default is false.
IncludeUserID Type: bool	Pass true to receive the publisher uuid with each history message. Default is false.
IncludeMessageActions Type: bool	The flag denoting to retrieve history messages with message actions. If true, the method is limited to one channel and 25 messages only. Default is false.
IncludeCustomMessageType Type: bool	Indicates whether to retrieve messages with the custom message type. For more information, refer to Retrieving Messages.

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

Actor.cpp

Blueprint

Truncated response

If you fetch messages with messages actions, the number of messages in the response may be truncated when internal limits are hit. If the response is truncated, a more property will be returned with additional parameters. Send iterative calls to history adjusting the parameters to fetch more messages.

Returns

This function is void, but the delegate returns the FOnFetchHistoryResponse struct.

FOnFetchHistoryResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.
Messages	TArray<FPubnubHistoryMessageData>&	An array of FPubnubHistoryMessageData structs which are the historical messages you wanted to fetch.

FOnFetchHistoryResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	The result of the operation.
Messages	const TArray<FPubnubHistoryMessageData>&	An array of FPubnubHistoryMessageData structs which are the historical messages you wanted to fetch.

FPubnubHistoryMessageData

Field	Type	Description
Message	FString	The message text.
UserID	FString	User ID of the user who sent the message.
Timetoken	FString	Timetoken indicating when the message was sent.
Meta	FString	Additional information.
MessageType	FString	Type of the message. Refer to Message types for more information.
CustomMessageType	FString	The custom message type associated with the message.
MessageActions	TArray<FPubnubMessageActionData>	An array of FPubnubMessageActionData structs which are message actions that were added to the historical messages.

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.

Fetch history for a specific time window

You can add a time window to the request:

Actor.h

Actor.cpp

Fetch history with all additional parameters

You can add additional parameters to the request:

Actor.h

Actor.cpp

Fetch history with lambda

You can use a lambda function to handle the response:

Actor.h

Actor.cpp

Delete messages from history

Requires Message Persistence

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

Removes the messages from the history of a specific channel.

Required setting

There is a setting to accept delete from history requests for a key, which you must enable by checking the Enable Delete-From-History checkbox in the key settings for your key in the Admin Portal.

Requires Initialization with secret key.

Method(s)

PubnubSubsystem->DeleteMessages(
    FString Channel, 
    FOnDeleteMessagesResponse OnDeleteMessagesResponse, 
    FPubnubDeleteMessagesSettings DeleteMessagesSettings = FPubnubDeleteMessagesSettings()
);

* required

Parameter	Description
Channel * Type: FString	The channel to get the historical messages of.
OnDeleteMessagesResponse * Type: FOnDeleteMessagesResponse	The delegate for the operation's result. You can also use a native callback of the type FOnDeleteMessagesResponseNative to handle the result using a lambda.
DeleteMessagesSettings Type: FPubnubDeleteMessagesSettings	Struct defining delete messages configuration.

FPubnubDeleteMessagesSettings

* required

Parameter	Description
Start Type: FString	Timetoken delimiting the start of time slice (inclusive) to delete messages from.
End Type: FString	Timetoken delimiting the end of time slice (exclusive) to delete messages from.

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

Actor.cpp

Blueprint

Returns

This function is void, but the delegate returns the FOnDeleteMessagesResponse struct.

FOnDeleteMessagesResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.

FOnDeleteMessagesResponseNative

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

Other examples

Reference code

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

Delete specific message from history

To delete a specific message, pass the publish timetoken (received from a successful publish) in the End parameter and timetoken - 1 in the Start parameter. For example, if 15526611838554310 is the publish timetoken, pass 15526611838554309 in Start and 15526611838554310 in End.

Actor.h

Actor.cpp

Delete messages with result struct

You can use the result struct to handle the response:

Actor.h

Actor.cpp

Delete messages with lambda

You can use a lambda function to handle the response:

Actor.h

Actor.cpp

Message counts

Requires Message Persistence

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

Returns the number of messages published on one or more channels since a given time. The count returned is the number of messages in history with a Timetoken value greater than or equal to than the passed value in the Timetoken parameter.

Unlimited message retention

For keys with unlimited message retention enabled, this method considers only messages published in the last 30 days.

Method(s)

PubnubSubsystem->MessageCounts(
    FString Channel, 
    FString Timetoken, 
    FOnMessageCountsResponse OnMessageCountsResponse
);

* required

Parameter	Description
Channel * Type: FString	The channel to get the message counts of.
Timetoken * Type: FString	The timetoken to fetch the message counts from.
OnMessageCountsResponse * Type: FOnMessageCountsResponse	The delegate for the operation's result. You can also use a native callback of the type FOnMessageCountsResponseNative 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

Actor.cpp

Blueprint

Returns

This function is void, but the delegate returns the FOnMessageCountsResponse struct.

FOnMessageCountsResponse

Field	Type	Description
Result	FPubnubOperationResult	The result of the operation.
MessageCounts	int	The number of messages published on one or more channels since a given time.

FOnMessageCountsResponseNative

Field	Type	Description
Result	const FPubnubOperationResult&	The result of the operation.
MessageCounts	int	The number of messages published on one or more channels since a given time.

Other examples

Reference code

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

Message counts with lambda

You can use a lambda function to handle the response:

Actor.h

Actor.cpp