---
source_url: https://www.pubnub.com/docs/sdks/windows-cpp/api-reference/presence
title: Presence API for Windows C++ SDK
updated_at: 2026-05-19T12:14:05.910Z
sdk_name: PubNub Windows C++ SDK
---

> 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 API for Windows C++ SDK

PubNub Windows C++ SDK

Presence lets you track who is online or offline and store custom state information. Presence shows:

* When a user has joined or left a channel
* How many users are subscribed to a particular channel (occupancy)
* Which channels a user or device is subscribed to
* Presence state associated with these users

Learn more about our Presence feature in the [Presence overview](https://www.pubnub.com/docs/general/presence/overview).

## Here now

:::warning Requires Presence
This method requires that the Presence add-on is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/). For information on how to receive presence events and what those events are, refer to [Presence Events](https://www.pubnub.com/docs/general/presence/presence-events#subscribe-to-presence-channel).
:::

This method returns information about the current state of a channel, including a list of unique user IDs (universally unique identifiers, UUIDs) currently subscribed to the channel and the total occupancy count of the channel.

:::note Cache
This method has a 3-second response cache time.
:::

### Method(s)

To call `Here Now` you can use the following method(s) in the Windows C++ SDK:

```cpp
here_now (std::string const &channel, std::string const &channel_group="")
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| channel | std::string | Yes |  | Specifies `channel` for which to return active uuids. |
| channel_group | std::string | Optional |  | Specifies `channel_group` for which to return active uuids. Wildcards are not supported. |

```cpp
here_now (std::vector<std::string> const &channel, std::vector<std::string> const &channel_group)
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: std::string const & | Specifies `channel` vector for which to return active uuids. |
| `channel_group` *Type: std::string const & | Specifies `channel_group` vector for which to return active uuids. Wildcards are not supported. |

### Sample code

#### Get a list of uuids subscribed to channel

```cpp
// Sync
void here_now(pubnub::context &pn) {
  enum pubnub_res res;

  res = pn.here_now("my_channel").await();

  if (PNR_OK == res) {
    std::cout << pn.get() << std::endl;
  } else {
    std::cout << "Here Now request failed" << std::endl;
  }
}

// Lambdas
void here_now(pubnub::context &pn) {
  pn.here_now("my_channel").then([=](https://www.pubnub.com/docs/pubnub::context &pn, pubnub_res res) {
      if (PNR_OK == res) {
        std::cout << pn.get() << std::endl;
      } else {
        std::cout << "Here Now request failed" << std::endl;
      }
    });
}

// Functions
void on_here_now(pubnub::context &pn, pubnub_res res) {
  if (PNR_OK == res) {
    std::cout << pn.get() << std::endl;
  } else {
    std::cout << "Here Now request failed" << std::endl;
  }
}

void here_now(pubnub::context &pn) {
  pn.here_now("my_channel").then(on_here_now);
}
```

### Rest response from server

The `here_now()` function returns a list of uuids currently subscribed to the channel.

* `uuids:["String","String", ... ,"String"]` - List of UUIDs currently subscribed to the channel.
* `occupancy: Number` - Total current occupancy of the channel.

```json
{
  "occupancy" : 4,
  "uuids" : "['123123234t234f34fq3dq', '143r34f34t34fq34q34q3', '23f34d3f4rq34r34rq23q', 'w34tcw45t45tcw435tww3']"
}
```

## Where now

:::warning Requires Presence
This method requires that the Presence add-on is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/). For information on how to receive presence events and what those events are, refer to [Presence Events](https://www.pubnub.com/docs/general/presence/presence-events#subscribe-to-presence-channel).
:::

This method returns the list of channels a UUID is subscribed to.

:::note Timeout events
If the app restarts (or the page refreshes) within the heartbeat window, no timeout event is generated.
:::

### Method(s)

To call `where_now()` you can use the following method(s) in the Windows C++ SDK:

```cpp
where_now (std::string const &uuid="")
```

| Parameter | Description |
| --- | --- |
| `uuid` *Type: std::string const & | Specifies `uuid` for which current subscribed channels info is required |

### Sample code

You simply need to define the `uuid` and the `callback` function to be used to send the data to as in the example below.

#### Get a list of channels a UUID is subscribed to

```cpp
//Sync
static void where_now(pubnub::context &pn) {
  enum pubnub_res res;

  try {
    res = pn.where_now("my_uuid").await();

    if (PNR_OK == res) {
      std::cout <<  pn.get() << std::endl;
    } else {
      std::cout << "Failed with code " << res << std::endl;
    }
  } catch (std::exception &ex) {
    std::cout << "Exception: " << ex.what() << std::endl;
  }
}

//Lambdas
static void where_now(pubnub::context &ipn) {
  ipn.where_now("my_uuid")
    .then([=](https://www.pubnub.com/docs/pubnub::context &pn, pubnub_res res) {
      if (PNR_OK == res) {
        std::cout <<  pn.get() << std::endl;
      } else {
        std::cout << "Failed with code " << res << std::endl;
      }
  });
}

//Functions
static void on_where_now(pubnub::context &pn, pubnub_res res) {
  if (PNR_OK == res) {
    std::cout <<  pn.get() << std::endl;
  } else {
    std::cout << "Failed with code " << res << std::endl;
  }
}

static void where_now(pubnub::context &ipn) {
  ipn.where_now("my_uuid").then(on_where_now);
}
```

### Rest response from server

The `where_now()` function returns a list of channels a uuid is subscribed to.

* `channels:["String","String", ... ,"String"]` - List of channels a uuid is subscribed to.

#### Example response

```json
{
    "channels": [
        "lobby",
        "game01",
        "chat"
    ]
}
```

## User state

:::warning Requires Presence
This method requires that the Presence add-on is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/). For information on how to receive presence events and what those events are, refer to [Presence Events](https://www.pubnub.com/docs/general/presence/presence-events#subscribe-to-presence-channel).
:::

Clients can set a dynamic custom state (score, game state, location) for their users on one or more channels and store it on a channel as long as the user stays subscribed.

The state is not persisted, and when the client disconnects, the state data is lost. For more information, refer to [Presence State](https://www.pubnub.com/docs/general/presence/presence-state).

### Method(s)

#### Set state

```cpp
set_state (std::string const &channel, std::string const &channel_group, std::string const &uuid, std::string const &state)
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: `std::string const &` | `Channel` to set state on |
| `channel_group` *Type: `std::string const &` | `Channel_group` to set state on |
| `uuid` *Type: `std::string const &` | `UUID` |
| `state` *Type: `std::string const &` | Serialized JSON `state` |

#### Set state with options

```cpp
set_state (std::string const &channel, const &state, set_state_options options )
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: `std::string const &` | `Channel` to set state on |
| `state` *Type: `std::string const &` | Serialized JSON `state` |
| `options` *Type: `set_state_options` | Extra options for this call. Refer to the section below for more information. |

##### set_state_options

| Parameter | Description |
| --- | --- |
| `channel_group`Type: `std::string` | The `string` with the `channel` name (or comma-delimited list of channel `group` names) to set `state` for. |
| `user_id` *Type: `std::string` | The `user_id` of the user for which to set `state` for. If `NULL`, the current `user_id` is used. |
| `heartbeat` *Type: `bool` | If set to `true`, you can set the state and make a heartbeat call at the same time via the `/heartbeat` endpoint. |

#### Get state

```cpp
state_get (std::string const &channel, std::string const &channel_group="", std::string const &uuid="")
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: `std::string const &` | `Channel` to get state. |
| `channel_group`Type: `std::string const &` | `Channel group` to get the state. |
| `uuid`Type: `std::string const &` | `UUID` |

### Sample code

#### Set state

```cpp
static void set_state(pubnub::context &pn) {
  enum pubnub_res res;

  try {
    std::string state("{\"first\":\"Robert\", \"last\":\"Plant\", \"age\":59, \"region\":\"UK\"}");
    res = pn.set_state("my_channel", "", "my_uuid", state).await();

    if (PNR_OK == res) {
      std::cout <<  pn.get() << std::endl;
    } else {
      std::cout << "Failed with code " << res << std::endl;
    }
  } catch (std::exception &ex) {
    std::cout << "Exception: " << ex.what() << std::endl;
  }
}
```

#### Set state with heartbeat

```cpp
std::cout << "Setting state with options" << std::endl;
  if (PNR_OK ==  pb.set_state(
      chan, "{\"x\":5}", pubnub::set_state_options().heartbeat(true)
    ).await()) {
      std::cout << "State was set: " << pb.get() << std::endl;
    }
    else {
        std::cout << "Setting state failed!" << std::endl;
    }
```

#### Get state

```cpp
static void get_state(pubnub::context &pn) {
  enum pubnub_res res;

  try {
    res = pn.state_get("my_channel", "", "my_uuid").await();

    if (PNR_OK == res) {
      std::cout <<  pn.get() << std::endl;
    } else {
      std::cout << "Failed with code " << res << std::endl;
    }
  } catch (std::exception &ex) {
    std::cout << "Exception: " << ex.what() << std::endl;
  }
}
```

### Returns

The state API returns a JSON object containing key value pairs.

```json
{
    first   : "Robert",
    last    : "Plant",
    age     : 59,
    region  : "UK"
}
```

## Heartbeat

:::warning Requires Presence
This method requires that the Presence add-on is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/). For information on how to receive presence events and what those events are, refer to [Presence Events](https://www.pubnub.com/docs/general/presence/presence-events#subscribe-to-presence-channel).
:::

This method notifies channels and channel groups about a client's presence. You can send heartbeats to channels you are not subscribed to.

### Method(s)

```cpp
pb.heartbeat(std::string const& channel, std::string const& channel_group)
```

| Parameter | Description |
| --- | --- |
| `channel`Type: std::string const& | The `string` with the `channel` name (or comma-delimited list of `channel` names) to notify. |
| `channel_group`Type: std::string const& | The `string` with the `channel_group` name (or comma-delimited list of channel `group` names) to notify. |

### Sample code

```c
res = pb.heartbeat(chan, NULL).await();
if (PNR_OK == res) {
    puts("Heartbeated! Got messages:");
}
else {
    printf("Heartbeating failed with code: %d('%s')\n",
            res,
            pubnub_res_2_string(res));
}
```

### Returns

This method returns a PubNub result enum or an error, depending on the status of the transaction.