Friend List and Status Feed

Using Subscription Management features and the Presence service, you can create simple friend graphs and a status message feed. The friend graph is a simple follow/followers model. For anything more complex, such as a true multi-degree graph or an application that requires querying or traversing graphs, consider a specialized implementation that uses a graph database such as Neo4J or other more sophisticated data mechanisms; these types of use cases are fairly uncommon.

The essential feature required to implement this is the Channel Group feature, which can also be thought of as a Subscribe Group. A Channel Group groups channels into a persistent collection of channels that you can modify dynamically, and it allows you to subscribe to all these channels by subscribing to the group. Learn More about Channel Groups here.

Channel Group's multiplexing capabilities enables us to create friend lists and status feeds. The diagram and the steps to implement follow:

Subscribe for Status and Presence

User Identification

All Presence features use the User ID that's set on PubNub client initialization for tracking that client, which typically is the user. Refer to Managing User IDs to learn more.

User Channels

Every user will need two channels:

  • A channel the user publishes for their status messages.
  • A channel the user subscribes to, to indicate they're online. This channel will be unique for each user. For convenience, we'll use user-[letter], like user-a or user-b, as the unique identifier.

We'll follow this naming convention:

  • ch-user-a-status (publish)
  • ch-user-a-present (subscribe)

Status and Present Channels

These channels will be added into Channel Groups to enable the monitoring and aggregation of both status messages into a feed, and presence for online status. It's not required to do both if you only want to support friend lists/presence or you only want to support status feeds.

// Publish a status message
channel: "ch-user-a-status",
message: {
author: "user-a",
status: "I am reading about Advanced Channel Groups!",
timestamp: / 1000
function (status, response) {
if (status.error) {
else {
show all 19 lines

User Channel Groups

Each user will also have two channel groups:

  • A channel group for observing the online status of friends.
  • A channel group to receive status updates in real time.

Again, we'll use the same convention for unique user identifiers:

  • cg-user-a-friends
  • cg-user-a-status-feed

Two Channel Groups

Creating channel groups requires you to add at least one channel to the channel group. The easiest way to do this is add the user's present channel (ch-user-a-present) to each channel group.

Channel Group Management

You should only call the Add/Remove Channel to/from Channel Group APIs from your back-end server when a user registers for an account. Doing so from the client side reduces the security of your channels.

// Add ch-user-a-present to cg-user-a-friends
channels: ["ch-user-a-present"],
channelGroup: "cg-user-a-friends",
function(status) {
if (status.error) {
console.log("operation failed w/ status: ", status);
else {
console.log("Channel added to channel group");
show all 31 lines


Expanding the friend graph through friending is straightforward: you add channels to channel groups. When User A and User B become friends, you add each user's -present channel to the other's friend group, and add the -status channel to each user's status-feed group. Again, you should only call these APIs from your back-end server when you receive the friendship confirmation from both users.

Users Friends Group

User A and User B become friends:

// ************************************
// * User A and User B become friends
// ************************************

// Add User B to User A's groups: Add ch-user-b-present to cg-user-a-friends
channels: ["ch-user-b-present"],
channelGroup: "cg-user-a-friends"
function(status) {
if (status.error) {
console.log("operation failed w/ status: ", status);
else {
show all 67 lines


To see these working, it comes to how you subscribe. What is a bit different here is that you'll subscribe to one channel group for messages (status-feed) but subscribe to the other channel group's presence event channel group for the online/offline status of friends.

Friends Online/Offline

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.

For presence, we track the subscribers on a channel, and we create a side channel based on the channel name for all the presence events on the main channel. This side channel is the channel name + -pnpres. So for channel ch-user-a-present, the presence side channel is ch-user-a-present-pnpres and that is where PubNub publishes presence events that occur on ch-user-a-present.

The presence events are as follows:

  • join - client subscribed
  • leave - client unsubscribed
  • timeout - client disconnected without unsubscribing (occurs after the timeout period expires)
  • state-change - client changed the contents of the state object

And for each event, we also include the User ID and the channel occupancy (how many subscribers).

To see your friends online/offline status and be updated in real time, you subscribe to the friends channel group, but not directly. You subscribe to the presence event side channel group only, by appending -pnpres to the channel group name.

The reason you do not want to subscribe directly to the channel group is because Channel Groups are Subscribe groups, and therefore you would inadvertently subscribe to all of that users' friends' presence channels. We are only interested in the presence events of this channel group and not the message of those users.

Friends Presence

// Get the List of Friends
channelGroup: "cg-user-a-friends"
function (status, response) {
if (status.error) {
console.log("operation failed w/ error:", status);

console.log("FRIENDLIST: ")
response.channels.forEach( function (channel) {
show all 41 lines

Status Feed (Messages)

The status-feed channel group is much more straightforward, you're going to subscribe directly to the channel group and you'll receive status updates in real time via each channel in the channel group.

Status Feed

Since we include the user's present channel (ch-user-a-present) for this user in the channel group, this will also have the net effect of subscribing to that channel. It also means it generates a join event for every channel group that includes this user's present channel. So, if User B is friends with User A, when User A subscribes to this status-feed channel group, it also subscribes to User A's present channel and generates that join event, in addition to all the other presence events.

Friend List Only Implementation

If you're implementing only the friend list and not the status feed, User A will need to subscribe to this ch-user-a-present channel directly since User A isn't subscribing to the status feed group which includes this channel.

message: function(message) {
console.log("STATUS: ", message);

// Get Status Feed Messages
pubnub.subscribe({channelGroups: ["cg-user-a-status-feed"]});

Retrieve History

Retrieving history of status messages can be a bit more work as you have to retrieve messages from each channel in the group individually (each friend) and mash/sort them together client side. You can retrieve message from multiple channels in a single request, but you still have to mash/sort them together when you get those messages.

Complex Use Cases

There are other complex use cases of changing status feeds that can make things a bit trickier, one is weighting the status message, so that it's no longer chronological, but rather based on interests, or activity, or other things. Another layer of complexity that you can add is commenting on status items. Again, it requires a bit more logic here, and PubNub has some additional features, like Message Reactions, that will provide some assistance.


Simple and powerful friend graphs are fairly easy to do with PubNub. It's much easier than trying to develop a full back end to support the presence and status feeds, and on top of that, it's real-time.

Last updated on