Manage the user-channel membership relation

When a user joins a channel or gets invited to it, a membership relation between that user and the channel is created (Membership entity). The membership ends when this user leaves the channel.

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 initalizing the PubnubChatSubsystem node. Afterwards, you can use the Pubnub Chat object reference.

Blueprint functions

The Blueprints provided in the documentation show how you can structure your application and may contain utility methods and elements like buttons that are not part of the Unreal Chat SDK and are meant to serve as guidance.

• In C++, you can use the PubNub SDK as any other Game Instance Subsystem.

  #include "Kismet/GameplayStatics.h"
  #include "PubnubChatSubsystem.h"
  
  
  UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
  UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();
  
  
  UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user") // config optional

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

  Chat->DeleteUser("SomeUserID");

Usage in Blueprints and C++

Requires App Context

To set up and manage channel membership, you must enable App Context for your app's keyset in the Admin Portal.

Read on to learn how to check and update user-channel membership.

Get members

GetMembers() returns the list of all channel members.

Method signature

Blueprint

C++ / Input parameters

1Channel->GetMembers(
2    FString Filter = "", 
3    FString Sort = "", 
4    int Limit = 0, 
5    FPubnubPage Page = FPubnubPage()
6);

* required

Parameter	Description
Filter Type: FString Default: n/a	Expression used to filter the results. Returns only these channels whose properties satisfy the given expression are returned. The filter language is defined here.
Sort Type: FString Default: n/a	Key-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Use asc or desc to specify the sorting direction, or specify null to take the default sorting direction (ascending). For example: {name: "asc"}. By default, the items are sorted by the last updated date.
Limit Type: int Default: 100	Number of objects to return in response. The default (and maximum) value is 100.
Page Type: FPubnubPage Default: n/a	Object used for pagination to define which previous or next result page you want to fetch.
→ Next Type: FString Default: n/a	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
→ Prev Type: FString Default: n/a	Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the Next parameter is supplied.

Output

Parameter	Description
FPubnubMembersResponseWrapper Type: struct	Returned object containing these fields: Page, Total, Status, and Memberships.
→ Page Type: FPubnubPage	Object used for pagination to define which previous or next result page you want to fetch.
→ Next Type: FString	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
→ Prev Type: FString	Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the Next parameter is supplied.
→ Total Type: int	Total number of channel members.
→ Status Type: FString	Status code of a server response, like 200.
→ Memberships Type: TArray<UPubnubMembership*>	Array of all related memberships.

Sample code

List all members of the support channel on the premium support plan.

1#include "Kismet/GameplayStatics.h"
2#include "PubnubChatSubsystem.h"
3

4UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
5UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();
6

7UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user");
8

9UPubnubChannel* Channel = Chat->GetChannel("support");
10

11// Define the filter for members with "premium" support plan
12FString Filter = "custom.support_plan == 'premium'";
13

14// Fetch the members with the filter
15FPubnubMembersResponseWrapper Members = Channel->GetMembers(Filter);

Get membership

GetMemberships() returns the list of all channel memberships of a given user.

To get a list of all existing channels, use the GetChannels() method.

Blueprint

C++ / Input parameters

1User->GetMemberships(
2    FString Filter = "", 
3    FString Sort = "", 
4    int Limit = 0, 
5    FPubnubPage Page = FPubnubPage()
6);

* required

Parameter	Description
Filter Type: FString Default: n/a	Expression used to filter the results. Returns only these channels whose properties satisfy the given expression are returned. The filter language is defined here.
Sort Type: FString Default: n/a	Key-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Use asc or desc to specify the sorting direction, or specify null to take the default sorting direction (ascending). For example: {name: "asc"}. By default, the items are sorted by the last updated date.
Limit Type: int Default: 100	Number of objects to return in response. The default (and maximum) value is 100.
Page Type: FPubnubPage Default: n/a	Object used for pagination to define which previous or next result page you want to fetch.
→ Next Type: FString Default: n/a	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
→ Prev Type: FString Default: n/a	Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the Next parameter is supplied.

Output

Parameter	Description
FPubnubMembershipsResponseWrapper Type: struct	Returned object containing these fields: Page, Total, Status, and Memberships.
→ Page Type: FPubnubPage	Object used for pagination to define which previous or next result page you want to fetch.
→ Next Type: FString	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
→ Prev Type: FString	Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the Next parameter is supplied.
→ Total Type: int	Total number of channel members.
→ Status Type: FString	Status code of a server response, like 200.
→ Memberships Type: TArray<UPubnubMembership*>	Array of all related memberships.

