Message Persistence API for Unreal SDK

Message Persistence gives you real-time access to the history of messages published to PubNub. Each message is timestamped to the nearest 10 nanoseconds and stored across multiple availability zones in several geographic locations. You can encrypt stored messages with AES-256 so they are not readable on PubNub’s network. For details, see Message Persistence.

You control how long messages are stored through your account’s retention policy. Options include: 1 day, 7 days, 30 days, 3 months, 6 months, 1 year, or Unlimited.

You can retrieve the following:

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

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->FetchHistoryAsync(Channel, OnFetchHistoryResponseDelegate, FetchHistorySettings);

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

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

  1FPubnubFetchHistoryResult Result = PubnubClient->FetchHistory(Channel, FetchHistorySettings);

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 receive messages older than the Start timetoken.
• If you specify only the End parameter (without Start), you receive messages from that End timetoken and newer.
• If you specify both Start and End, you receive messages between those timetokens (inclusive of End).

Returns up to 100 messages on a single channel, or 25 per channel on up to 500 channels. To page, iteratively update the Start timetoken.

Method(s)

1PubnubClient->FetchHistoryAsync(
2    FString Channel,
3    FOnPubnubFetchHistoryResponse OnFetchHistoryResponse,
4    FPubnubFetchHistorySettings FetchHistorySettings = FPubnubFetchHistorySettings()
5);

* required

Parameter	Description
Channel * Type: FString	The channel to get the historical messages of.
OnFetchHistoryResponse * Type: FOnPubnubFetchHistoryResponse	The delegate for the operation's result. You can also use a native callback of the type FOnPubnubFetchHistoryResponseNative 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

1

Actor.cpp

1

Blueprint

Truncated response

If truncated, a more property will be returned with additional parameters. Make iterative calls adjusting parameters.

Returns

This method is void. The delegate returns the following struct:

FOnPubnubFetchHistoryResponse

Delegate type: DECLARE_DYNAMIC_DELEGATE_TwoParams

Parameter	Description
Result Type: FPubnubOperationResult	The result of the operation.
Messages Type: const TArray<FPubnubHistoryMessageData>&	An array of historical messages.

FOnPubnubFetchHistoryResponseNative

Native callback variant that accepts a lambda.

Parameter	Description
Result Type: const FPubnubOperationResult&	The result of the operation.
Messages Type: const TArray<FPubnubHistoryMessageData>&	An array of historical messages.

FPubnubHistoryMessageData

Field	Type	Description
Message	FString	The message text.
Channel	FString	Channel that message was published to.
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

1

Actor.cpp

1

Fetch history with all additional parameters

You can add additional parameters to the request:

Actor.h

1

Actor.cpp

1

Fetch history with lambda

You can use a lambda function to handle the response:

Actor.h

1

Actor.cpp

1

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

Enable Delete-From-History in key settings and initialize with a secret key.

Method(s)

1PubnubClient->DeleteMessagesAsync(
2    FString Channel,
3    FOnPubnubDeleteMessagesResponse OnDeleteMessagesResponse,
4    FPubnubDeleteMessagesSettings DeleteMessagesSettings = FPubnubDeleteMessagesSettings()
5);

* required

Parameter	Description
Channel * Type: FString	The channel to get the historical messages of.
OnDeleteMessagesResponse * Type: FOnPubnubDeleteMessagesResponse	The delegate for the operation's result. You can also use a native callback of the type FOnPubnubDeleteMessagesResponseNative 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

1

Actor.cpp

1

Blueprint

Returns

This method is void. The delegate returns the following struct:

FOnPubnubDeleteMessagesResponse

Delegate type: DECLARE_DYNAMIC_DELEGATE_OneParam

Parameter	Description
Result Type: FPubnubOperationResult	The result of the operation.

FOnPubnubDeleteMessagesResponseNative

Native callback variant that accepts a lambda.

Parameter	Description
Result Type: 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

1

Actor.cpp

1

Delete messages with result struct

You can use the result struct to handle the response:

Actor.h

1

Actor.cpp

1

Delete messages with lambda

You can use a lambda function to handle the response:

Actor.h

1

Actor.cpp

1

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)

1PubnubClient->MessageCountsAsync(
2    FString Channel,
3    FString Timetoken,
4    FOnPubnubMessageCountsResponse OnMessageCountsResponse
5);

