Create custom events

Before creating your own custom chat events, learn how Chat SDK handles PubNub and chat-specific events.

Event handling

PubNub events

If you were to use a standard PubNub SDK, such as the Swift SDK, to build a chat app, you would have to perform additional steps as part of your PubNub initialization:

• Explicitly subscribe to the chosen channel(s) to receive messages.
• Add event listeners for your app to receive and handle all messages, signals, and events sent to the channel(s) you are subscribed to.

Luckily, the Chat SDK does this work automatically for you as part of other methods you will run on various entities to build and work with your chat app.

All these methods also return a function you can invoke to stop receiving events of a given type and unsubscribe from the channel. Follow the links to method descriptions for details and examples.

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	getTyping()	(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).

Chat SDK wraps all events returned as HTTP responses from the server into meaningful and handy entities, like Channel, Message, User. These objects contain methods you can invoke to build your chat app and parameters you can display on your app's UI.

Chat events

Events, just like messages, are separate entities in the Chat SDK that carry data as a payload. Contrary to messages, however, events are not merely data transmitters but can trigger additional business logic. For example, in the Chat SDK, the Typing Indicator feature relies on events - based on whether a user is typing or not, the typing indicator starts or stops.

Chat SDK handles a few intrinsic types of such events that get emitted automatically when a user:

• Reports a message (Report event type)
• 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)

All event types use underneath the PubNub Pub/Sub API and one of these methods:

• publish() - if event history is required, like for storing reported messages. For the purpose of the Chat SDK, history is always enabled when emitting an event with the publish() method.
• signal() - if no event history is required, like in the case of the typing indicator that relies on short-lived signals.

Different Chat SDK methods emit (handle) different chat event types. For example, the sendText() method called on the Channel object emits Mention events because the IDs of the mentioned users are always passed as part of published messages.

To listen to those events, Chat SDK uses two methods:

• listenForEvents() for the current events that are emitted with the signal() or publish() method.
• getEventsHistory() to get historical events that were emitted with the publish() method.

Events history limitations

The getEventsHistory() method uses PubNub Message Persistence API which has limitations - you cannot filter the results by type. Calling this method would return all event types that happened on a given channel in a given timeframe as long as they were emitted with the publish() method that stores history. Check custom events for an example showing this method.

The payload structure of the chat events is fixed and depends on the event type.

Read the subsections to get a better overview of each event type - check how they work and get some ideas on using them in your chat app to trigger additional business logic.

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_MODERATION_{channel_id}
• Trigger: report() method on the Message object
• Listener: streamMessageReports() (current) and getMessageReportsHistory (historical)
• Sample use case: Message moderation. You might want to create a UI for an operational dashboard to monitor and manage all reported messages.
• Payload:

1public class Report: EventContent {
2  public let text: String?
3  public let reason: String
4  public let reportedMessageTimetoken: Timetoken?
5  public let reportedMessageChannelId: String?
6  public let reportedUserId: String?
7}

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: getTyping() 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:

1public class Typing: EventContent {
2  public let value: Bool
3}

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: listenForEvents() (current) or getEventsHistory() (historical) on the Chat 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:

1public class Mention: EventContent {
2  public let messageTimetoken: Timetoken
3  public let channel: String
4  public let parentChannel: String?
5}

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 Chat 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:

1public class Receipt: EventContent {
2  public let messageTimetoken: Timetoken
3}

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: An event is sent to the ID of the invited user (user channel with the name same as the user ID).
• Trigger: invite() and inviteMultiple methods on the Channel object
• Listener: listenForEvents() (current) or getEventsHistory() (historical) on the Chat object
• Sample use case: Channel invitations. You might want to notify users that they were invited to join a channel.
• Payload:

1public class Invite: EventContent {
2  public let channelType: ChannelType
3  public let channelId: String
4}

Custom events

Chat SDK provides an additional type of events called custom. As the type name suggests, they are meant to let you carry your custom payloads and use them to perform additional business logic in your chat app.

With Chat SDK, you can:

• Trigger such custom events using the emitEvent() method.
• Listen to them with the listenForEvents() method.
• Get all historical events using the getEventsHistory() method.

Create and send events

emitEvent() handles (constructs and sends) events with your custom payload.

In its logic, you can compare this method to the sendText() method used for sending new messages.

Method signature

This method takes the following parameters:

1chat.emitEvent<T : EventContent>(
2    channelId: String,
3    payload: T,
4    mergePayloadWith otherPayload: [String: JSONCodable]? = nil
5) async throws -> Timetoken

Input

* required

Parameter	Description
channelId Type: String Default: n/a	Channel where you want to send the events.
payload * Type: T Default: n/a	Type of events. Use custom for full control over event payload and emitting method.
mergePayloadWith * Type: [String: JSONCodable] Default: n/a	Metadata in the form of key-value pairs you want to pass as events from your chat app. Can contain anything in case of Custom events, but has a predefined structure for other types of events.

