Listen for 'Presence' messages on a specified channel, such as 'join' and 'leave' events.

Presence and Subscribe are very similar. The only difference is the channel you subscribe to. For example, if the channel you wish to receive presence events on is called hello_world , then you would subscribe to the channel named hello_world-pnpres.

For any given channel CHANNEL_NAME, CHANNEL_NAME-pnpres is the 'Presence' channel for CHANNEL_NAME.

It is important that when your subscribers subscribe to a channel, that they include the ?uuid= parameter at the end of the subscribe request. Otherwise, PubNub will not have an identifier for the subscriber, and therefore will not be able to return presence information for that subscriber.

Refer to this link for more information on the Subscribe service:

Monitoring the active/inactive state of a channel

By request, PubNub support staff can configure channel activity state monitoring for your account:

A channel becomes active when occupancy goes from 0 to >= 1 and becomes inactive with occupancy goes from >=1 to 0. If configured, a notification of this change of state is published to a channel of your choosing and/or PubNub will make a callback to your application server at the URL you configure.

You application server can have different callbacks for active and inactive. To receive these events via POST, your web server must accept a POST request with the following parameters:

sub_key : string
channel : string
status : string
timestamp : long int

PubNub messaging notifying you of a channel becoming active would resemble:

{    "channel":"my_channel",     "status":"active",     "timestamp":12323425345}


Where channel is the channel name, status is either active or inactive, and timestamp is the time the event occured, expressed as a PubNub timetoken value.

Advanced Options

By request, the following advanced presence options can be configured by PubNub support staff for your account:

presence_announce_max : the maximum number of occupants in a channel before it switches to interval announcements

presence_cb_active : the HTTP callback URL that is triggered when a channel becomes active

presence_cb_inactive: the HTTP callback URL that is triggered when a channel becomes inactive

presence_interval : when in interval announce mode, the number of seconds between each announcement

presence_active_notice_channel : the pubnub channel where active/inactive channel notifications are published

Success Response

There are three possible presence action types in presence. They are Join, Leave, and Timeout.

A Join action occurs when a new UUID registers against subscribe with a timetoken of 0, and then subsequently subscribes to the current timetoken (Subscribes new to a channel):

{"action":"join", "timestamp":1357898972, "uuid":"2b0ff52b-3ceb-48b2-8a1e-ea9d53efe461", "occupancy":1}

A Leave action occurs when an existing UUID explicitly leaves a channel by tearing down his subscribe connection to PubNub (Leaves a channel).

{"action":"leave", "timestamp":1357899331, "uuid":"bd86583d-fb5b-481a-b343-72f67f445484", "occupancy":1}

A Timeout action occurs when an existing UUID implicitly leaves a channel, and the system does not receive any further subscribe requests from that UUID. This can happen whenever a user does not explicitly unsubscribe, but is not longer connected to PubNub.

{"action":"timeout", "timestamp":1357899778, "uuid":"1234568901", "occupancy":1}

In the above example responses:

action is the event type.

timestamp is the time at which the action occurred, expressed as a PubNub timetoken.

uuid is the action owner's UUID subscribe parameter.

occupancy is the current number of subscribers in the channel as of this action notification.

Failure Response

[0,"Error description here"]