Presence State

You can set dynamic, custom state for users on one or more channels. PubNub stores this state on each channel while the user remains subscribed.

Typical examples include score, game status, or frequently changing location.

The state is transient. PubNub does not persist it. When the client disconnects, the state is cleared. If you need a user's state after reconnect, cache it locally. For long‑term storage, see App Context.

PubNub also sends presence state-change events when the user's state changes. Subscribe to presence channels to receive these events. See Presence Events.

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.

Set Presence state

You can set state for a User ID on channel(s) or channel group(s). By default, PubNub uses the current client's User ID. When you set state on a channel group, PubNub applies it to all channels in that group.

JavaScript

pubnub.setState(
  {
    state: {"mood":"pumped", "isTyping":false},
    channels: ["chats.room1"],
    channelGroups: ["cg_user123_friends"]
  },
  function (status, response) {
    if (status.isError) {
      console.log(status);
    }
    else {
      console.log(response);
    }
  }
);

Swift

pubnub.setPresence(
  state: ["mood": "pumped", "workingFrom": "Home"],
  on: ["chats.room1"],
  and: ["cg_user123_friends"]
) { result in
  switch result {
    case let .success(response):
      print("Successful Set State Response: \(response)")

    case let .failure(error):
      print("Failed Set State Response: \(error.localizedDescription)")
  }
}

Objective-C

[self.pubnub setState: @{@"mood": @"pumped", @"workingFrom": @"Home"}
      forUUID:self.pubnub.uuid onChannel: @"chats.room1"
      withCompletion:^(PNClientStateUpdateStatus *status) {
    // handle status
}];

Java

JsonObject state = new JsonObject();
state.addProperty("mood", "pumped");
state.addProperty("workingFrom", "Home");

pubnub.setPresenceState()
  .channels(Arrays.asList("chats.room1"))
  .channelGroups(Arrays.asList("cg_user123_friends"))
  .state(state)
  .async(result -> { /* check result */ });

C#

Dictionary<string, object> state = new Dictionary<string, object>();
state.Add("mood", "pumped");
state.Add("workingFrom", "Home");

pubnub.SetPresenceState()
  .Channels(new string[] {"chats.room1"})
  .ChannelGroups(new string[] {"cg_user123_friends"})
  .State(myState)
  .Execute(new PNSetStateResultExt((result, status) => {
    if (status.IsError()) {
      Console.WriteLine("SetPresenceState error:" + status);
    }
    else {
      Console.WriteLine("SetPresenceState success:" + result);
    }

show all 17 lines

Python

my_state = {"mood": "pumped", "workingFrom": "Home"}

envelope = pubnub.set_state()\
  .channels(["chats.room1"]) \
  .channel_groups(["cg_user123_friends"])\
  .state(my_state)\
  .sync()

When you set state for a client, PubNub overwrites the entire existing state. To update part of the state, send the full state payload. Keep state payloads small for efficiency.

Get Presence state

You can get state data for any client on a given channel(s) or channel group(s) using the Get State API. This is useful to get the state of other clients based on their User ID.

JavaScript

pubnub.getState(
  {
    uuid: "anotherClientUserID",
    channels: ["chats.room1"],
    channelGroups: ["cg_user123_friends"]
  },
  function (status, response) {
    // handle status, response
  }
);

Swift

pubnub.getPresenceState(
  for: "anotherClientUserId",
  on: ["chats.room1"],
  and: ["cg_user123_friends"]
) { result in
  switch result {
  case let .success(response):
    print("Successful Get State Response: \(response)")

  case let .failure(error):
    print("Failed Get State Response: \(error.localizedDescription)")
  }
}

Objective-C

 [self.pubnub stateForUUID:@"anotherClientUUID" onChannel:@"chats.room1"
      withCompletion:^(PNChannelClientStateResult *result, PNErrorStatus *status) {

  if (!status) {

  }
  else {

  }
}];

Java

pubnub.getPresenceState()
  .channels(Arrays.asList("chats.room1"))
  .channelGroups(Arrays.asList("cg_user123_friends"))
  .uuid("anotherClientUserId")
  .async(result -> { /* check result */ });

C#

pubnub.GetPresenceState()
  .Channels(new string[] {"chats.room1"})
  .Uuid(clientUserId)
  .Execute(new PNGetStateResultExt((result, status) => {
    if (status.IsError()) {
      Console.WriteLine("GetPresenceState error:" + status);
    }
    else {
      Console.WriteLine("GetPresenceState success:" + result);
    }
  }
));

Python

envelope = pubnub.get_state()\
  .uuid("anotherClientUserId")\
  .channels(["chats.room1"])\
  .sync()