Output

Parameter	Description
Timetoken	Result of the PubNub Publish or Signal call.

Sample code

You want to monitor a high-priority channel with a keyword spotter that identifies dissatisfaction words like "annoyed," "frustrated," or "angry." Suppose a message sent by any of the customers present on this channel contains any of these words. In that case, you want to resend it (with relevant metadata) to a separate technical channel (CUSTOMER-SATISFACTION-CREW) that's monitored by the team responsible for customer satisfaction.

1// Define a custom payload that conforms to EventContent
2class CustomEventPayload: EventContent, JSONCodable {
3  let chatID: String
4  let timestamp: String
5  let customerID: String
6  let triggerWord: String
7  
8  init(chatID: String, timestamp: String, customerID: String, triggerWord: String) {
9    self.chatID = chatID
10    self.timestamp = timestamp
11    self.customerID = customerID
12    self.triggerWord = triggerWord
13  }
14}
15

16// Assuming you have a reference of type "ChatImpl" named "chat".
17// Create the custom payload
18Task {
19  let customPayload = CustomEventPayload(
20    chatID: "chat1234",
21    timestamp: "2022-04-30T10:30:00Z",
22    customerID: "customer5678",
23    triggerWord: "frustrated"
24  )
25    
26  // Emit the custom event to the "CUSTOMER-SATISFACTION-CREW" channel
27  try await chat.emitEvent(
28    channelId: "CUSTOMER-SATISFACTION-CREW",
29    payload: customPayload,
30    mergePayloadWith: nil
31  )
32}

show all 32 lines

Receive current events

listenForEvents() lets you watch a selected channel for any new custom events emitted by your chat app. You can decide what to do with the incoming custom events and handle them using an async stream.

In its logic, you can compare this method to the connect() method used for receiving new messages.

Method signature

This method takes the following parameters:

1chat.listenForEvents<T: EventContent>(
2    type: T.Type,
3    channelId: String,
4    customMethod: EmitEventMethod = .publish
5  ) -> AsyncStream<EventWrapper<T>>

Input

* required

Parameter	Description
type * Type: T.Type Default: n/a	Type parameter allowing access to type information at runtime.
channelId * Type: String Default: n/a	Channel to listen for new events.
customMethod Type: EmitEventMethod Default: n/a	An optional custom method for emitting events. If not provided, defaults to .publish. Available values: .publish and .signal.

Output

Parameter	Description
AsyncStream<EventWrapper<T>>	An asynchronous stream that produces a value each time a new event of the specified type is emitted.

Sample code

Monitor a channel for frustrated customer events. When such an event occurs, the handleFrustratedEvent function responds with a message acknowledging the customer's frustration and offering assistance.

AsyncStream

1// Define a custom payload that conforms to EventContent
2class CustomEventPayload: EventContent, JSONCodable {
3  let chatID: String
4  let timestamp: String
5  let customerID: String
6  let triggerWord: String
7  
8  init(chatID: String, timestamp: String, customerID: String, triggerWord: String) {
9    self.chatID = chatID
10    self.timestamp = timestamp
11    self.customerID = customerID
12    self.triggerWord = triggerWord
13  }
14}
15

16// Function to handle the "frustrated" event and respond to the customer
17func handleFrustratedEvent(eventData: CustomEventPayload) {
18  // Extract relevant information from the event data
19  let customerID = eventData.customerID
20  let timestamp = eventData.timestamp
21  let triggerWord = eventData.triggerWord
22    
23  // Create a response
24  let response = "Thank you for reaching out. We're sorry to hear that you're \(triggerWord). Our team is here to help and will work to resolve your concerns as quickly as possible. Your satisfaction is important to us."
25    
26  // Send the response back to the customer's chat (mocked function)
27  sendResponseToCustomerChat(customerID: customerID, timestamp: timestamp, response: response)
28}
29

30// Mocked function to send a response back to the customer's chat
31func sendResponseToCustomerChat(customerID: String, timestamp: String, response: String) {
32  // Implement the logic to send a response back to the customer's chat
33  debugPrint("Sent response to customer \(customerID) at \(timestamp): \(response)")
34}
35

36// Listen for events on the "CUSTOMER-SATISFACTION-CREW" channel.
37// Assuming you have a reference of type "ChatImpl" named "chat"
38Task {
39  for await event in chat.listenForEvents(
40    type: CustomEventPayload.self,
41    channelId: "CUSTOMER-SATISFACTION-CREW",
42    customMethod: .publish
43  ) {
44    if event.event.payload.triggerWord == "frustrated" {
45      handleFrustratedEvent(eventData: event.event.payload)
46    }
47  }
48}
49