Sample code

Find out which channels the support_agent_15 user is a member of.

1#include "Kismet/GameplayStatics.h"
2#include "PubnubChatSubsystem.h"
3

4UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
5UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();
6

7UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user");
8

9// Define user ID
10FString UserID = "support_agent_15";
11

12// Get the user and save the reference
13UPubnubUser* User = Chat->GetUser(UserID);
14

15FPubnubMembershipsResponseWrapper Memberships = User->GetMemberships();

Get updates

You can receive updates when specific user-channel Membership object(s) are edited (status, type, custom data) using the following methods:

• StreamUpdates() checks updates on a single Membership object.
• StreamUpdatesOn() checks updates on a list of Membership objects.

Membership changes

These methods notify you about field changes (e.g., metadata, status) for existing memberships, not new membership additions or removals.

Both methods accept a callback function as an argument. The Unreal Chat SDK invokes this callback whenever someone changes membership data.

Underneath, these methods subscribe the current user to a channel and add an objects event listener to receive all objects events of type membership. These methods also return the unsubscribe function you can invoke to stop receiving objects events and unsubscribe from the channel.

Method signature

Blueprint

C++ / Input parameters

• StreamUpdates()

  1Membership->StreamUpdates(FOnPubnubMembershipStreamUpdateReceived MembershipUpdateCallback);

• StreamUpdatesOn()

  1Membership->StreamUpdatesOn(
  2    TArray<UPubnubMembership*> Memberships, 
  3    FOnPubnubMembershipStreamUpdateReceived MembershipUpdateCallback
  4);

Parameter	Required in StreamUpdates()	Required in StreamUpdatesOn()	Description
Memberships Type: TArray<UPubnubMembership*> Default: n/a	No	Yes	Array of Membership objects for which you want to get updates.
MembershipUpdateCallback Type: FOnPubnubMembershipStreamUpdateReceived Default: n/a	Yes	Yes	Callback function passed as a parameter to both methods. It defines the custom behavior to be executed when detecting channel metadata changes.

Each function in the Unreal Chat SDK that takes a callback as a parameter requires you to handle the response type accordingly.

For example, you can bind a callback function for the Channel->StreamPresence method to its handler in the following way:

1// Create a pubnub response delegate
2// you MUST implement your own callback function to handle the response
3FOnPubnubChannelStreamPresenceReceived PresenceResponse;
4PresenceResponse.BindDynamic(this, &AMyActor::OnPresenceResponseReceived);
5

6Channel->StreamPresence(PresenceResponse);

You can implement the callback function to handle the response as follows:

AMyActor.h

1UFUNCTION()
2void OnPresenceResponseReceived(const TArray<FString> &PresentUsersIDs);

AMyActor.cpp

1void AMyActor::OnPresenceResponseReceived(const TArray<FString> &PresentUsersIDs)
2{
3	for(auto PresentUser : PresentUsersIDs)
4	{
5		UE_LOG(LogTemp, Log, TEXT("Present User ID: "), *PresentUser);
6	}
7}

Handle the response

Output

Type	Description
UPubnubCallbackStop*	Object on which you can call Stop() to stop receiving updates.

Sample code

Get updates on the first user membership.

• StreamUpdates()

  1#include "Kismet/GameplayStatics.h"
  2#include "PubnubChatSubsystem.h"
  3
  
  4UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
  5UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();
  6
  
  7UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user");
  8
  
  9// Get the users and save the reference
  10UPubnubUser* User1 = Chat->GetUser("support_agent_15");
  11
  
  12FPubnubMembershipsResponseWrapper Memberships = User->GetMemberships();
  13
  
  14UPubnubMembership* Membership = Memberships.Memberships[0];
  15
  
  16// Create a pubnub response delegate
  17// you MUST implement your own callback function to handle the response
  18FOnPubnubMembershipStreamUpdateReceived MembershipUpdatesResponse;
  19MembershipUpdatesResponse.BindDynamic(this, &AMyActor::OnMembershipResponseReceived);
  20
  
  21Membership->StreamUpdates(MembershipUpdatesResponse);

  show all 21 lines

Get updates on the first page of user memberships.