* 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: FOnPubnubMessageCountsResponse	The delegate for the operation's result. You can also use a native callback of the type FOnPubnubMessageCountsResponseNative 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

This method is void. The delegate returns the following struct:

FOnPubnubMessageCountsResponse

Delegate type: DECLARE_DYNAMIC_DELEGATE_TwoParams

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

FOnPubnubMessageCountsResponseNative

Native callback variant that accepts a lambda.

Parameter	Description
Result Type: const FPubnubOperationResult&	The result of the operation.
MessageCounts Type: 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

1

Actor.cpp

1

Message counts multiple

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 multiple channels since given timetokens. For each channel you provide a corresponding timetoken; the count for that channel is the number of messages in history with a timetoken greater than or equal to the given value.

Unlimited message retention

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

Method(s)

1PubnubClient->MessageCountsMultipleAsync(
2    TArray<FString> Channels,
3    TArray<FString> Timetokens,
4    FOnPubnubMessageCountsMultipleResponse OnMessageCountsMultipleResponse
5);

* required

Parameter	Description
Channels * Type: TArray<FString>	The channels to get the message counts of.
Timetokens * Type: TArray<FString>	One timetoken per channel; the count for each channel is from that timetoken onward.
OnMessageCountsMultipleResponse * Type: FOnPubnubMessageCountsMultipleResponse	The delegate for the operation's result. You can also use FOnPubnubMessageCountsMultipleResponseNative with a lambda.

Returns

This method is void. The delegate returns the following struct:

FOnPubnubMessageCountsMultipleResponse

Delegate type: DECLARE_DYNAMIC_DELEGATE_OneParam

Parameter	Description
Result Type: FPubnubMessageCountsMultipleResult	The operation result including message counts per channel.

FOnPubnubMessageCountsMultipleResponseNative

Native callback variant that accepts a lambda.

Parameter	Description
Result Type: const FPubnubMessageCountsMultipleResult&	The operation result including message counts per channel.

Deprecated methods

Fetch history (deprecated)

Deprecated

Use PubnubClient->FetchHistory() (synchronous) or PubnubClient->FetchHistoryAsync() (asynchronous) instead.

Method(s) (deprecated)

1PubnubSubsystem->FetchHistory(
2    FString Channel,
3    FOnFetchHistoryResponse OnFetchHistoryResponse,
4    FPubnubFetchHistorySettings FetchHistorySettings = FPubnubFetchHistorySettings()
5);

* required

Parameter	Description
Channel * Type: FString	The channel to get the historical messages of.
OnFetchHistoryResponse * Type: FOnFetchHistoryResponse	The delegate for the operation's result.
FetchHistorySettings Type: FPubnubFetchHistorySettings	Struct defining history configuration.

Returns (deprecated)

This function is void, but the delegate returns the FOnFetchHistoryResponse struct (Result, Messages).

Delete messages from history (deprecated)

Deprecated

Use PubnubClient->DeleteMessages() (synchronous) or PubnubClient->DeleteMessagesAsync() (asynchronous) instead.

Method(s) (deprecated)

1PubnubSubsystem->DeleteMessages(
2    FString Channel,
3    FOnDeleteMessagesResponse OnDeleteMessagesResponse,
4    FPubnubDeleteMessagesSettings DeleteMessagesSettings = FPubnubDeleteMessagesSettings()
5);

* required

Parameter	Description
Channel * Type: FString	The channel to get the historical messages of.
OnDeleteMessagesResponse * Type: FOnDeleteMessagesResponse	The delegate for the operation's result.
DeleteMessagesSettings Type: FPubnubDeleteMessagesSettings	Struct defining delete messages configuration.

Returns (deprecated)

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

Message counts (deprecated)

Deprecated

Use PubnubClient->MessageCounts() (synchronous) or PubnubClient->MessageCountsAsync() (asynchronous) instead.

Method(s) (deprecated)

1PubnubSubsystem->MessageCounts(
2    FString Channel,
3    FString Timetoken,
4    FOnMessageCountsResponse OnMessageCountsResponse
5);

* 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.

Returns (deprecated)

This function is void, but the delegate returns the FOnMessageCountsResponse struct (Result, MessageCounts).