Create custom events

Learn how Unreal Chat SDK handles events before working with custom chat events.

Event handling

PubNub events

With a standard PubNub SDK like the Unreal SDK, building a chat app requires additional steps:

• Subscribe to channels to receive messages
• Add event listeners to handle messages, signals, and events

Unreal Chat SDK handles this automatically. All listener methods return a function to stop receiving events and unsubscribe from the channel.

Entity	Method	Events handled
Channel	StreamUpdates() or StreamUpdatesOn()	(Un)Subscribe the current user to/from a channel and start/stop getting all objects events of type channel.
User	StreamUpdates() or StreamUpdatesOn()	(Un)Subscribe the current user to/from a channel and start/stop getting all objects events of type uuid.
Message	StreamUpdates() or StreamUpdatesOn()	(Un)Subscribe the current user to/from a channel and start/stop getting all messageAction events (for message and message actions changes) of type added or removed.
Membership	StreamUpdates() or StreamUpdatesOn()	(Un)Subscribe the current user to/from a channel and start/stop getting all objects events of type membership.
Channel	Connect()	(Un)Subscribe the current user to/from a channel and start/stop getting all message events of type text.
Channel	StreamTyping() and StopStreamingTyping()	(Un)Subscribe the current user to/from a channel and start/stop getting all signal events of type typing.
Channel	StreamPresence()	(Un)Subscribe the current user to/from a channel and start/stop getting all presence events of type action (responsible for monitoring when users join, leave the channels, or when their channel connection times out and they get disconnected).

Unreal Chat SDK wraps server responses into entities like Channel, Message, and User with methods and properties for building your app's UI.

Chat events

Events are separate entities that carry data payloads and can trigger business logic (for example, the Typing Indicator starts or stops based on typing events).

Unreal Chat SDK automatically emits these event types when a user:

• Reports a message (report event type for messages)
• Starts/Stops typing a message on a channel (typing event type)
• Mentions someone else in the message (mention event type)
• Reads a message published on a channel (receipt event type)
• Invites another user to join a channel (invite event type)
• Mutes a user, bans them, or removes these restrictions (moderation event type)

All event types use the PubNub Pub/Sub API with Publish() or Signal() methods.

Retrieve historical events with:

• GetEventsHistory() - for historical events emitted via Publish()

History retrieval

GetEventsHistory() cannot filter by event type. It returns all events emitted via Publish() on the channel within the specified timeframe.

Each event type has a fixed payload structure documented below.

Events for reported messages

• Type: report
• PubNub method: PubNub method used to send events you listen for. Publish() (with history) is used for all events related to message reporting.
• Target: PUBNUB_INTERNAL_ADMIN_CHANNEL
• Trigger: Report() method on the Message object
• Listener: GetEventsHistory() (historical) on the Chat object
• Sample use case: Message moderation. You might want to create a UI for an operational dashboard to monitor and manage all reported messages.
• Payload:

1payload: {
2    // content of the flagged message
3    text: string;
4    // reason for flagging the message
5    reason: string;
6    // channel where message was flagged
7    reportedMessageChannelId: string;
8    // timetoken of the flagged message
9    reportedMessageTimetoken: string;
10    // author of the flagged message
11    reportedUserId: string;
12}

Events for typing indicator

• Type: typing
• PubNub method: PubNub method used to send events you listen for. Signal() (without history) is used for all events related to typing.
• Target: The same channel where messages are published.
• Trigger: StartTyping() and StopTyping() methods on the Channel object
• Listener: StreamTyping() on the Channel object
• Sample use case: Typing indicator. You might want to show graphically on the channel that another channel member is typing or has stopped typing a message.
• Payload:

1payload: {
2    // value showing whether someone is typing or not
3    value: boolean;
4}

Events for mentions

• Type: mention
• PubNub method: PubNub method used to send events you listen for. Publish() (with history) is used for all events related to mentions.
• Target: Unlike in other event types, a target for mention events is equal to a user ID. This ID is treated as a user-specific channel and is used to send system notifications about changes concerning a User object, such as creating, updating, or deleting that user. The channel name is equal to the ID (id) of the user and you can retrieve it by calling the currentUser method on the Chat object.
• Trigger: SendText() method on the Channel object
• Listener: GetEventsHistory() (historical) on the Chat object, or the OnMentioned delegate on the User object
• Sample use case: User mentions. You might want to receive notifications for all events emitted when you are mentioned in a parent or thread channel.
• Payload:

1payload: {
2    // timetoken of the message where someone is mentioned
3    messageTimetoken: string;
4    // channel on which the message with mention was sent
5    channel: string;
6}

Events for read receipts

• Type: receipt
• PubNub method: PubNub method used to send events you listen for. Signal() (with history persisted as the last read message on the Membership object) is used for all events related to message read receipts.
• Target: The same channel where messages are published.
• Trigger: MarkAllMessagesAsRead() method on the Chat object, the SetLastReadMessageTimetoken() method on the Membership object, and the SetLastReadMessage() method on the Membership object
• Listener: StreamReadReceipts() (current) on the Channel object
• Sample use case: Read receipts. You might want to indicate on a channel - through avatars or some other indicator - that a message was read by another user/other users.
• Payload:

1payload: {
2    // timetoken of the read message
3    messageTimetoken: string;
4}

Events for channel initations

• Type: invite
• PubNub method: PubNub method used to send events you listen for. Publish() (with history) is used for all events related to channel invitations.
• Target: The same channel where messages are published.
• Trigger: Invite() and InviteMultiple() methods on the Channel object
• Listener: GetEventsHistory() (historical) on the Chat object, or the OnInvited delegate on the User object
• Sample use case: Channel invitations. You might want to notify users that they were invited to join a channel.
• Payload: Delivered as FPubnubChatInviteEvent:

