Presence API for Python-Asyncio SDK

Presence lets you track which users and devices are online and store custom state. 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.

Here now

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

For information on how to receive presence events and what those events are, refer to Presence Events.

Use here_now() to get who is on a channel (UUIDs) and how many users are subscribed (occupancy).

Cache

This method has a 3-second response cache time.

Method(s)

Use the following method in the Python SDK:

pubnub.here_now() \
    .channels(String|List|Tuple) \
    .channel_groups(String|List|Tuple) \
    .include_state(Boolean) \
    .include_uuids(Boolean)

* required

Parameter	Description
channels Type: String | List | Tuple Default: None	Channels to query for details.
channel_groups Type: String | List | Tuple Default: None	Channel groups to query for details. Wildcards aren't supported.
include_state Type: Boolean Default: False	Whether the response should include the presence state for users on channels and channel groups.
include_uuids Type: Boolean Default: True	Whether the response should include the UUIDs of connected clients.

Sample code

Get a list of UUIDs subscribed to channel

Reference code

This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

import asyncio
import os
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub_asyncio import PubNubAsyncio
from pubnub.exceptions import PubNubException


async def get_here_now(pubnub: PubNubAsyncio):
    try:
        # Get a list of UUIDs subscribed to channels
        envelope = await pubnub.here_now() \
            .channels(['cool_channel1', 'cool_channel2']) \
            .include_uuids(True) \
            .future()

show all 46 lines

Returns

The here_now() operation returns a PNHereNowResult with the following fields:

Field	Type	Description
total_channels	Int	Total number of channels.
total_occupancy	Int	Total occupancy count across all channels.
channels	Dictionary	Dictionary mapping channel names (String) to PNHereNowChannelData objects.

PNHereNowChannelData

Field	Type	Description
channel_name	String	Channel name.
occupancy	Int	Occupancy of the channel.
occupants	List	List of PNHereNowOccupantData objects.

PNHereNowOccupantData

Field	Type	Description
uuid	String	UUID of the user.
state	Dictionary	Presence state for the user.

Returning state

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

For information on how to receive presence events and what those events are, refer to Presence Events.

envelope = await pubnub.here_now() \
    .channels("my_channel") \
    .include_uuids(True) \
    .include_state(True) \
    .future()

Example response

{
    total_channels: 1,
    channels: [{
        channel_name: "my_channel",
        occupancy: 1,
        occupants: [{
            uuid: "myUuid1"
            state: {
                "abcd": {
                    "age": 15
                }
            }
        }]
    }],
    total_occupancy: 1

show all 16 lines

Return occupancy only

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

For information on how to receive presence events and what those events are, refer to Presence Events.

To return only occupancy for a channel, set include_uuids and include_state to False:

envelope = await pubnub.here_now() \
    .channels("my_channel") \
    .include_uuids(False) \
    .include_state(False) \
    .future()

Example response

{
    total_channels: 1,
    channels: [{
        channel_name: "my_channel",
        occupancy: 3,
        occupants: []
    }],
    total_occupancy: 3
}

Here now for channel groups

envelope = await pubnub.here_now() \
    .channel_groups(['cg1', 'cg2', 'cg3']) \
    .include_uuids(True) \
    .include_state(True) \
    .future()

Example response

{
    total_channels: 1,
    channels: [
        {
            channel_name: "my_channel",
            occupancy: 1,
            occupants: [{
                uuid: "143r34f34t34fq34q34q3",
                state: None
            }]
        },
        {
            occupancy: 1,
            occupants: [{
                uuid: "123123234t234f34fq3dq",

show all 35 lines

Where now

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

For information on how to receive presence events and what those events are, refer to Presence Events.

Use where_now() to get the list of channels a UUID is subscribed to.

Timeout events

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

Method(s)

Use the following method in the Python SDK:

pubnub.where_now() \
    .uuid(String)

* required

Parameter	Description
uuid Type: String	uuid to get info on.

Sample code

envelope = await pubnub.where_now() \
    .future()

Returns

The where_now() operation returns a PNWhereNowResult which contains the following fields:

Field	Type	Description
channels	List	The list of channels where the UUID is present.

Other examples

Obtain information about the current list of channels of some other UUID

envelope = await pubnub.where_now() \
    .uuid('some-other-uuid') \
    .future()

User state

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

For information on how to receive presence events and what those events are, refer to Presence Events.

Clients can set a dynamic custom state (for example, score, game state, or location) for their users on one or more channels. The state exists while the user stays subscribed.

The state isn't persisted. When the client disconnects, the state is lost. For more information, refer to Presence State.

Presence state format

Presence state must be a dict. When calling set_state, supply an initialized, serializable dict.

Method(s)

Set state

pubnub.set_state() \
    .channels(String|List|Tuple) \
    .channel_groups(String|List|Tuple) \
    .state(Dictionary)

* required

Parameter	Description
channels Type: String | List | Tuple	channels to set state.
channel_groups Type: String | List | Tuple	channel groups to set state.
state Type: Dictionary	state to set.

Get state

pubnub.get_state() \
    .channels(String|List|Tuple) \
    .channel_groups(String|List|Tuple) \
    .uuid(String)

* required

Parameter	Description
channels Type: String | List | Tuple	channels to get state.
channel_groups Type: String | List | Tuple	channel groups to get state.
uuid Type: String	uuid to get state from.

Sample code

Set state

my_state = {
    'age': 20
}
envelope = await pubnub.set_state() \
    .channels(['ch1', 'ch2', 'ch3']) \
    .state(my_state) \
    .future()

Get state

envelope = await pubnub.get_state() \
    .channels(['ch1', 'ch2', 'ch3']) \
    .uuid('such_uuid') \
    .future()

Returns

The set_state() operation returns a PNSetStateResult which contains the following fields

Field	Type	Description
state	Dictionary	Dictionary of UUIDs and the user states.

The get_state() operation returns a PNGetStateResult which contains the following fields

Field	Type	Description
channels	Dictionary	Dictionary of channels and the user states.

Other examples

Set state for channels in channel group

my_state = {
    'age': 20
}
envelope = await pubnub.set_state().channel_groups(['gr1', 'gr2', 'gr3']).state(my_state).future()

The above code would return the following response to the client:

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