Welcome to PubNub’s documentation!

Pubnub

class pubnub.Pubnub(publish_key, subscribe_key, secret_key=None, cipher_key=None, auth_key=None, ssl_on=False, origin='pubsub.pubnub.com', uuid=None, pooling=True, daemon=False, pres_uuid=None, azure=False)
audit(channel=None, channel_group=None, auth_key=None, callback=None, error=None)

Method for fetching permissions from pubnub servers.

This method provides a mechanism to reveal existing PubNub Access Manager attributes for any combination of subscribe_key, channel and auth_key.

Args:
channel: (string) (optional)
Specifies channel name to return PAM attributes optionally in combination with auth_key. If channel/channel_group is not specified, results for all channels associated with subscribe_key are returned. If auth_key is not specified, it is possible to return results for a comma separated list of channels.
channel_group: (string) (optional)
Specifies channel group name to return PAM attributes optionally in combination with auth_key. If channel/channel_group is not specified, results for all channels associated with subscribe_key are returned. If auth_key is not specified, it is possible to return results for a comma separated list of channels.
auth_key: (string) (optional)
Specifies the auth_key to return PAM attributes for. If only a single channel is specified, it is possible to return results for a comma separated list of auth_keys.
callback: (function) (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (function) (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a dict in sync mode i.e. when callback argument is not given The dict returned contains values with keys ‘message’ and ‘payload’

Sample Response:

{
    "message":"Success",
    "payload":{
        "channels":{
            "my_channel":{
                "auths":{"my_ro_authkey":{"r":1,"w":0},
                "my_rw_authkey":{"r":0,"w":1},
                "my_admin_authkey":{"r":1,"w":1}
            }
        }
    },
}

Usage:

pubnub.audit (‘my_channel’); # Sync Mode
channel_group_list_channels(channel_group, callback=None, error=None)

Get list of channels for a group.

Using this method, list of channels for a group, can be obtained.

Args:
channel_group: (string) (optional)
Channel Group name. It can also contain namespace. If namespace is also specified, then the parameter will be in format namespace:channel_group
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
Returns:

Sync Mode: dict channel_group_list_channels method returns a dict which contains list of channels in payload field:

{
    u'status': 200,
    u'payload': {"channels": ["hi"], "group": "abcd"},
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_list_channels gets the a dict containing list of channels under payload field:

{
    u'payload': {"channels": ["hi"], "group": "abcd"}
}
channel_group_list_groups(namespace=None, callback=None, error=None)

Get list of groups.

Using this method, list of groups for the subscribe key associated with PubNub object, can be obtained. If namespace is provided, groups within the namespace only are listed

Args:

namespace: (string) (optional) namespace

callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: dict

channel_group_list_groups method returns a dict which contains list of groups in payload field:

{
    u'status': 200,
    u'payload': {"namespace": "dev", "groups": ["abcd"]},
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_list_namespaces gets the a dict containing list of groups under payload field:

{
    u'payload': {"namespace": "dev", "groups": ["abcd"]}
}
channel_group_list_namespaces(callback=None, error=None)

Get list of namespaces.

You can obtain list of namespaces for the subscribe key associated with PubNub object using this method.

Args:
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
Returns:

Sync Mode: dict

channel_group_list_namespaces method returns a dict which contains list of namespaces in payload field:

{
    u'status': 200,
    u'payload': {
        u'sub_key': u'demo',
        u'namespaces': [u'dev', u'foo']
    },
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None (callback gets the response as parameter)

Response Format:

The callback passed to channel_group_list_namespaces gets the a dict containing list of namespaces under payload field:

{
    u'payload': {
        u'sub_key': u'demo',
        u'namespaces': [u'dev', u'foo']
    }
}

namespaces is the list of namespaces for the given subscribe key

channel_group_remove_channel(channel_group, channel, callback=None, error=None)

Remove channel.

A channel can be removed from a group method.

Args:
channel_group: (string)
Channel Group name. It can also contain namespace. If namespace is also specified, then the parameter will be in format namespace:channel_group
channel: (string)
Can be a channel name, a list of channel names, or a comma separated list of channel names
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: dict

channel_group_remove_channel method returns a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_remove_channel gets the a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}
channel_group_remove_group(channel_group, callback=None, error=None)

Remove channel group.

A channel group can be removed using this method.

Args:
channel_group: (string)
Channel Group name. It can also contain namespace. If namespace is also specified, then the parameter will be in format namespace:channel_group
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
Returns:

Sync Mode: dict

channel_group_remove_group method returns a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_remove_group gets the a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}
channel_group_remove_namespace(namespace, callback=None, error=None)

Remove a namespace.

A namespace can be deleted using this method.

Args:

namespace: (string) namespace to be deleted

callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: dict

channel_group_remove_namespace method returns a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_list_namespaces gets the a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}
decrypt(message)

Method for decrypting data.

This method takes ciphertext as input and returns decrypted data. This need not be called directly as enncryption/decryption is taken care of transparently by Pubnub class if cipher key is provided at time of initializing pubnub object

Args:
message: Message to be decrypted.
Returns:
Returns decrypted message if cipher key is set
encrypt(message)

Method for encrypting data.

This method takes plaintext as input and returns encrypted data. This need not be called directly as enncryption/decryption is taken care of transparently by Pubnub class if cipher key is provided at time of initializing pubnub object

Args:
message: Message to be encrypted.
Returns:
Returns encrypted message if cipher key is set
grant(channel=None, channel_group=None, auth_key=False, read=False, write=False, manage=False, ttl=5, callback=None, error=None)

Method for granting permissions.

This function establishes subscribe and/or write permissions for PubNub Access Manager (PAM) by setting the read or write attribute to true. A grant with read or write set to false (or not included) will revoke any previous grants with read or write set to true.

Permissions can be applied to any one of three levels:
  1. Application level privileges are based on subscribe_key applying to all associated channels.
  2. Channel level privileges are based on a combination of subscribe_key and channel name.
  3. User level privileges are based on the combination of subscribe_key, channel and auth_key.
Args:
channel: (string) (optional)
Specifies channel name to grant permissions to. If channel/channel_group is not specified, the grant applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to grant permissions to multiple channels simultaneously by specifying the channels as a comma separated list.
channel_group: (string) (optional)
Specifies channel group name to grant permissions to. If channel/channel_group is not specified, the grant applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to grant permissions to multiple channel groups simultaneously by specifying the channel groups as a comma separated list.
auth_key: (string) (optional)
Specifies auth_key to grant permissions to. It is possible to specify multiple auth_keys as comma separated list in combination with a single channel name. If auth_key is provided as the special-case value “null” (or included in a comma-separated list, eg. “null,null,abc”), a new auth_key will be generated and returned for each “null” value.
read: (boolean) (default: True)
Read permissions are granted by setting to True. Read permissions are removed by setting to False.
write: (boolean) (default: True)
Write permissions are granted by setting to true. Write permissions are removed by setting to false.
manage: (boolean) (default: True)
Manage permissions are granted by setting to true. Manage permissions are removed by setting to false.
ttl: (int) (default: 1440 i.e 24 hrs)
Time in minutes for which granted permissions are valid. Max is 525600 , Min is 1. Setting ttl to 0 will apply the grant indefinitely.
callback: (function) (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (function) (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a dict in sync mode i.e. when callback argument is not given The dict returned contains values with keys ‘message’ and ‘payload’

Sample Response:

{
    "message":"Success",
    "payload":{
        "ttl":5,
        "auths":{
            "my_ro_authkey":{"r":1,"w":0}
        },
        "subscribe_key":"my_subkey",
        "level":"user",
        "channel":"my_channel"
    }
}
here_now(channel, uuids=True, state=False, callback=None, error=None)

Get here now data.

You can obtain information about the current state of a channel including a list of unique user-ids currently subscribed to the channel and the total occupancy count of the channel by calling the here_now() function in your application.

Args:
channel: (string) (optional)
Specifies the channel name to return occupancy results. If channel is not provided, here_now will return data for all channels.
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: list Async Mode: None

Response Format:

The here_now() method 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.

Example Response:

{
    occupancy: 4,
    uuids: [
        '123123234t234f34fq3dq',
        '143r34f34t34fq34q34q3',
        '23f34d3f4rq34r34rq23q',
        'w34tcw45t45tcw435tww3',
    ]
}
history(channel, count=100, reverse=False, start=None, end=None, include_token=False, callback=None, error=None)

This method fetches historical messages of a channel.

PubNub Storage/Playback Service provides real-time access to an unlimited history for all messages published to PubNub. Stored messages are replicated across multiple availability zones in several geographical data center locations. Stored messages can be encrypted with AES-256 message encryption ensuring that they are not readable while stored on PubNub’s network.

It is possible to control how messages are returned and in what order, for example you can:

Return messages in the order newest to oldest (default behavior).

Return messages in the order oldest to newest by setting reverse to true.

Page through results by providing a start or end time token.

Retrieve a “slice” of the time line by providing both a start and end time token.

Limit the number of messages to a specific quantity using the count parameter.

Args:
channel: (string)
Specifies channel to return history messages from
count: (int) (default: 100)
Specifies the number of historical messages to return
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a list in sync mode i.e. when callback argument is not given

Sample Response:
[[“Pub1”,”Pub2”,”Pub3”,”Pub4”,”Pub5”],13406746729185766,13406746845892666]
presence(channel, callback, error=None, connect=None, disconnect=None, reconnect=None)

Subscribe to presence events on a channel.

Only works in async mode
Args:

channel: Channel name ( string ) on which to listen for events

callback: A callback method should be passed as parameter.
If passed, the api works in async mode. Required argument when working with twisted or tornado .
error: Optional variable. An error method can be passed as parameter.
If set, the api works in async mode.
Returns:
None
presence_group(channel_group, callback, error=None, connect=None, disconnect=None, reconnect=None)

Subscribe to presence events on a channel group.

Only works in async mode
Args:

channel_group: Channel group name ( string )

callback: A callback method should be passed to the method.
If passed, the api works in async mode. Required argument when working with twisted or tornado .
error: Optional variable. An error method can be passed as parameter.
If passed, the api works in async mode.
Returns:
None
publish(channel, message, callback=None, error=None)

Publishes data on a channel.

The publish() method is used to send a message to all subscribers of a channel. To publish a message you must first specify a valid publish_key at initialization. A successfully published message is replicated across the PubNub Real-Time Network and sent simultaneously to all subscribed clients on a channel.

Messages in transit can be secured from potential eavesdroppers with SSL/TLS by setting ssl to True during initialization.

Published messages can also be encrypted with AES-256 simply by specifying a cipher_key during initialization.

Args:
channel: (string)
Specifies channel name to publish messages to.
message: (string/int/double/dict/list)
Message to be published
callback: (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
Returns:

Sync Mode : list Async Mode : None

The function returns the following formatted response:

[ Number, “Status”, “Time Token”]

The output below demonstrates the response to a successful call:

[1,”Sent”,”13769558699541401”]
revoke(channel=None, channel_group=None, auth_key=None, ttl=1, callback=None, error=None)

Method for revoking permissions.

Args:
channel: (string) (optional)
Specifies channel name to revoke permissions to. If channel/channel_group is not specified, the revoke applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to grant permissions to multiple channels simultaneously by specifying the channels as a comma separated list.
channel_group: (string) (optional)
Specifies channel group name to revoke permissions to. If channel/channel_group is not specified, the grant applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to revoke permissions to multiple channel groups simultaneously by specifying the channel groups as a comma separated list.
auth_key: (string) (optional)
Specifies auth_key to revoke permissions to. It is possible to specify multiple auth_keys as comma separated list in combination with a single channel name. If auth_key is provided as the special-case value “null” (or included in a comma-separated list, eg. “null,null,abc”), a new auth_key will be generated and returned for each “null” value.
ttl: (int) (default: 1440 i.e 24 hrs)
Time in minutes for which granted permissions are valid. Max is 525600 , Min is 1. Setting ttl to 0 will apply the grant indefinitely.
callback: (function) (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (function) (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a dict in sync mode i.e. when callback argument is not given The dict returned contains values with keys ‘message’ and ‘payload’

Sample Response:

{
    "message":"Success",
    "payload":{
        "ttl":5,
        "auths":{
            "my_authkey":{"r":0,"w":0}
        },
        "subscribe_key":"my_subkey",
        "level":"user",
        "channel":"my_channel"
    }
}
subscribe(channels, callback, state=None, error=None, connect=None, disconnect=None, reconnect=None, sync=False)

Subscribe to data on a channel.

This function causes the client to create an open TCP socket to the PubNub Real-Time Network and begin listening for messages on a specified channel. To subscribe to a channel the client must send the appropriate subscribe_key at initialization.

Only works in async mode

Args:
channel: (string/list)
Specifies the channel to subscribe to. It is possible to specify multiple channels as a comma separated list or andarray.
callback: (function)
This callback is called on receiving a message from the channel.
state: (dict)
State to be set.
error: (function) (optional)
This callback is called on an error event
connect: (function) (optional)
This callback is called on a successful connection to the PubNub cloud
disconnect: (function) (optional)
This callback is called on client disconnect from the PubNub cloud
reconnect: (function) (optional)
This callback is called on successfully re-connecting to the PubNub cloud
Returns:
None
subscribe_group(channel_groups, callback, error=None, connect=None, disconnect=None, reconnect=None, sync=False)

Subscribe to data on a channel group.

This function causes the client to create an open TCP socket to the PubNub Real-Time Network and begin listening for messages on a specified channel. To subscribe to a channel group the client must send the appropriate subscribe_key at initialization.

Only works in async mode

Args:
channel_groups: (string/list)
Specifies the channel groups to subscribe to. It is possible to specify multiple channel groups as a comma separated list or andarray.
callback: (function)
This callback is called on receiving a message from the channel.
error: (function) (optional)
This callback is called on an error event
connect: (function) (optional)
This callback is called on a successful connection to the PubNub cloud
disconnect: (function) (optional)
This callback is called on client disconnect from the PubNub cloud
reconnect: (function) (optional)
This callback is called on successfully re-connecting to the PubNub cloud
Returns:
None
time(callback=None)

This function will return a 17 digit precision Unix epoch.

Args:

callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a 17 digit number in sync mode i.e. when callback argument is not given

Sample:
13769501243685161
unsubscribe(channel)
Unsubscribe from channel .
Only works in async mode
Args:
channel: Channel name ( string )
unsubscribe_group(channel_group)
Unsubscribe from channel group.
Only works in async mode
Args:
channel_group: Channel group name ( string )

PubnubTwisted

class pubnub.PubnubTwisted(publish_key, subscribe_key, secret_key=None, cipher_key=None, auth_key=None, ssl_on=False, origin='pubsub.pubnub.com')
audit(channel=None, channel_group=None, auth_key=None, callback=None, error=None)

Method for fetching permissions from pubnub servers.

This method provides a mechanism to reveal existing PubNub Access Manager attributes for any combination of subscribe_key, channel and auth_key.

Args:
channel: (string) (optional)
Specifies channel name to return PAM attributes optionally in combination with auth_key. If channel/channel_group is not specified, results for all channels associated with subscribe_key are returned. If auth_key is not specified, it is possible to return results for a comma separated list of channels.
channel_group: (string) (optional)
Specifies channel group name to return PAM attributes optionally in combination with auth_key. If channel/channel_group is not specified, results for all channels associated with subscribe_key are returned. If auth_key is not specified, it is possible to return results for a comma separated list of channels.
auth_key: (string) (optional)
Specifies the auth_key to return PAM attributes for. If only a single channel is specified, it is possible to return results for a comma separated list of auth_keys.
callback: (function) (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (function) (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a dict in sync mode i.e. when callback argument is not given The dict returned contains values with keys ‘message’ and ‘payload’

Sample Response:

{
    "message":"Success",
    "payload":{
        "channels":{
            "my_channel":{
                "auths":{"my_ro_authkey":{"r":1,"w":0},
                "my_rw_authkey":{"r":0,"w":1},
                "my_admin_authkey":{"r":1,"w":1}
            }
        }
    },
}

Usage:

pubnub.audit (‘my_channel’); # Sync Mode
channel_group_list_channels(channel_group, callback=None, error=None)

Get list of channels for a group.

Using this method, list of channels for a group, can be obtained.

Args:
channel_group: (string) (optional)
Channel Group name. It can also contain namespace. If namespace is also specified, then the parameter will be in format namespace:channel_group
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
Returns:

Sync Mode: dict channel_group_list_channels method returns a dict which contains list of channels in payload field:

{
    u'status': 200,
    u'payload': {"channels": ["hi"], "group": "abcd"},
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_list_channels gets the a dict containing list of channels under payload field:

{
    u'payload': {"channels": ["hi"], "group": "abcd"}
}
channel_group_list_groups(namespace=None, callback=None, error=None)

Get list of groups.

Using this method, list of groups for the subscribe key associated with PubNub object, can be obtained. If namespace is provided, groups within the namespace only are listed

Args:

namespace: (string) (optional) namespace

callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: dict

channel_group_list_groups method returns a dict which contains list of groups in payload field:

{
    u'status': 200,
    u'payload': {"namespace": "dev", "groups": ["abcd"]},
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_list_namespaces gets the a dict containing list of groups under payload field:

{
    u'payload': {"namespace": "dev", "groups": ["abcd"]}
}
channel_group_list_namespaces(callback=None, error=None)

Get list of namespaces.

You can obtain list of namespaces for the subscribe key associated with PubNub object using this method.

Args:
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
Returns:

Sync Mode: dict

channel_group_list_namespaces method returns a dict which contains list of namespaces in payload field:

{
    u'status': 200,
    u'payload': {
        u'sub_key': u'demo',
        u'namespaces': [u'dev', u'foo']
    },
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None (callback gets the response as parameter)

Response Format:

The callback passed to channel_group_list_namespaces gets the a dict containing list of namespaces under payload field:

{
    u'payload': {
        u'sub_key': u'demo',
        u'namespaces': [u'dev', u'foo']
    }
}

namespaces is the list of namespaces for the given subscribe key

channel_group_remove_channel(channel_group, channel, callback=None, error=None)

Remove channel.

A channel can be removed from a group method.

Args:
channel_group: (string)
Channel Group name. It can also contain namespace. If namespace is also specified, then the parameter will be in format namespace:channel_group
channel: (string)
Can be a channel name, a list of channel names, or a comma separated list of channel names
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: dict

channel_group_remove_channel method returns a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_remove_channel gets the a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}
channel_group_remove_group(channel_group, callback=None, error=None)

Remove channel group.

A channel group can be removed using this method.

Args:
channel_group: (string)
Channel Group name. It can also contain namespace. If namespace is also specified, then the parameter will be in format namespace:channel_group
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
Returns:

Sync Mode: dict

channel_group_remove_group method returns a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_remove_group gets the a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}
channel_group_remove_namespace(namespace, callback=None, error=None)

Remove a namespace.

A namespace can be deleted using this method.

Args:

namespace: (string) namespace to be deleted

callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: dict

channel_group_remove_namespace method returns a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_list_namespaces gets the a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}
decrypt(message)

Method for decrypting data.

This method takes ciphertext as input and returns decrypted data. This need not be called directly as enncryption/decryption is taken care of transparently by Pubnub class if cipher key is provided at time of initializing pubnub object

Args:
message: Message to be decrypted.
Returns:
Returns decrypted message if cipher key is set
encrypt(message)

Method for encrypting data.

This method takes plaintext as input and returns encrypted data. This need not be called directly as enncryption/decryption is taken care of transparently by Pubnub class if cipher key is provided at time of initializing pubnub object

Args:
message: Message to be encrypted.
Returns:
Returns encrypted message if cipher key is set
grant(channel=None, channel_group=None, auth_key=False, read=False, write=False, manage=False, ttl=5, callback=None, error=None)

Method for granting permissions.

This function establishes subscribe and/or write permissions for PubNub Access Manager (PAM) by setting the read or write attribute to true. A grant with read or write set to false (or not included) will revoke any previous grants with read or write set to true.

Permissions can be applied to any one of three levels:
  1. Application level privileges are based on subscribe_key applying to all associated channels.
  2. Channel level privileges are based on a combination of subscribe_key and channel name.
  3. User level privileges are based on the combination of subscribe_key, channel and auth_key.
Args:
channel: (string) (optional)
Specifies channel name to grant permissions to. If channel/channel_group is not specified, the grant applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to grant permissions to multiple channels simultaneously by specifying the channels as a comma separated list.
channel_group: (string) (optional)
Specifies channel group name to grant permissions to. If channel/channel_group is not specified, the grant applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to grant permissions to multiple channel groups simultaneously by specifying the channel groups as a comma separated list.
auth_key: (string) (optional)
Specifies auth_key to grant permissions to. It is possible to specify multiple auth_keys as comma separated list in combination with a single channel name. If auth_key is provided as the special-case value “null” (or included in a comma-separated list, eg. “null,null,abc”), a new auth_key will be generated and returned for each “null” value.
read: (boolean) (default: True)
Read permissions are granted by setting to True. Read permissions are removed by setting to False.
write: (boolean) (default: True)
Write permissions are granted by setting to true. Write permissions are removed by setting to false.
manage: (boolean) (default: True)
Manage permissions are granted by setting to true. Manage permissions are removed by setting to false.
ttl: (int) (default: 1440 i.e 24 hrs)
Time in minutes for which granted permissions are valid. Max is 525600 , Min is 1. Setting ttl to 0 will apply the grant indefinitely.
callback: (function) (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (function) (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a dict in sync mode i.e. when callback argument is not given The dict returned contains values with keys ‘message’ and ‘payload’

Sample Response:

{
    "message":"Success",
    "payload":{
        "ttl":5,
        "auths":{
            "my_ro_authkey":{"r":1,"w":0}
        },
        "subscribe_key":"my_subkey",
        "level":"user",
        "channel":"my_channel"
    }
}
here_now(channel, uuids=True, state=False, callback=None, error=None)

Get here now data.

You can obtain information about the current state of a channel including a list of unique user-ids currently subscribed to the channel and the total occupancy count of the channel by calling the here_now() function in your application.

Args:
channel: (string) (optional)
Specifies the channel name to return occupancy results. If channel is not provided, here_now will return data for all channels.
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: list Async Mode: None

Response Format:

The here_now() method 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.

Example Response:

{
    occupancy: 4,
    uuids: [
        '123123234t234f34fq3dq',
        '143r34f34t34fq34q34q3',
        '23f34d3f4rq34r34rq23q',
        'w34tcw45t45tcw435tww3',
    ]
}
history(channel, count=100, reverse=False, start=None, end=None, include_token=False, callback=None, error=None)

This method fetches historical messages of a channel.

PubNub Storage/Playback Service provides real-time access to an unlimited history for all messages published to PubNub. Stored messages are replicated across multiple availability zones in several geographical data center locations. Stored messages can be encrypted with AES-256 message encryption ensuring that they are not readable while stored on PubNub’s network.

It is possible to control how messages are returned and in what order, for example you can:

Return messages in the order newest to oldest (default behavior).

Return messages in the order oldest to newest by setting reverse to true.

Page through results by providing a start or end time token.

Retrieve a “slice” of the time line by providing both a start and end time token.

Limit the number of messages to a specific quantity using the count parameter.

Args:
channel: (string)
Specifies channel to return history messages from
count: (int) (default: 100)
Specifies the number of historical messages to return
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a list in sync mode i.e. when callback argument is not given

Sample Response:
[[“Pub1”,”Pub2”,”Pub3”,”Pub4”,”Pub5”],13406746729185766,13406746845892666]
presence(channel, callback, error=None, connect=None, disconnect=None, reconnect=None)

Subscribe to presence events on a channel.

Only works in async mode
Args:

channel: Channel name ( string ) on which to listen for events

callback: A callback method should be passed as parameter.
If passed, the api works in async mode. Required argument when working with twisted or tornado .
error: Optional variable. An error method can be passed as parameter.
If set, the api works in async mode.
Returns:
None
presence_group(channel_group, callback, error=None, connect=None, disconnect=None, reconnect=None)

Subscribe to presence events on a channel group.

Only works in async mode
Args:

channel_group: Channel group name ( string )

callback: A callback method should be passed to the method.
If passed, the api works in async mode. Required argument when working with twisted or tornado .
error: Optional variable. An error method can be passed as parameter.
If passed, the api works in async mode.
Returns:
None
publish(channel, message, callback=None, error=None)

Publishes data on a channel.

The publish() method is used to send a message to all subscribers of a channel. To publish a message you must first specify a valid publish_key at initialization. A successfully published message is replicated across the PubNub Real-Time Network and sent simultaneously to all subscribed clients on a channel.

Messages in transit can be secured from potential eavesdroppers with SSL/TLS by setting ssl to True during initialization.

Published messages can also be encrypted with AES-256 simply by specifying a cipher_key during initialization.

Args:
channel: (string)
Specifies channel name to publish messages to.
message: (string/int/double/dict/list)
Message to be published
callback: (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
Returns:

Sync Mode : list Async Mode : None

The function returns the following formatted response:

[ Number, “Status”, “Time Token”]

The output below demonstrates the response to a successful call:

[1,”Sent”,”13769558699541401”]
revoke(channel=None, channel_group=None, auth_key=None, ttl=1, callback=None, error=None)

Method for revoking permissions.

Args:
channel: (string) (optional)
Specifies channel name to revoke permissions to. If channel/channel_group is not specified, the revoke applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to grant permissions to multiple channels simultaneously by specifying the channels as a comma separated list.
channel_group: (string) (optional)
Specifies channel group name to revoke permissions to. If channel/channel_group is not specified, the grant applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to revoke permissions to multiple channel groups simultaneously by specifying the channel groups as a comma separated list.
auth_key: (string) (optional)
Specifies auth_key to revoke permissions to. It is possible to specify multiple auth_keys as comma separated list in combination with a single channel name. If auth_key is provided as the special-case value “null” (or included in a comma-separated list, eg. “null,null,abc”), a new auth_key will be generated and returned for each “null” value.
ttl: (int) (default: 1440 i.e 24 hrs)
Time in minutes for which granted permissions are valid. Max is 525600 , Min is 1. Setting ttl to 0 will apply the grant indefinitely.
callback: (function) (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (function) (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a dict in sync mode i.e. when callback argument is not given The dict returned contains values with keys ‘message’ and ‘payload’

Sample Response:

{
    "message":"Success",
    "payload":{
        "ttl":5,
        "auths":{
            "my_authkey":{"r":0,"w":0}
        },
        "subscribe_key":"my_subkey",
        "level":"user",
        "channel":"my_channel"
    }
}
subscribe(channels, callback, state=None, error=None, connect=None, disconnect=None, reconnect=None, sync=False)

Subscribe to data on a channel.

This function causes the client to create an open TCP socket to the PubNub Real-Time Network and begin listening for messages on a specified channel. To subscribe to a channel the client must send the appropriate subscribe_key at initialization.

Only works in async mode

Args:
channel: (string/list)
Specifies the channel to subscribe to. It is possible to specify multiple channels as a comma separated list or andarray.
callback: (function)
This callback is called on receiving a message from the channel.
state: (dict)
State to be set.
error: (function) (optional)
This callback is called on an error event
connect: (function) (optional)
This callback is called on a successful connection to the PubNub cloud
disconnect: (function) (optional)
This callback is called on client disconnect from the PubNub cloud
reconnect: (function) (optional)
This callback is called on successfully re-connecting to the PubNub cloud
Returns:
None
subscribe_group(channel_groups, callback, error=None, connect=None, disconnect=None, reconnect=None, sync=False)

Subscribe to data on a channel group.

This function causes the client to create an open TCP socket to the PubNub Real-Time Network and begin listening for messages on a specified channel. To subscribe to a channel group the client must send the appropriate subscribe_key at initialization.

Only works in async mode

Args:
channel_groups: (string/list)
Specifies the channel groups to subscribe to. It is possible to specify multiple channel groups as a comma separated list or andarray.
callback: (function)
This callback is called on receiving a message from the channel.
error: (function) (optional)
This callback is called on an error event
connect: (function) (optional)
This callback is called on a successful connection to the PubNub cloud
disconnect: (function) (optional)
This callback is called on client disconnect from the PubNub cloud
reconnect: (function) (optional)
This callback is called on successfully re-connecting to the PubNub cloud
Returns:
None
time(callback=None)

This function will return a 17 digit precision Unix epoch.

Args:

callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a 17 digit number in sync mode i.e. when callback argument is not given

Sample:
13769501243685161
unsubscribe(channel)
Unsubscribe from channel .
Only works in async mode
Args:
channel: Channel name ( string )
unsubscribe_group(channel_group)
Unsubscribe from channel group.
Only works in async mode
Args:
channel_group: Channel group name ( string )

PubnubTornado

class pubnub.PubnubTornado(publish_key, subscribe_key, secret_key=False, cipher_key=False, auth_key=False, ssl_on=False, origin='pubsub.pubnub.com')
audit(channel=None, channel_group=None, auth_key=None, callback=None, error=None)

Method for fetching permissions from pubnub servers.

This method provides a mechanism to reveal existing PubNub Access Manager attributes for any combination of subscribe_key, channel and auth_key.

Args:
channel: (string) (optional)
Specifies channel name to return PAM attributes optionally in combination with auth_key. If channel/channel_group is not specified, results for all channels associated with subscribe_key are returned. If auth_key is not specified, it is possible to return results for a comma separated list of channels.
channel_group: (string) (optional)
Specifies channel group name to return PAM attributes optionally in combination with auth_key. If channel/channel_group is not specified, results for all channels associated with subscribe_key are returned. If auth_key is not specified, it is possible to return results for a comma separated list of channels.
auth_key: (string) (optional)
Specifies the auth_key to return PAM attributes for. If only a single channel is specified, it is possible to return results for a comma separated list of auth_keys.
callback: (function) (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (function) (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a dict in sync mode i.e. when callback argument is not given The dict returned contains values with keys ‘message’ and ‘payload’

Sample Response:

{
    "message":"Success",
    "payload":{
        "channels":{
            "my_channel":{
                "auths":{"my_ro_authkey":{"r":1,"w":0},
                "my_rw_authkey":{"r":0,"w":1},
                "my_admin_authkey":{"r":1,"w":1}
            }
        }
    },
}

Usage:

pubnub.audit (‘my_channel’); # Sync Mode
channel_group_list_channels(channel_group, callback=None, error=None)

Get list of channels for a group.

Using this method, list of channels for a group, can be obtained.

Args:
channel_group: (string) (optional)
Channel Group name. It can also contain namespace. If namespace is also specified, then the parameter will be in format namespace:channel_group
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
Returns:

Sync Mode: dict channel_group_list_channels method returns a dict which contains list of channels in payload field:

{
    u'status': 200,
    u'payload': {"channels": ["hi"], "group": "abcd"},
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_list_channels gets the a dict containing list of channels under payload field:

{
    u'payload': {"channels": ["hi"], "group": "abcd"}
}
channel_group_list_groups(namespace=None, callback=None, error=None)

Get list of groups.

Using this method, list of groups for the subscribe key associated with PubNub object, can be obtained. If namespace is provided, groups within the namespace only are listed

Args:

namespace: (string) (optional) namespace

callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: dict

channel_group_list_groups method returns a dict which contains list of groups in payload field:

{
    u'status': 200,
    u'payload': {"namespace": "dev", "groups": ["abcd"]},
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_list_namespaces gets the a dict containing list of groups under payload field:

{
    u'payload': {"namespace": "dev", "groups": ["abcd"]}
}
channel_group_list_namespaces(callback=None, error=None)

Get list of namespaces.

You can obtain list of namespaces for the subscribe key associated with PubNub object using this method.

Args:
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
Returns:

Sync Mode: dict

channel_group_list_namespaces method returns a dict which contains list of namespaces in payload field:

{
    u'status': 200,
    u'payload': {
        u'sub_key': u'demo',
        u'namespaces': [u'dev', u'foo']
    },
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None (callback gets the response as parameter)

Response Format:

The callback passed to channel_group_list_namespaces gets the a dict containing list of namespaces under payload field:

{
    u'payload': {
        u'sub_key': u'demo',
        u'namespaces': [u'dev', u'foo']
    }
}

namespaces is the list of namespaces for the given subscribe key

channel_group_remove_channel(channel_group, channel, callback=None, error=None)

Remove channel.

A channel can be removed from a group method.

Args:
channel_group: (string)
Channel Group name. It can also contain namespace. If namespace is also specified, then the parameter will be in format namespace:channel_group
channel: (string)
Can be a channel name, a list of channel names, or a comma separated list of channel names
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: dict

channel_group_remove_channel method returns a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_remove_channel gets the a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}
channel_group_remove_group(channel_group, callback=None, error=None)

Remove channel group.

A channel group can be removed using this method.

Args:
channel_group: (string)
Channel Group name. It can also contain namespace. If namespace is also specified, then the parameter will be in format namespace:channel_group
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado.
Returns:

Sync Mode: dict

channel_group_remove_group method returns a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_remove_group gets the a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}
channel_group_remove_namespace(namespace, callback=None, error=None)

Remove a namespace.

A namespace can be deleted using this method.

Args:

namespace: (string) namespace to be deleted

callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: dict

channel_group_remove_namespace method returns a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}

Async Mode: None ( callback gets the response as parameter )

Response Format:

The callback passed to channel_group_list_namespaces gets the a dict indicating status of the request:

{
    u'status': 200,
    u'message': 'OK',
    u'service': u'channel-registry',
    u'error': False
}
decrypt(message)

Method for decrypting data.

This method takes ciphertext as input and returns decrypted data. This need not be called directly as enncryption/decryption is taken care of transparently by Pubnub class if cipher key is provided at time of initializing pubnub object

Args:
message: Message to be decrypted.
Returns:
Returns decrypted message if cipher key is set
encrypt(message)

Method for encrypting data.

This method takes plaintext as input and returns encrypted data. This need not be called directly as enncryption/decryption is taken care of transparently by Pubnub class if cipher key is provided at time of initializing pubnub object

Args:
message: Message to be encrypted.
Returns:
Returns encrypted message if cipher key is set
grant(channel=None, channel_group=None, auth_key=False, read=False, write=False, manage=False, ttl=5, callback=None, error=None)

Method for granting permissions.

This function establishes subscribe and/or write permissions for PubNub Access Manager (PAM) by setting the read or write attribute to true. A grant with read or write set to false (or not included) will revoke any previous grants with read or write set to true.

Permissions can be applied to any one of three levels:
  1. Application level privileges are based on subscribe_key applying to all associated channels.
  2. Channel level privileges are based on a combination of subscribe_key and channel name.
  3. User level privileges are based on the combination of subscribe_key, channel and auth_key.
Args:
channel: (string) (optional)
Specifies channel name to grant permissions to. If channel/channel_group is not specified, the grant applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to grant permissions to multiple channels simultaneously by specifying the channels as a comma separated list.
channel_group: (string) (optional)
Specifies channel group name to grant permissions to. If channel/channel_group is not specified, the grant applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to grant permissions to multiple channel groups simultaneously by specifying the channel groups as a comma separated list.
auth_key: (string) (optional)
Specifies auth_key to grant permissions to. It is possible to specify multiple auth_keys as comma separated list in combination with a single channel name. If auth_key is provided as the special-case value “null” (or included in a comma-separated list, eg. “null,null,abc”), a new auth_key will be generated and returned for each “null” value.
read: (boolean) (default: True)
Read permissions are granted by setting to True. Read permissions are removed by setting to False.
write: (boolean) (default: True)
Write permissions are granted by setting to true. Write permissions are removed by setting to false.
manage: (boolean) (default: True)
Manage permissions are granted by setting to true. Manage permissions are removed by setting to false.
ttl: (int) (default: 1440 i.e 24 hrs)
Time in minutes for which granted permissions are valid. Max is 525600 , Min is 1. Setting ttl to 0 will apply the grant indefinitely.
callback: (function) (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (function) (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a dict in sync mode i.e. when callback argument is not given The dict returned contains values with keys ‘message’ and ‘payload’

Sample Response:

{
    "message":"Success",
    "payload":{
        "ttl":5,
        "auths":{
            "my_ro_authkey":{"r":1,"w":0}
        },
        "subscribe_key":"my_subkey",
        "level":"user",
        "channel":"my_channel"
    }
}
here_now(channel, uuids=True, state=False, callback=None, error=None)

Get here now data.

You can obtain information about the current state of a channel including a list of unique user-ids currently subscribed to the channel and the total occupancy count of the channel by calling the here_now() function in your application.

Args:
channel: (string) (optional)
Specifies the channel name to return occupancy results. If channel is not provided, here_now will return data for all channels.
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
Optional variable. An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Sync Mode: list Async Mode: None

Response Format:

The here_now() method 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.

Example Response:

{
    occupancy: 4,
    uuids: [
        '123123234t234f34fq3dq',
        '143r34f34t34fq34q34q3',
        '23f34d3f4rq34r34rq23q',
        'w34tcw45t45tcw435tww3',
    ]
}
history(channel, count=100, reverse=False, start=None, end=None, include_token=False, callback=None, error=None)

This method fetches historical messages of a channel.

PubNub Storage/Playback Service provides real-time access to an unlimited history for all messages published to PubNub. Stored messages are replicated across multiple availability zones in several geographical data center locations. Stored messages can be encrypted with AES-256 message encryption ensuring that they are not readable while stored on PubNub’s network.

It is possible to control how messages are returned and in what order, for example you can:

Return messages in the order newest to oldest (default behavior).

Return messages in the order oldest to newest by setting reverse to true.

Page through results by providing a start or end time token.

Retrieve a “slice” of the time line by providing both a start and end time token.

Limit the number of messages to a specific quantity using the count parameter.

Args:
channel: (string)
Specifies channel to return history messages from
count: (int) (default: 100)
Specifies the number of historical messages to return
callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
error: (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a list in sync mode i.e. when callback argument is not given

Sample Response:
[[“Pub1”,”Pub2”,”Pub3”,”Pub4”,”Pub5”],13406746729185766,13406746845892666]
presence(channel, callback, error=None, connect=None, disconnect=None, reconnect=None)

Subscribe to presence events on a channel.

Only works in async mode
Args:

channel: Channel name ( string ) on which to listen for events

callback: A callback method should be passed as parameter.
If passed, the api works in async mode. Required argument when working with twisted or tornado .
error: Optional variable. An error method can be passed as parameter.
If set, the api works in async mode.
Returns:
None
presence_group(channel_group, callback, error=None, connect=None, disconnect=None, reconnect=None)

Subscribe to presence events on a channel group.

Only works in async mode
Args:

channel_group: Channel group name ( string )

callback: A callback method should be passed to the method.
If passed, the api works in async mode. Required argument when working with twisted or tornado .
error: Optional variable. An error method can be passed as parameter.
If passed, the api works in async mode.
Returns:
None
publish(channel, message, callback=None, error=None)

Publishes data on a channel.

The publish() method is used to send a message to all subscribers of a channel. To publish a message you must first specify a valid publish_key at initialization. A successfully published message is replicated across the PubNub Real-Time Network and sent simultaneously to all subscribed clients on a channel.

Messages in transit can be secured from potential eavesdroppers with SSL/TLS by setting ssl to True during initialization.

Published messages can also be encrypted with AES-256 simply by specifying a cipher_key during initialization.

Args:
channel: (string)
Specifies channel name to publish messages to.
message: (string/int/double/dict/list)
Message to be published
callback: (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
Returns:

Sync Mode : list Async Mode : None

The function returns the following formatted response:

[ Number, “Status”, “Time Token”]

The output below demonstrates the response to a successful call:

[1,”Sent”,”13769558699541401”]
revoke(channel=None, channel_group=None, auth_key=None, ttl=1, callback=None, error=None)

Method for revoking permissions.

Args:
channel: (string) (optional)
Specifies channel name to revoke permissions to. If channel/channel_group is not specified, the revoke applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to grant permissions to multiple channels simultaneously by specifying the channels as a comma separated list.
channel_group: (string) (optional)
Specifies channel group name to revoke permissions to. If channel/channel_group is not specified, the grant applies to all channels associated with the subscribe_key. If auth_key is not specified, it is possible to revoke permissions to multiple channel groups simultaneously by specifying the channel groups as a comma separated list.
auth_key: (string) (optional)
Specifies auth_key to revoke permissions to. It is possible to specify multiple auth_keys as comma separated list in combination with a single channel name. If auth_key is provided as the special-case value “null” (or included in a comma-separated list, eg. “null,null,abc”), a new auth_key will be generated and returned for each “null” value.
ttl: (int) (default: 1440 i.e 24 hrs)
Time in minutes for which granted permissions are valid. Max is 525600 , Min is 1. Setting ttl to 0 will apply the grant indefinitely.
callback: (function) (optional)
A callback method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado
error: (function) (optional)
An error method can be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a dict in sync mode i.e. when callback argument is not given The dict returned contains values with keys ‘message’ and ‘payload’

Sample Response:

{
    "message":"Success",
    "payload":{
        "ttl":5,
        "auths":{
            "my_authkey":{"r":0,"w":0}
        },
        "subscribe_key":"my_subkey",
        "level":"user",
        "channel":"my_channel"
    }
}
subscribe(channels, callback, state=None, error=None, connect=None, disconnect=None, reconnect=None, sync=False)

Subscribe to data on a channel.

This function causes the client to create an open TCP socket to the PubNub Real-Time Network and begin listening for messages on a specified channel. To subscribe to a channel the client must send the appropriate subscribe_key at initialization.

Only works in async mode

Args:
channel: (string/list)
Specifies the channel to subscribe to. It is possible to specify multiple channels as a comma separated list or andarray.
callback: (function)
This callback is called on receiving a message from the channel.
state: (dict)
State to be set.
error: (function) (optional)
This callback is called on an error event
connect: (function) (optional)
This callback is called on a successful connection to the PubNub cloud
disconnect: (function) (optional)
This callback is called on client disconnect from the PubNub cloud
reconnect: (function) (optional)
This callback is called on successfully re-connecting to the PubNub cloud
Returns:
None
subscribe_group(channel_groups, callback, error=None, connect=None, disconnect=None, reconnect=None, sync=False)

Subscribe to data on a channel group.

This function causes the client to create an open TCP socket to the PubNub Real-Time Network and begin listening for messages on a specified channel. To subscribe to a channel group the client must send the appropriate subscribe_key at initialization.

Only works in async mode

Args:
channel_groups: (string/list)
Specifies the channel groups to subscribe to. It is possible to specify multiple channel groups as a comma separated list or andarray.
callback: (function)
This callback is called on receiving a message from the channel.
error: (function) (optional)
This callback is called on an error event
connect: (function) (optional)
This callback is called on a successful connection to the PubNub cloud
disconnect: (function) (optional)
This callback is called on client disconnect from the PubNub cloud
reconnect: (function) (optional)
This callback is called on successfully re-connecting to the PubNub cloud
Returns:
None
time(callback=None)

This function will return a 17 digit precision Unix epoch.

Args:

callback: (optional)
A callback method should be passed to the method. If set, the api works in async mode. Required argument when working with twisted or tornado .
Returns:

Returns a 17 digit number in sync mode i.e. when callback argument is not given

Sample:
13769501243685161
unsubscribe(channel)
Unsubscribe from channel .
Only works in async mode
Args:
channel: Channel name ( string )
unsubscribe_group(channel_group)
Unsubscribe from channel group.
Only works in async mode
Args:
channel_group: Channel group name ( string )

Indices and tables