• StreamUpdatesOn()

  1#include "Kismet/GameplayStatics.h"
  2#include "PubnubChatSubsystem.h"
  3
  
  4UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
  5UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();
  6
  
  7UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user");
  8
  
  9// Get the users and save the reference
  10UPubnubUser* User1 = Chat->GetUser("support_agent_15");
  11TArray<UPubnubMembership*> Memberships = User->GetMemberships().Memberships;
  12
  
  13// Create a pubnub response delegate
  14// you MUST implement your own callback function to handle the response
  15FOnPubnubMembershipStreamUpdateReceived MembershipUpdatesOnResponse;
  16MembershipUpdatesOnResponse.BindDynamic(this, &AMyActor::OnMembershipsResponseReceived);
  17
  
  18Memberships->StreamUpdatesOn(MembershipUpdatesOnResponse);

  show all 18 lines

Other examples

Stop listening to updates on the first user membership.

• StreamUpdates()

  1auto StopUpdates = Membership->StreamUpdates(MembershipUpdatesResponse);
  2
  
  3StopUpdates->Stop();

Stop listening to updates on the first page of user memberships.

• StreamUpdatesOn()

  1auto StopUpdates = Membership->StreamUpdatesOn(MembershipUpdatesOnResponse);
  2
  
  3StopUpdates->Stop();

Update

Update() updates the channel membership information for a given user.

Method signature

Blueprint

C++ / Input parameters

1Membership->Update(FPubnubChatMembershipData MembershipData);

Type	Description
FPubnubChatMembershipData	The object containing all membership data.

FPubnubChatMembershipData

Parameter	Description
CustomDataJson Type: FString	Custom data associated with the membership.
Status Type: FString	Status of the membership.
Type Type: FString	Type of the membership.

Output

Type	Description
UPubnubMembership*	Returned (modified) object containing all membership data.

Sample code

Assign the premium-support role to support_agent_15 on the high-priority-incidents channel.

1#include "Kismet/GameplayStatics.h"
2#include "PubnubChatSubsystem.h"
3

4UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
5UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();
6

7UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user");
8

9// Define user ID
10FString UserID = "support_agent_15";
11

12// Get the user and save the reference
13UPubnubUser* User = Chat->GetUser(UserID);
14

15// Define user ID
16FString UserID = "support_agent_15";
17

18// Get the user and save the reference
19UPubnubUser* User = Chat->GetUser(UserID);
20// Define the filter for members with "premium" support plan
21FString Filter = "channel.id == 'high-priority-incidents'";
22

23FPubnubMembershipsResponseWrapper Memberships = User->GetMemberships(Filter);
24

25// There should only be one membership matching the filter, but this loop protects against unexpected cases
26  for (UPubnubMembership* Membership : Memberships.Memberships)
27  {
28      FPubnubChatMembershipData MembershipData;
29      MembershipData.CustomDataJson = "{\"role\": \"premium-support\"}";
30      MembershipData.Status = "active";
31      MembershipData.Type = "player";
32      Membership->Update(MembershipData); 
33

34      UE_LOG(LogTemp, Log, TEXT("Updated membership for user: %s with role: premium-support"), *UserID);
35  }

show all 35 lines

Get membership data

GetMembershipData() returns the channel membership data for a given user.

Method signature

Blueprint

C++ / Input parameters

1Membership->GetMembershipData();

Output

Type	Description
FPubnubChatMembershipData	The object containing all membership data.

Sample code

1#include "Kismet/GameplayStatics.h"
2#include "PubnubChatSubsystem.h"
3

4UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
5UPubnubChatSubsystem* PubnubChatSubsystem = GameInstance->GetSubsystem<UPubnubChatSubsystem>();
6

7UPubnubChat* Chat = PubnubChatSubsystem ->InitChat("demo", "demo", "my_user");
8

9// Define user ID
10FString UserID = "support_agent_15";
11

12// Get the user and save the reference
13UPubnubUser* User = Chat->GetUser(UserID);
14

15// Define user ID
16FString UserID = "support_agent_15";
17

18// Get the user and save the reference
19UPubnubUser* User = Chat->GetUser(UserID);
20

21// Define the filter for members with "premium" support plan
22FString Filter = "channel.id == 'high-priority-incidents'";
23

24FPubnubMembershipsResponseWrapper Memberships = User->GetMemberships(Filter);
25

26// If Membership exists, get it's data
27FPubnubChatMembershipData MembershipData;
28if(!Memberships.Memberships.IsEmpty())
29{
30	MembershipData = Memberships.Memberships[0]->GetMembershipData();
31}

show all 31 lines