Field	Type	Description
Timetoken	FString	Timetoken of the invite event.
ChannelID	FString	ID of the channel to which the user was invited.
ChannelType	FString	Type of channel (e.g., direct, group).
InvitedByUserID	FString	User ID of the person who sent the invitation.

Events for user moderation

• Type: moderation
• PubNub method: PubNub method used to send events you listen for. Publish() (with history) is used for all events related to user restrictions.
• Target: An event is sent to the ID of the moderated user (user channel with the name same as the user ID) preceded by the PUBNUB_INTERNAL_MODERATION. prefix, like PUBNUB_INTERNAL_MODERATION.[UserId].
• Trigger: SetRestrictions() methods on the Channel, Chat, and User objects
• Listener: GetEventsHistory() (historical) on the Chat object, or the OnRestrictionChanged delegate on the User object
• Sample use case: User moderation. You might want to notify users when they were muted, banned, or when you remove these restrictions from them.
• Payload:

1payload: {
2  // ID of the channel on which the user's moderation restrictions were set or lifted
3  channelId: `PUBNUB_INTERNAL_MODERATION.String`
4  // ID of the channel on which the user's moderation restrictions were set or lifted preceded by the PUBNUB_INTERNAL_MODERATION. prefix",
5  restriction: "muted" | "banned" | "lifted"
6  // reason for muting or banning the user
7  reason?: string
8}

Custom events

The custom event type carries custom payloads for additional business logic. Methods:

• GetEventsHistory() - retrieve historical events
• StreamCustomEvents() - listen for real-time custom events on a Channel object

Get historical events

GetEventsHistory() retrieves historical events from a channel, similar to GetHistory() for messages. Results cannot be filtered by type and include all events emitted via Publish() in the specified timeframe.

Method signature

1Chat->GetEventsHistory(
2    FString ChannelID,
3    FString StartTimetoken,
4    FString EndTimetoken,
5    int Count = 100
6);

* required

Parameter	Description
ChannelID * Type: FString Default: n/a	Channel from which you want to pull historical events.
StartTimetoken Type: FString Default: n/a	Timetoken delimiting the start of a time slice (exclusive) to pull events from. For details, refer to the Fetch History section.
EndTimetoken Type: FString Default: n/a	Timetoken delimiting the end of a time slice (inclusive) to pull events from. For details, refer to the Fetch History section.
Count Type: int Default: 100	Number of historical events to return for the channel in a single call. You can pull a maximum number of 100 events in a single call.

Output

Parameter	Description
FPubnubChatEventsResult Type: struct	Returned object containing Result, Events, and IsMore.
→ Result Type: FPubnubChatOperationResult	Operation result with Error (bool), ErrorMessage (FString), and StepResults.
→ Events Type: TArray<FPubnubChatEvent>	Array listing the requested number of historical event objects.
→ IsMore Type: bool	Info whether there are more historical events to pull.

FPubnubChatEvent

Parameter	Description
Timetoken Type: FString	Timetoken of the event.
ChannelID Type: FString	Channel the event occurred on.
UserID Type: FString	User ID associated with the event.
Payload Type: FString	Event payload.
Type Type: EPubnubChatEventType	Type of the event.

EPubnubChatEventType

Value	Description
PCET_Typing	Indicates a user is typing a message. Displayed as Typing.
PCET_Report	Represents an event where a message has been flagged or reported for offensive content. Displayed as Report.
PCET_Receipt	Confirms receipt of a message or event. Displayed as Receipt.
PCET_Mention	Indicates that a user has been mentioned in a message. Displayed as Mention.
PCET_Invite	Represents an invitation event typically sent to a specific user. Displayed as Invite.
PCET_Custom	Custom event type for specialized behavior or use cases. Displayed as Custom.
PCET_Moderation	Represents an event related to content moderation actions. Displayed as Moderation.

Sample code

Fetch the last 10 historical events from the CUSTOMER-SATISFACTION-CREW channel.

1

Emit custom event on a channel

EmitCustomEvent() publishes a custom event to a channel. Subscribers listening with StreamCustomEvents() will receive it.

Method signature

1Channel->EmitCustomEvent(
2    FString Payload,
3    FString Type = "",
4    bool StoreInHistory = true
5);

* required

Parameter	Description
Payload * Type: FString Default: n/a	Custom event data to publish.
Type Type: FString Default: ""	Optional type label for the custom event.
StoreInHistory Type: bool Default: true	Whether to store the event in Message Persistence.

Output

Type	Description
FPubnubChatOperationResult	Operation result with Error (bool) and ErrorMessage (FString).

To emit asynchronously, use Channel->EmitCustomEventAsync(Payload, OnOperationResponse, Type, StoreInHistory).

Stream custom events on a channel

You can also listen for custom events directly on a Channel object using StreamCustomEvents(). Custom events are delivered via the OnCustomEventReceived delegate on the channel.

Call StopStreamingCustomEvents() to stop listening.

Method signature

1Channel->StreamCustomEvents();

Output

Type	Description
FPubnubChatOperationResult	Operation result with Error (bool), ErrorMessage (FString), and StepResults (per-step details).

OnCustomEventReceived delegate

Bind to the OnCustomEventReceived delegate on the channel to handle incoming custom events.

Delegate	Parameter
FOnPubnubChatCustomEventReceived Type: FPubnubChatCustomEvent	CustomEvent

FPubnubChatCustomEvent

Field	Type	Description
Timetoken	FString	Timetoken of the custom event.
UserID	FString	ID of the user who emitted the event.
Payload	FString	Custom event payload.
Type	FString	Custom event type string.

Sample code

Actor.h

1

Actor.cpp

1