---
source_url: https://www.pubnub.com/docs/sdks/freertos/api-reference/presence
title: Presence API for FreeRTOS SDK
updated_at: 2026-06-18T11:27:33.819Z
sdk_name: PubNub FreeRTOS 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 FreeRTOS SDK

PubNub FreeRTOS 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 FreeRTOS SDK:

```c
enum pubnub_res pubnub_here_now (pubnub_t *p, const char *channel, const char *channel_group)
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| p | pubnub_t* | Yes |  | Pointer to PubNub client context. |
| channel | const | Optional |  | The `string` with the `channel` name (or comma-delimited list of `channel` names) to get `presence` info for. |
| channel_group | const | Optional |  | The `string` with the `channel` name (or comma-delimited list of channel `group` names) to get `presence` info for. Wildcards are not supported. |

### Sample code

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

```c
// Sync
char const *chan = "my_channel";
char const *msg;
enum pubnub_res res;

res = pubnub_here_now(pn, chan, NULL);
if (res != PNR_STARTED) {
  return -1;
}

res = pubnub_await(pn);
if (res == PNR_STARTED) {
  return -1;
}

if (PNR_OK == res) {
  msg = pubnub_get(pn);
  // Print out, on Windows simulator `puts(msg)` should work
} else {
  return -1;
}

return 0;

//callback

int start_here_now(pubnub_t *pn) {
  char const *chan = "my_channel";
  if (PNR_STARTERD != pubnub_here_now(pn, chan, NULL)) {
    return -1;
  }
  return 0;
}
int receive_here_now(pubnub_t *pn, enum pubnub_res res) {
  char const *msg;
  if (res == PNR_STARTED) {
    return -1;
  }

  if (PNR_OK == res) {
    msg = pubnub_get(pn);
  // Print out, on Windows simulator `puts(msg)` should work
  } else {
    return -1;
  }

  return 0;
}
```

### Rest response from server

The `pubnub_here_now()` function returns a list of uuid s 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 pubnub_where_now() you can use the following method(s) in the FreeRTOS SDK:

```c
enum pubnub_res pubnub_where_now (pubnub_t *p, const char *uuid)
```

| Parameter | Description |
| --- | --- |
| `p` *Type: pubnub_t* | Pointer to PubNub client context. |
| `uuid`Type: const char* | The `UUID` of the user to get the `channel` presence. If `NULL`, the current `UUID` of the `p` context will be used. |

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

```c
// Sync

char const *msg;
enum pubnub_res res;

res = pubnub_where_now(pn, "my_uuid");
if (res != PNR_STARTED) {
  return -1;
}

res = pubnub_await(pn);
if (res == PNR_STARTED) {
  return -1;
}

if (PNR_OK == res) {
  msg = pubnub_get(pn);
  // Print out, on Windows simulator `puts(msg)` should work
} else {
  return -1;
}

return 0;

// Callback

int start_where_now(pubnub_t *pn) {
  return PNR_STARTED == pubnub_where_now(pn, "my_uuid") ? 0 : -1;
}
int receive_where_now(pubnub_t *pn, enum pubnub_res res) {
  if (PNR_OK == res) {
    char const* msg = pubnub_get(pn);
  // Print out, on Windows simulator `puts(msg)` should work
  } else {
    return -1;
  }
  return 0;
}
```

### Rest response from server

The pubnub_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

```c
enum pubnub_res pubnub_set_state (pubnub_t *p, char const *channel, char const *channel_group, const char *uuid, char const *state)
```

| Parameter | Description |
| --- | --- |
| `p` *Type: pubnub_t* | Pointer to PubNub client context. |
| `channel`Type: char const* | The `string` with the `channel` name (or comma-delimited list of `channel` names) to set `state` for. |
| `channel_group`Type: char const* | The `string` with the `channel` name (or comma-delimited list of channel `group` names) to set `state` for. |
| `uuid` *Type: const char* | The `UUID` of the user for which to set `state` for. If `NULL`, the current `UUID` of the `p` context will be used. |
| `state` *Type: char const* | Has to be a JSON object |

#### Get state

```c
enum pubnub_res pubnub_state_get (pubnub_t *p, char const *channel, char const *channel_group, const char *uuid)
```

| Parameter | Description |
| --- | --- |
| `p` *Type: pubnub_t* | Pointer to Pubnub Client Context |
| `channel`Type: char const* | The string with the `channel` name (or comma-delimited list of channel names) to get the state for. |
| `channel_group`Type: char const* | The string with the `channel` name (or comma-delimited list of `channel group` names) to get the `state` for. |
| `uuid`Type: const char* | The `UUID` of the user for which to get the `state` for. If NULL, the current `UUID` of the `p` context will be used. |

### Sample code

#### Set state

```c
pubnub_set_state(ctx, "hello_world", NULL, NULL, NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
    printf("Set success\n");
}
```

#### Get state

```c
pubnub_get_state(ctx, "my_channel", NULL, NULL);
pbresult = pubnub_await(ctx);
if (PNR_OK == pbresult) {
    char const *json_response = pubnub_get(ctx);
}
```

### Returns

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

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