50// Simulated triggering of the event with example event data somewhere else in your application.
51// Assuming you have a reference of type "ChatImpl" named "chat"
52Task {
53  let simulatedEventData = CustomEventPayload(
54    chatID: "chat1234",
55    timestamp: "2022-04-30T10:30:00Z",
56    customerID: "customer5678",
57    triggerWord: "frustrated"
58  )
59

60  try await chat.emitEvent(
61    channelId: "CUSTOMER-SATISFACTION-CREW",
62    payload: simulatedEventData
63  )
64}

show all 64 lines

Closure

1// Define a custom payload that conforms to EventContent
2class CustomEventPayload: EventContent, JSONCodable {
3  let chatID: String
4  let timestamp: String
5  let customerID: String
6  let triggerWord: String
7  
8  init(chatID: String, timestamp: String, customerID: String, triggerWord: String) {
9    self.chatID = chatID
10    self.timestamp = timestamp
11    self.customerID = customerID
12    self.triggerWord = triggerWord
13  }
14}
15

16// Function to handle the "frustrated" event and respond to the customer
17func handleFrustratedEvent(eventData: CustomEventPayload) {
18  // Extract relevant information from the event data
19  let customerID = eventData.customerID
20  let timestamp = eventData.timestamp
21  let triggerWord = eventData.triggerWord
22    
23  // Create a response
24  let response = "Thank you for reaching out. We're sorry to hear that you're \(triggerWord). Our team is here to help and will work to resolve your concerns as quickly as possible. Your satisfaction is important to us."
25    
26  // Send the response back to the customer's chat (mocked function)
27  sendResponseToCustomerChat(customerID: customerID, timestamp: timestamp, response: response)
28}
29

30// Mocked function to send a response back to the customer's chat
31func sendResponseToCustomerChat(customerID: String, timestamp: String, response: String) {
32  // Implement the logic to send a response back to the customer's chat
33  debugPrint("Sent response to customer \(customerID) at \(timestamp): \(response)")
34}
35

36// Listen for events on the "CUSTOMER-SATISFACTION-CREW" channel.
37// Assuming you have a reference of type "ChatImpl" named "chat"
38

39// Hold a strong reference to the returned "AutoCloseable" object; otherwise, it will be canceled
40let autoCloseable = chat.listenForEvents(
41  type: CustomEventPayload.self,
42  channelId: "CUSTOMER-SATISFACTION-CREW",
43  customMethod: .publish
44) { event in
45  // Check if the trigger word is "frustrated"
46  if event.event.payload.triggerWord == "frustrated" {
47      handleFrustratedEvent(eventData: event.event.payload)
48  }
49}
50

51// Simulated triggering of the event callback with example event data
52let simulatedEventData = CustomEventPayload(
53  chatID: "chat1234",
54  timestamp: "2022-04-30T10:30:00Z",
55  customerID: "customer5678",
56  triggerWord: "frustrated"
57)

show all 57 lines

Get historical events

getEventsHistory() lets you get historical events from a selected channel.

In its logic, you can compare this method to the getHistory() method used for receiving historical messages. Similarly to this method, you cannot filter the results by type, so you'll get all events emitted with the publish() method that happened on a given channel in a given timeframe (not only Custom events).

Method signature

This method takes the following parameters:

1chat.getEventsHistory(
2    channelId: String,
3    startTimetoken: Timetoken? = nil,
4    endTimetoken: Timetoken? = nil,
5    count: Int = 100
6) async throws -> (events: [EventWrapper<EventContent>], isMore: Bool)

Input

* required

Parameter	Description
channelId * Type: String Default: n/a	Channel from which you want to pull historical messages.
startTimetoken Type: Timetoken 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: Timetoken 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
(events: [EventWrapper<EventContent>], isMore: Bool) Type: object	Returned object containing two fields: events and isMore.
→ events Type: Set<Event<EventContent>>	Array listing the requested number of historical events objects.
→ isMore Type: Bool	Info whether there are more historical events to pull.

Sample code

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

1// Define the custom payload type conforming to EventContent
2class CustomEventContent: EventContent, JSONCodable {
3  let chatID: String
4  let timestamp: String
5  let customerID: String
6  let triggerWord: String
7  
8  init(chatID: String, timestamp: String, customerID: String, triggerWord: String) {
9    self.chatID = chatID
10    self.timestamp = timestamp
11    self.customerID = customerID
12    self.triggerWord = triggerWord
13  }
14}
15

16// Pull historical events from the "CUSTOMER-SATISFACTION-CREW" channel with count of 10.
17// Assuming you have a reference of type "ChatImpl" named "chat"
18Task {
19  let historyResponse = try await chat.getEventsHistory(
20    channelId: "CUSTOMER-SATISFACTION-CREW",
21    count: 10
22  )
23  historyResponse.events.forEach { event in
24    if let customContent = event.event.payload as? CustomEventContent {
25      debugPrint("Custom payload: \(customContent)")
26      debugPrint("triggerWord: \(customContent.triggerWord)")
27    }
28  }
29}

show all 29 lines