---
source_url: https://www.pubnub.com/docs/general/presence/presence-state
title: Presence State
updated_at: 2026-06-16T12:49:41.126Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# 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](https://www.pubnub.com/docs/general/metadata/basics).

PubNub also sends presence `state-change` events when the user's state changes. Subscribe to presence channels to receive these events. See [Presence Events](https://www.pubnub.com/docs/general/presence/presence-events).

:::note 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](https://www.pubnub.com/docs/general/setup/users-and-devices#set-the-user-id).
:::

## 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

```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

```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

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

### Java

```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#

```csharp
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);
    }
  }
));
```

### Python

```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

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

### Swift

```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

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

  if (!status) {

  }
  else {

  }
}];
```

### Java

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

### C#

```csharp
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

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

## Terms in this document

* **Channel** - A pathway for sending and receiving messages between devices, created automatically when you first use it, that can handle any number of users and messages for different communication needs, like 1-1 text chats, group conversations, and other data streaming.
* **PubNub** - PubNub is a real-time messaging platform that provides APIs and SDKs for building scalable applications. It handles the complex infrastructure of real-time communication, including: Message delivery and persistence, Presence detection, Access control, Push notifications, File sharing, Serverless processing with Functions and Events & Actions, Analytics and monitoring with BizOps Workspace, AI-powered insights with Illuminate.