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, pres_uuid=None)
audit(channel=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 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
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, auth_key=False, read=True, write=True, 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 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.
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.
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, 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, 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)

Subscribe to presence data on a channel.

Only works in async mode
Args:

channel: Channel name ( string ) on which to publish message callback: 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 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:
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, 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 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.
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, 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.
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)
Subscribe to presence data on a channel.
Only works in async mode
Args:

channel: Channel name ( string ) on which to publish message message: Message to be published ( String / int / double / dict / list ). callback: 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 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:
Returns a list in sync mode i.e. when callback argument is not given

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, 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 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
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, auth_key=False, read=True, write=True, 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 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.
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.
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, 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, 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)

Subscribe to presence data on a channel.

Only works in async mode
Args:

channel: Channel name ( string ) on which to publish message callback: 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 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:
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, 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 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.
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, 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.
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)
Subscribe to presence data on a channel.
Only works in async mode
Args:

channel: Channel name ( string ) on which to publish message message: Message to be published ( String / int / double / dict / list ). callback: 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 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:
Returns a list in sync mode i.e. when callback argument is not given

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, 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 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
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, auth_key=False, read=True, write=True, 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 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.
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.
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, 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, 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)

Subscribe to presence data on a channel.

Only works in async mode
Args:

channel: Channel name ( string ) on which to publish message callback: 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 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:
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, 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 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.
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, 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.
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)
Subscribe to presence data on a channel.
Only works in async mode
Args:

channel: Channel name ( string ) on which to publish message message: Message to be published ( String / int / double / dict / list ). callback: 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 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:
Returns a list in sync mode i.e. when callback argument is not given

Indices and tables

Table Of Contents

This Page