Receive Messages

Messages sent through PubNub are no different from any other PubNub event. They are only structured differently.

Receiving messages (or any other events for that matter) is a three-step process:

  1. Create an entity

    Entity

    A subscribable object within a PubNub SDK that allows you to perform context-specific operations.
    -based subscription or a subscription set.
  2. Implement the appropriate event listener.
  3. Subscribe to the subscription to start receiving real-time updates.
Entity-enabled SDKs

Not all PubNub SDKs currently support entities. For the SDKs that still use the legacy event listeners and Subscribe API, the information about the API remains in their respective SDK API docs.

Refer to each SDK's API documentation for more information.

Add an event handler

Messages and events are received in your app using event handlers (also called listeners). In those listeners, you add the logic for handling all received messages, signals, files, and events.

Add listeners to subscriptions and subscription sets for specific or multiple subscriptions simultaneously.

There are four entities:

Each type of message or event has its own handler to receive them where you implement your custom app logic to do something useful with the received data.

Once you no longer need to handle events in your app, you can remove a listener using a corresponding SDK method. See Javascript SDK as an example.

The following handlers are available to you:

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

// Event-specific listeners
subscription.
// Messages
onMessage(onMessagelistener: (messageEvent) => void)
// Presence
onPresence(onPresencelistener: (presenceEvent) => void)
// Signals
onSignal(onSignalListener: (signalEvent) => void)
// App Context
onObjects(onObjectsListener: (objectsEvent) => void)
// Message Reactions
onMessageAction(messageActionEventListener: (messageActionEvent) => void)
// File Sharing
onFile(fileEventListener: (fileEvent) => void)

show all 77 lines

The following is an overview of each of the event listeners. Details about the data passed to the handlers' parameters will be explained in the API sections of the associated handlers.

HandlerDescription
StatusReceives events when the client successfully connects (subscribes), or reconnects (in case of connection issues) to channels. For other error events that can be received by the Status handler, refer to Connection Management and to the tip that follows this table.

In entity-enabled SDKs, you can only add this listener to the pubnub object, not to an individual subscription.
MessageReceives all messages published to all the channels subscribed by the client. The event payload will contain the published message data, publish timetoken, the User ID of the client that published the message and more. Refer to Publish Messages.
SignalReceives all signals that are sent to any channels subscribed by the client. The event payload will contain the signal data, signal timetoken, the User ID of the client that published the message and more. Refer to Send Signals.
PresenceReceives all presence events that are triggered on any channels subscribed by the client. The event payload will contain the presence event type (join, leave, timeout, state-change), timetoken of the action, the User ID of the client that caused the event, state data (if applicable) and more. Refer to Detect Presence.
MessageActionReceives all events when existing messages are annotated (by an action) for any channels subscribed by the client. The event payload will contain the User ID that acted on the message, message reaction type (such as an emoji reaction), timetoken of the annotated message, timetoken of the action, action value and more. Refer to Message Reactions.
ObjectsReceives all objects events that are emitted when a channel, channel membership, or user metadata is created, updated or removed. Refer to Channel Metadata, User Metadata, and Membership Metadata.
Status event handling

For more information on how the SDKs handle status events, refer to SDK troubleshooting and status event references.

Last updated on