PubNub REST API Documentation

Common REST Query String Parameters

The following parameters should be used on all REST calls being made to PubNub.

  • uuid – required - A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

  • auth – optional - An Access Manager authentication key (v2) or token (v3), to be used on Access Manager-enabled endpoints:

    • Publishing
    • Subscribing
    • History
    • Channel Group operations
  • signature – optional - Only to be used for Access Manager admin REST calls (grant, audit).

  • pnsdk – required - An identifier which uniquely identifies your client SDK. This should be of the format CompanyName-ProgrammingLanguageUsed/YourClientSDKVersion (e.g. CompanyABC-JS/1.0). Please contact support@pubnub.com for further information.

Common HTTP Request Headers

The following HTTP headers should be used across all PubNub REST requests.

  • Content-Encoding - When sending compressed, gzipped data via POST requests, set value as gzip

  • Content-Type - Always use application/json; charset=UTF-8 when sending JSON, and using UTF-8

  • Accept-Encoding - If your client supports gzip, set this value to gzip, if your client supports deflate, set this value to deflate, if it supports both, set this value to gzip, deflate and if it supports neither, omit this header altogether.

Common HTTP Status Codes

The following HTTP Status codes should be treated the same across all PubNub REST responses.

  • 200 – The REST call was successful. Refer to the detail usage by operation for more information on parsing the response.

  • 403 – The REST call was unsuccessful, due to an Access Manager (access control) issue. Try again, without an auth URL parameter, or with a different auth URL parameter.

  • 414 – The REST call was unsuccessful, due to exceeding the allowed size of 32 KiB.

Publish / Subscribe

Publish V1 via GET

Publish a message to a channel.

Publish v1 - Valid / Success Responses

Successful (HTTP Status 200) Publish() calls will always return a three-element array:

  • Array Element 0 - Integer – 1 or 0, where 1 is success, and 0 is error.

  • Array Element 1 - String – Description of the success or error, if available.

  • Array Element 2 - String – The current PubNub time expressed as a Timetoken, on success only.

A sample response from server [1,"Sent","14375189629170609"] contains the following fields:

  • The first element is an integer of value 1 representing success.

  • The second element is a string description of the success, which for 200 response codes will always be "Sent".

  • The third element is the string Timetoken value the system accepted the Publish() operation at.

Publish v1 - Invalid / Error Responses

In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned. If you do, and it has a second element, and that element is a string, you may parse it for a description of the error.

Errors specific to Publish() will occur when URL (e.g., message payload) is too large (>=32K), and invalid publish and/or subscribe keys are used.

Publish JSON to channel via GETGET/publish/{pub_key}/{sub_key}/0/{channel}/{callback}/{payload}{?store,uuid}

Example URI

GET https://ps.pndsn.com/publish/myPubKey/mySubKey/0/ch1/myCallback/%7B%22text%22%3A%22hey%22%7D?store=0&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
pub_key
string (required) Example: myPubKey

the publish key to use

sub_key
string (required) Example: mySubKey

the subscriber key

channel
string (required) Example: ch1

the destination of the message

callback
string (required) Example: myCallback

response will be wrapped in JSONP function, 0 for no JSONP

payload
string (required) Example: %7B%22text%22%3A%22hey%22%7D

url-encoded JSON

Query Parameters
store
number (optional) Example: 0

this parameter overrides default account configuration on message saving. 1 to Save, 0 to not save.

auth
string (optional) Example: "authKey"

If the channel is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to publish to the channel.

meta
object (optional) Example: meta={"cool":"meta"}

used to send additional information about the message which can be used on stream filtering.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

ttl
integer (optional) Example: 1

Set a per-message time to live in storage.

  1. If store = 1, and ttl = 0, the message is stored with no expiry time.
  2. If store = 1 and ttl = X (X is an Integer value), the message is stored with an expiry time of X hours.
  3. If store = 0, the ttl parameter is ignored.
  4. If ttl is not specified, then expiration of the message defaults back to the expiry value for the key.
Request without JSON
Headers
Location: /publish/myPubKey/mySubKey/0/ch1/0/%7B%22text%22%3A%22hey%22%7D
Response 200
Headers
Content-Type: application/json
Body
[1,"Sent","14375220012064619"]
Request with JSONP
Headers
Location: /publish/myPubKey/mySubKey/0/ch1/myCallback/%7B%22text%22%3A%22hey%22%7D
Response 200
Headers
Content-Type: application/json
Body
myCallback([1,"Sent","14375220012064619"])

Publish V1 via POST

Publish a message to a channel.

Publish JSON to channel via POSTPOST/publish/{pub_key}/{sub_key}/0/{channel}/{callback}{?store,uuid}

Example URI

POST https://ps.pndsn.com/publish/myPubKey/mySubKey/0/ch1/myCallback?store=0&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
pub_key
string (required) Example: myPubKey

the publish key to use

sub_key
string (required) Example: mySubKey

the subscriber key

channel
string (required) Example: ch1

the destination of the message

callback
string (required) Example: myCallback

response will be wrapped in JSONP function, 0 for no JSONP

Query Parameters
store
number (optional) Example: 0

this parameter overrides default account configuration on message saving. 1 to save, 0 to not save.

auth
string (optional) Example: "authKey"

If the channel is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to write to the channel.

meta
object (optional) Example: meta={"cool":"meta"}

used to send additional information about the message which can be used on stream filtering.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

ttl
integer (optional) Example: 1

Set a per-message time to live in storage.

  1. If store = 1, and ttl = 0, the message is stored with no expiry time.
  2. If store = 1, and ttl = X (X is an Integer value), the message is stored with an expiry time of X hours.
  3. If store = 0, the ttl parameter is ignored.
  4. If ttl is not specified, then expiration of the message defaults back to the expiry value for the key.
Request without JSONP
Headers
Content-Type: application/json Location: /publish/myPubKey/mySubKey/0/ch1/0
Body
{ "message": "All your base are belong to us." }
Response 200
Headers
Content-Type: application/json
Body
[ 1, "Sent", "14375220012064619" ]
Request with JSONP
Headers
Location: /publish/myPubKey/mySubKey/0/ch1/myCallback/%7B%22text%22%3A%22hey%22%7D
Body
{ "message": "All your base are belong to us." }
Response 200
Headers
Content-Type: application/json
Body
myCallback([1,"Sent","14375220012064619"])

Fire

The fire endpoint allows the client to send a message to BLOCKS Event Handlers. These messages will go directly to any Event Handlers registered on the channel that you fire to and will trigger their execution. The content of the fired request will be available for processing within the Event Handler. The message sent via fire() is not replicated, and so will not be received by any subscribers to the channel. The message is also not stored in history.

FireGET/publish/{pub_key}/{sub_key}/0/{channel}/{callback}?&norep=true&store=0

Example URI

GET https://ps.pndsn.com/publish/myPubKey/mySubKey/0/ch1/myCallback/{"text"%3A"hey"}?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&norep=true&store=0
Path Parameters
pub_key
string (required) Example: myPubKey

The publish key to use.

sub_key
string (required) Example: mySubKey

The subscriber key.

channel
string (required) Example: ch1

The destination of the message.

callback
string (required) Example: myCallback

Response will be wrapped in JSONP function, 0 for no JSONP.

Query Parameters
store
number (required, should be 0 for Fire)
norep
boolean(required, should be true for Fire)
auth
string (optional) Example: "authKey"

If the channel is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to write to the channel.

meta
object (optional) Example: meta={"cool":"meta"}

Used to send additional information about the message which can be used for stream filtering.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request without JSONP
Response 200
Request with JSONP
Response 200

Signals

Signals are very small, transient messages that represent momentary snippets of information that do not require extensive tracking and backup, as each one will be rapidly replaced by the next signal.

A signal may be part of a high-volume stream of payloads intended to inform or instruct an application, without including information that would be directly reflected in an application UI. Examples of signals include rideshare driver latitude and longitude measurements, a command to switch on a chat app typing indicator, and more.

By default, signals are limited to a message payload size of 64 bytes. This limit applies only to the request body, and not to the URI or headers. If you require a larger payload size, please contact support.

Signal a message to a channelGET/signal/{pub_key}/{sub_key}/0/{channel}/{callback}/{payload}{?uuid,auth}

This resource allows a developer to send a signal to a channel.

Example URI

GET https://ps.pndsn.com/signal/demo/demo/0/ch1/0/%22typing_on%22?uuid=user-123
Path parameters
pub_key

string (required)
Your PubNub Publish API Key

sub_key

string (required)
Your PubNub Subscribe API Key.

channel

string (required)
The channel name you wish to signal.

callback

string (required)
The JSONP callback, or 0 if no callback.

payload

string (required)
The message body to signal. This can be unstructured text or JSON, for example.

Query Parameters
uuid

string (optional)
A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

auth

string (optional)
If the channel is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to publish to the channel.

Response  200

Success

Headers
Content-Type: text/javascript
Body
[ 1, "Sent", "15614849564528142" ]
Receiving a signal message

To receive a signal message, you use a request. Signal messages are tagged with a message type (e) field value of e=1. The following example shows a signal message:

{ "t": { "t": "15653761881633527", "r": 1 }, "m": [ { "a": "5", "f": 0, "e": 1, "i": "user-123", "p": { "t": "15653761881622292", "r": 1 }, "k": "demo", "c": "myChannel", "d": "typing_on", "b": "myChannelGroup" } ] }
Response  400

There was an error with the request

Headers
Content-Type: text/javascript
Body
{ "message": "Invalid Subscribe Key", "error": true, "status": 400 }
Response  403

Client is not authorized to perform this operation.

Headers
Content-Type: text/javascript
Body
{ "message": "Forbidden", "payload": { "channels": [ "channel" ] }, "error": true, "service": "Access Manager", "status": 403 }
Response  404

Requested object was not found.

Headers
Content-Type: text/javascript
Body
[]
Response  413

The Signal POST body is larger than 64 bytes.

Headers
Content-Type: text/javascript
Body
{ "status": 413, "service": "Balancer", "error": true, "message": "Request Entity Too Large" }
Response  429

Request rate limit exceeded.

Headers
Content-Type: text/javascript
Body
{ "status": 429, "error": true, "message": "Too many requests." }

Subscribe

Subscribe to messages on channels and/or channel groups.

Subscribe v1 - Valid / Success Responses

Successful responses (200) return a three-element array:

  • Array Element 0 - Array - An array consisting of messages.

  • Array Element 1 - String - The next timetoken to connect with.

  • Array Element 2 - String - A CSV (not array) of the channels associated, in order, with the messages in array element 0. If the is an empty heartbeat response, or an empty initial timetoken 0 response, or you are only subscribed to a single channel or channel group, this element will not be returned.

  • Array Element 3 - String -When subscribed to one or more channel groups, array element 3 appears. It is a CSV (not array) of the "real channel" name associated with the channel group name.

If you are subscribed to a channel group named myCG, and you receive a message on myCG from a member channel named myCH, array element 2 will contain "myCG", and the corresponding entry in element 3 will be "myCH".

When subscribing to both channels and channel groups, the corresponding entry for an non-CG member channel will be identical to that of the entry for it element 2.

Subscribe v1 - Invalid / Error Responses

In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned.

Common HTTP Status Codes should be expected. In the event of a non-Common HTTP Status Code and/or unparseable JSON, assume an error, fire your error callback with as much information as possible, wait 1 second, and retry the failed request indefinitely.

It is critical to design your subscribe logic to be durable and always retry. Although it should try indefinately, since its calling the error callback on each failure, the developer will be able to unsubscribe from the channel(s) if needed.

SubscribeGET/subscribe/{sub_key}/{channel}/{callback}/{timetoken}{?state,heartbeat,uuid}

Example URI

GET https://ps.pndsn.com/subscribe/mySubKey/ch1/myFunction/1231312313123?state=%7B%22text%22%3A%22hey%22%7D&heartbeat=412&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s) you are subscribing to. Verify that channels are comprised of valid characters. You may subscribe to mulitple channels using a comma seperator. If subscribing to no channels (only channel groups), use a comma char (,) as a placeholder. You may subscribe to channels, channels & channel groups, or just channel groups.

callback
string (required) Example: myFunction

JSONP callback name, or 0 if none.

timetoken
string (required) Example: 1231312313123

0 (zero) for the initial subscribe, or a valid timetoken if resuming / continuing / fast-forwarding from a previous subscribe flow.

Query Parameters
channel-group
string (optional) Example: cg1,cg2,cg3

Channel group name(s) to subscribe to. If subscribing to more than one channel group, use a comma separator between channel group names. You may subscribe to channels, channels & channel groups, or just channel groups.

state
string (optional) Example: %7B%22text%22%3A%22hey%22%7D

When state is set, this value is an object with root keys associated with each channel you are setting state for. You must be subscribed to a channel to set state for it. (Refer to the get/set state sections)

heartbeat
number (optional) Example: 412

If heartbeat is set, send this parameter with the heartbeat value. (Refer to the heartbeat section)

auth
string (optional) Example: "authKey"

If the channel / channel group is protected by Access Manager, auth must be passed with a key which is authorized to read from the channel.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Subscribe v2 - Subscribe Process

To successfully subscribe and receive messages, you must send at least two subscribe calls.

  1. In the first call, set the tt parameter to 0. The server responds with the t (timetoken) and r (region) parameters.
  2. In subsequent calls, set the tt parameter to the value of the t parameter and the tr parameter to the value of the r parameter the server returned in the previous call.

The subscribe call returns messages with timetokens that are more recent than the one passed in the subscribe call. As you continue to make new subscribe calls, you must set the value of tr to the last received value of r as it keeps you subscribed to the same data center and prevents you from receiving duplicate messages.

Subscribe v2 - Valid / Success Responses

An Object containing 2 elements:

  • First element is an object containing 2 values: t - String - the timetoken and r - Int - the region.

  • Second element is an array of messages, each message contains.

    • a - String - Shard
    • b - String - Subscription match or the channel group
    • c - String - Channel
    • d - Object - The payload
    • e - Int - Message Type (e.g. 1 is for Signal, 2 is for Objects messages, 3 is for MessageAction messages, 4 is for Files messages)
    • f - Int - Flags
    • i - String - Issuing Client Id
    • k - String - Subscribe Key
    • o - Object - Originating Timetoken, containing: t - String - the timetoken and r - Int - the region.
    • p - Object - Publish Timetoken Metadata containing: t - String - the timetoken and r - Int - the region.
    • u - Object - User Metadata

If you are subscribed to a channel group named myCG, and you receive a message on myCG from a member channel named myCH, b will contain "myCG", and c will contain "myCH".

The value of e denotes the type of messages. If e is 1 the message is of type Signal and if e is 2 the message is of type Objects. A value of 0 or no e field means the message is a regular message. (See Body for more details.)

Each time a message action is added or removed, a specially-structured action event message will be published on the same channel as the parent message. These action event messages will come through the same subscribe event loop as the user's regular messages, but the envelope of the message will show an "e" field of 3. The data of the action event message will show whether the action was added or removed, and the data of the message action in question. The UUID that caused this event will also be returned in the envelope of the message, in the "i" field.

When subscribing to both channels and channel groups, the corresponding entry for an non-CG member channel will be identical to that of the entry for it element 2.

Subscribe v2 - Invalid / Error Responses

In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned.

Common HTTP Status Codes should be expected. In the event of a non-Common HTTP Status Code and/or unparseable JSON, assume an error, fire your error callback with as much information as possible, wait 1 second, and retry the failed request indefinitely.

It is critical to design your subscribe logic to be durable and always retry. Although it should try indefinately, since its calling the error callback on each failure, the developer will be able to unsubscribe from the channel(s) if needed.

SubscribeGET/v2/subscribe/{sub_key}/{channel}/{callback}{?uuid,tt,tr,state,filter-expr}

This resource allows a developer to Subscribe to PubNub.

Example URI

GET https://ps.pndsn.com/v2/subscribe/mySubKey/ch1/myFunction?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&tt=14586610176891624&tr=4&state=%7B%22ch1%22%3A%7B%22testkey%22%3A%22testval%22%7D%7D&filter-expr=uuid%20!%3D%20%27cvc1%27
Path Parameters
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s) you are subscribing to. Verify that channels are comprised of valid characters. You may subscribe to mulitple channels using a comma seperator. If subscribing to no channels (only channel groups), use a comma char (,) as a placeholder. You may subscribe to channels, channels & channel groups, or just channel groups.

callback
string (required) Example: myFunction

JSON callback name, or 0 if none.

Query Parameters
tt
string (required) Example: 1231312313123

0 (zero) for the initial subscribe, or a valid timetoken if resuming / continuing / fast-forwarding from a previous subscribe flow.

tr
string (required)

Region as returned from the initial subscribe call (with tt=0) or any subsequent call. This parameter prevents you from receiving duplicate messages by keeping you subscribed to the same data center.

channel-group
string (optional) Example: cg1,cg2,cg3

Channel group name(s) to subscribe to. If subscribing to more than one channel group, use a comma separator between channel group names. You may subscribe to channels, channels & channel groups, or just channel groups.

state
string (optional) Example: %7B%22text%22%3A%22hey%22%7D

When state is set, this value is an object with root keys associated with each channel you are setting state for. You must be subscribed to a channel to set state for it. (Refer to the get/set state sections)

heartbeat
number (optional) Example: 412

If heartbeat is set, send this parameter with the heartbeat value. (Refer to the heartbeat section)

auth
string (optional) Example: "authKey"

If the channel / channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

filter-expr
string (optional) Example: uuid%20!%3D%20%27cvc1%27

Set filter expression for Subscribe message filtering.

Response 200

Success

Headers
Content-Type: text/javascript
Body (For normal messages)
{ "t": { "t": "15628652479932717", "r": 4 }, "m":[ { "a": "1", "f": 514, "i": "pn-0ca50551-4bc8-446e-8829-c70b704545fd", "s": 1, "p": { "t": "15628652479933927", "r": 4 }, "k": "demo", "c": "my-channel", "d": "my message", "b": "my-channel" } ] }
Body (For messages of type Signal)
{ "t": { "t":"15665475668624925", "r":7 }, "m":[ { "a":"1", "f":0, "e":1, "i":"pn-2fedcc05-9909-4d46-9129-a75cb8b69a5a", "p": { "t":"15665475668605765", "r":7 }, "k":"sub-c-26a73b0a-c3f2-11e9-8b24-569e8a5c3af3", "c":"userid0", "d":"my-signal", "b":"userid0" } ] }
Body (For messages of type Objects)
{ "t": { "t":"15665291391003207", "r":7 }, "m":[ { "a":"1", "f":0, "e":2, "p": { "t":"15665291390119767", "r":2 }, "k":"sub-c-26a73b0a-c3f2-11e9-8b24-569e8a5c3af3", "c":"spaceid0", "d": { "source":"objects", "version":"1.0", "event":"update", "type":"space", "data": { "description":"desc5", "eTag":"AYSay6Cm6YfKEA", "id":"spaceid0", "name":"name", "updated":"2019-08-23T02:58:58.983927Z" } }, "b":"spaceid0" } ] }
Body (For messages of type Message Actions)
{ "t":{ "t":"15694740174268096", "r":56 }, "m":[ { "f":0, "e":3, "i":"pn-53ca01eb-f7c5-4653-9639-ab45b8768d0f", "p":{ "t":"15694740174271958", "r":56 }, "k":"sub-c-d7da9e58-c997-11e9-a139-dab2c75acd6f", "c":"my-channel", "d":{ "source":"actions", "version":"1.0", "data":{ "messageTimetoken":"15694739912496365", "type":"reaction", "value":"smiley_face", "actionTimetoken":"15694740173724452" }, "event":"added" }, "b":"my-channel" } ] }
Body (For messages of type Files)
{ "t":{ "t":"15632184115458813", "r":1 }, "m":[ { "a":"1", "f":514, "p":{ "t":"15632184115444394", "r":1 }, "k":"demo", "c":"my-channel", "d":{ "message":"Hello World", "file":{ "id":"5a3eb38c-483a-4b25-ac01-c4e20deba6d6", "name":"test_file.jpg" } }, "e":"4", "i":"uuid-1", "b":"my-channel" } ] }
Response 400

There was an error with the request

Headers
Content-Type: text/javascript
Body
{ "message": "Invalid Subscribe Key", "error": true, "service": "Access Manager", "status": 400 }
Response 403

Client is not authorized to perform this operation.

Headers
Content-Type: text/javascript
Body
{ "message": "Forbidden", "payload": { "channels": [ "channel" ] }, "error": true, "service": "Access Manager", "status": 403 }
Response 414

Request size exceeds 32KiB.

Headers
Content-Type: text/javascript
Body
{ "status": 414, "service": "Balancer", "error": true, "message": "Request URI Too Long" }
Response 429

The Signal POST body is larger than 32KiB.

Headers
Content-Type: text/javascript
Body
{ "status": 429, "error": true, "message": "Too many requests." }

Files

 

Allows users to upload and share files. You can upload any file of up to 5 MB in size. This feature is commonly used in social apps to share images, or in medical apps to share medical records for patients.

When a file is uploaded on a channel, it's stored and managed using a storage service, and associated with your key. Subscribers to that channel receive a file event which contains a file ID, filename, and optional description.

is also a two-step operation: given a file name and its associated ID, you request a download URL, which returns a 307 redirect to a time-limited download URL.

Get FileGET/v1/files/{sub_key}/channels/{channel}/files/{id}/{name}

Redirects to a download URL for the given file.

Example URI

GET https://ps.pndsn.com/v1/files/mySubKey/channels/ch1/files/5a3eb38c-483a-4b25-ac01-c4e20deba6d6/cat_picture.jpg
Path Parameters
sub_key

string (required) example: demo

Subscribe key

channel

string (required) example: my_channel

Channel on which to perform the file operation

id

string (required) example: 5a3eb38c-483a-4b25-ac01-c4e20deba6d6

PubNub generated ID for the uploaded file.

name

string (required) example: cat_picture.jpg

User-supplied filename

Query Parameters
auth

string (optional) 
Authorization key with permissions to perform the request (if configured)

uuid

string (optional) 
The UUID associated with the action -- max 150 characters

Response  307

307 response to get file presigned url.

Headers
Content-Type: application/json
NameDescriptionType
LocationThe URL to which you're redirected for downloadstring
Example: https://s3.presigned.url.com
Cache-ControlTime, in seconds, the response will be cachedstring
Example: public, max-age=3300, immutable
Response  400

One or more request parameters are invalid.

Response  402

The Files service is not enabled for the subkey.

Response  500

Internal Server Error.

List FilesGET/v1/files/{sub_key}/channels/{channel}/files

List files uploaded to the channel.

Example URI

GET https://ps.pndsn.com/v1/files/mySubKey/channels/ch1/files
Path Parameters
sub_key

string (required) example: demo

Subscribe key

channel

string (required) example: my_channel

Channel on which to perform the file operation

Query Parameters
limit

integer (optional)  Default value: 100
Number of objects to return in the response. Default is 100, which is also the maximum value. Set limit to 0 (zero) and count to true if you want to retrieve only a result count.

next

string (optional) 
URL-safe token to get the next batch of files

auth

string (optional) 
Authorization key with permissions to perform the request (if configured)

uuid

string (optional) 
The UUID associated with the action -- max 150 characters

Response  200

Successfully retrieved the list of uploaded files.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": [ { "name": "cat_picture.jpg", "id": "5a3eb38c-483a-4b25-ac01-c4e20deba6d6", "size": 203923, "created": "2020-04-22T22:48:31Z" } ], "next": "lnlngwonowgong", "count": 100 }
Response  400

One or more request parameters are invalid.

Response  402

The Files service is not enabled for the subkey.

Response  500

Internal Server Error.

Delete FileDELETE/v1/files/{sub_key}/channels/{channel}/files/{id}/{name}

Delete a file.

Example URI

DELETE https://ps.pndsn.com/v1/files/mySubKey/channels/ch1/files/5a3eb38c-483a-4b25-ac01-c4e20deba6d6/cat_picture.jpg
Path Parameters
sub_key

string (required) example: demo

Subscribe key

channel

string (required) example: my_channel

Channel on which to perform the file operation

id

string (required) example: 5a3eb38c-483a-4b25-ac01-c4e20deba6d6

PubNub generated id for the uploaded file.

name

string (required) example: cat_picture.jpg

User-supplied filename

Query Parameters
auth

string (optional) 
Authorization key with permissions to perform the request (if configured)

uuid

string (optional) 
The UUID associated with the action -- max 150 characters

Response  200

The operation was successful.

Headers
Content-Type: application/json
Body
{ "status": 200 }
Response  400

One or more request parameters are invalid.

Response  402

The Files service is not enabled for the subkey.

Response  500

Internal Server Error.

Error responses

  • Response 400

    One or more request parameters are invalid.

    Headers
    Content-Type: application/json
    Body
    { "status": 400, "error": { "source": "Files", "message": "Invalid limit parameter. Limit must be an integer between 1 and 100 (inclusive).", "code": 3001 } }
  • Response 402

    The Files service is not enabled for the subkey.

    Headers
    Content-Type: application/json
    Body
    { "status": 402, "error": { "source": "Files", "message": "File Upload Service not enabled for subkey.", "code": 3005 } }
  • Response 500

    Internal Server Error

    Headers
    Content-Type: application/json
    Body
    { "status": 500, "error": { "source": "Files", "message": "Internal Server Error", "code": 9090 } }

History

Fetch History

History - Valid / Success Responses

  • Array Element 0 – Array – Contains an array of JSON messages. Array will be between 0 and 100 in length, based on the count parameter (default 100) used at request time, and the number of valid messages available for the given time-slice.

  • Array Element 1 – Int – Start Timetoken of returned results,

  • Array Element 2 – Int – End Timetoken of returned results,

Successful (HTTP Status 200) History() calls will always return a three-element array similar to:

[ [MSG1, MSG2, ...], START_TIMETOKEN, END_TIMETOKEN ]

for example: [["Pub1","Pub2","Pub3"],13406746729185766,13406746780720711]

History - Invalid / Error Responses

In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned.

About Timetokens

The timetoken represents a 17-digit precision unix time (UTC). To convert PubNub’s timetoken to Unix timestamp (seconds), divide the timetoken number by 10,000,000 (10^7).

To convert back and forth between current time, A Ruby example follows as:

> now = Time.now => 2012-11-02 14:27:11 -0700 > timetoken = now.to_f * 10000000 => 13518916319742640 > Time.at(timetoken / 10000000) => 2012-11-02 14:27:11 -0700

Paging

Page through History, traversing newest to oldest:

Perform the initial history request, without any start or end parameters (we’ll limit results to two at a time to make this example easier to grok):

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4" --> [["msg4","msg5","msg6","msg7"],14382111171320896,14382111251236844]

Using the start Timetoken provided from the last response, use as the start parameter for the next page:

url "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4&start=14382111171320896" --> [["msg1","msg2","msg3"],14382102111436851,14382102175496790]

Repeat, until you get 0 (zero) back as a start Timetoken. This indicates you are at the end of the list.

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4&start=14382102111436851" --> [[],0,0]`

Fetch HistoryGET/v2/history/sub-key/{sub_key}/channel/{channel}

Use this api to fetch message history.

Example URI

GET https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/ch1?count=100&start=12332312312312312&end=12332312312312312&reverse=false&include_meta=true&stringtoken=false&include_token=false&string_message_token=false&auth=authKey&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

channel
string (required) Example: ch1

channel for which the history is requested

Query Parameters
count
number (optional) Example: 100

The maximum number of messages to return per response. If the count parameter is not provided, the server will default to the maximum value of 100. When the count parameter is provided, you may request between 1 and 100 messages.

start
number (optional) Example: 12332312312312312

If provided, lets you select a "start date", in Timetoken (Unix epoch) format. If not provided, it will default to current time. 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. start is ‘exclusive’ – that is, the first item returned will be the one immediately after the start Timetoken value.

end
number (optional) Example: 12332312312312312

If provided, lets you select an "end date", in Timetoken (Unix epoch) format. If not provided, it will provide up to the number of messages defined in the "count" parameter. 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. End is ‘inclusive’ – that is, if a message is associated exactly with the end Timetoken, it will be included in the result.

reverse
boolean (optional) Example: false

Direction of time traversal. Default is false, which means timeline is traversed newest to oldest.

include_meta
boolean (optional) Example: true

Set to true to include metadata with returned messages. This metadata is set using the meta parameter with the publish operation. Default is false.

stringtoken
boolean (optional) Example: false

If false, 0, or not provided, the returned start and end Timetoken values will be returned as long ints. If 1, or true, the start and end Timetoken values will be returned as strings.

include_token
boolean (optional) Example: false

pass true to recieve a timetoken with each history message. Defaults to false

string_message_token
boolean (optional) Example: false

This option takes effect when include_token is 1, or true. If false, 0, or not provided, the returned Timetokens with each history message will be returned as long ints. If 1, or true, the returned Timetokens with each history message will be returned as strings. This option takes effect when include_token is 0, or False, it is equivalent to stringtoken. Default is false.

auth
string (optional) Example: "authKey"

If the channel is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Response  200
[ [ { "message":"Hello world", "timetoken":15936276818931372, "meta":"" } ], 15936276818931372 ]

Batch HistoryGET/v3/history/sub-key/{sub_key}/channel/{channels}

Use this api to fetch batch of message history

Example URI

GET https://ps.pndsn.com/v3/history/sub-key/mySubKey/channel/ch1,ch2?max=25&start=12332312312312312&end=12332312312312312&include_message_type=true&include_uuid=true&include_meta=true&auth=authKey&encode_channels=true
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

channel
string (required) Example: ch1, ch2

comma separated channels for which the history is requested

Query Parameters
max
number (optional) Example: 25

The batch history is limited to 500 channels and only the last 25 messages per channel. If you specify only a single channel, the maximum value for max is 100. The default value in all cases is 1.

start
number (optional) Example: 12332312312312312

If provided, lets you select a "start date", in Timetoken (Unix epoch) format. If not provided, it will default to current time. 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. start is ‘exclusive’ – that is, the first item returned will be the one immediately after the start Timetoken value.

end
number (optional) Example: 12332312312312312

If provided, lets you select an "end date", in Timetoken (Unix epoch) format. If not provided, it will provide up to the number of messages defined in the "max" parameter. 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. End is ‘inclusive’ – that is, if a message is associated exactly with the end Timetoken, it will be included in the result.

include_message_type
boolean (optional) Example: true

Pass true to receive the message type with each history message.
Defaults to false

include_uuid
boolean (optional) Example: true

Set to true to include uuid with returned messages. This is set using the uuid parameter with the publish operation.
Default is false.

include_meta
boolean (optional) Example: true

Set to true to include metadata with returned messages. This metadata is set using the meta parameter with the publish operation. Default is false.

auth
string (optional) Example: "authKey"

If the channel is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

encode_channels
boolean (optional) Example: true

Set to true, the channel names in the response will be url encoded. Set to false, the channel names in the response will not be url encoded. Default is true.

Response  200
{ "status":200, "error":false, "error_message":"", "channels":{ "demo-channel":[ { "message":"Hello world", "timetoken":15610547826970040, "uuid":"my-uuid", "message_type":1, "meta":"" } ] } }

History With ActionsGET/v3/history-with-actions/sub-key/{sub_key}/channel/{channel}

Show history messages within the given time range, along with their actions. Allows users to get everything they would need to display a single screen in a typical chat application like slack.

  • The response is a list of messages, ordered by ascending timetoken, wherein some of the message objects may by augmented with actions.
  • The actions for a given message are organized first by type, then by value. For a given (type, value) pair, all the unique UUIDs who posted that action will be shown, along with the timetoken when the post occurred. Pagination can be controlled with start, end, and max parameters, similar to the get_actions_by_timetoken operation.
  • The server may truncate the number of messages in the response, due to internal limits on the number of queries which can be performed per request. However, the server will always give "complete" messages, in the sense that the messages returned here will always have all their actions. If truncation of the original query occurs, a "more" link will be provided. This indicates that internal limiting has occurred, and the more link itself can be used to continue fetching the originally requested range of messages.

Consider the scenario where most messages have relatively few actions (<250), but the first message has somehow accumulated 25000 actions. If the user requests 25 messages-with-actions, the first request to history-with-actions would return only the first message, with all of its 25000 actions underneath it, and provide a "more" link to signal that truncation has occurred. Then the next request would contain the other 24 messages along with all their actions.

Example URI

GET https://ps.pndsn.com/v3/history-with-actions/sub-key/{sub_key}/channel/{channel}?include_message_type=true&include_uuid=true&max=25
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

channel

string (required) Example: demo-animal-forest
The channel name.

Query Parameters
include_message_type
boolean (optional) Example: true

Pass true to receive the message type with each history message.
Defaults to false

include_uuid
boolean (optional) Example: true

Pass true to receive the publisher uuid with each history message.
Defaults to false.

auth

string (optional) 
Authorization key with permissions to perform the request (if configured)

start

string (optional) Example: 15610547826970040
Message timetoken denoting the start of the range requested (return values will be less than start)

end

string (optional) 
Message timetoken denoting the end of the range requested (return values will be greater or equal to end)

max

integer (optional)  Default (and maximum) value: 25
Number of messages to return in response.

include_meta

boolean (optional) 
Whether to include metadata along with each message. This metadata is set using the meta parameter with the publish operation. Default is false

Response  200

The messages and actions were fetched.

Headers
Content-Type: application/json
Body
{ "status": 200, "error": false, "error_message": "", "channels": { "demo-channel": [ { "message": "Hi", "timetoken": 15610547826970040, "actions": { "receipt": { "read": [ { "uuid": "user-7", "actionTimetoken": 15610547826970044 } ] } } }, { "message": "Hello", "timetoken": 15610547826970000, "actions": { "reaction": { "smiley_face": [ { "uuid": "user-456", "actionTimetoken": 15610547826970050 } ], "poop_pile": [ { "uuid": "user-789", "actionTimetoken": 15610547826980050 }, { "uuid": "user-567", "actionTimetoken": 15610547826970000 } ] } } } ] }, "more": { "url": "/v3/history-with-actions/s/channel/c?start=15610547826970000&max=98", "start": "15610547826970000", "max": 98 } }
Body (For Files History)
{ "status":200, "error":false, "error_message":"", "channels":{ "demo-channel":[ { "message":"Hello world", "timetoken":15610547826970040, "uuid":"my-uuid", "message_type":1, "meta":"", "actions":{ "receipt":{ "read":[ { "uuid":"user-7", "actionTimetoken":15610547826970044 } ] } } } ] }, "more":{ "url":"/v3/history-with-actions/s/channel/c?start=15610547826970000&max=98", "start":"15610547826970000", "max":98 } }
Response  400

The request was invalid.

Headers
Content-Type: application/json
Body
{ "status": 400, "error": true, "error_message": "Invalid Arguments: start", "channels": {} }

MessageCounts GET /v3/history/sub-key/{sub_key}/message-counts/{channels}

Get message counts for channels.

Returns a list of channels with associated message counts over the given time period. Channels without messages have a count of 0. Channels with 10,000 messages or more have a count of 10000.

Note

For keys with unlimited message retention enabled, this method considers only messages published in the last 30 days.

Example URI

GET https://ps.pndsn.com/v3/history/sub-key/mySubKey/message-counts/myChannel1,myChannel2?channelsTimetoken=15210190573608384,15211140747622125&auth=akey
Path parameters
sub_key
Path Parameter (required) 

Your PubNub subscribe API key.

channels
Path Parameter (required) 

The channel name(s) you wish to pull history from. Separate multiple channel names with commas. Channel names must be comprised of valid characters. May be a single channel, or multiple channels, separated by comma.

Query parameters
timetoken
Query Parameter (optional) 

A single timetoken to cover all channels passed-in on the request path. This parameter is incompatible with channelsTimetoken. Value must be greater than 0 (zero).

channelsTimetoken
Query Parameter (optional) 

A comma-delimited list of timetokens, in order of the channels list, in the request path. If the list of timetokens is not the same length as the list of channels, a 400 bad request error will result. This parameter is incompatible with timetoken. Value must be greater than 0 (zero).

auth
string (optional) Example: "authKey"

If the channel is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

Return type
Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

  • application/json
Response  200

A list of channels with counts of messages in history newer than the passed-in timetoken (greater than operation).

{ "status": 200, "error": false, "error_message": "", "channels": { "myChannel1": 33, "myChannel2": 0 } }
Response  400

Invalid Arguments. This may be due to an invalid subscribe key; missing or invalid timetoken or channelsTimetoken (values must be greater than 0); mismatched number of channels and time tokens; invalid characters in a channel name; or other invalid request data.

Response  403

Storage is not enabled for this subscribe key.

HistoryResponseV3

status
Integer  

API HTTP status code format: int32.

error
Boolean  

TRUE if an error occurred, and FALSE if the operation was successful.

error_message
String (optional) 

Error message content, if applicable.

message
String (optional) 

Error message content from another service, if applicable.

channels
Object (optional) 

Object containing key-value pairs. Each key-value pair is a channel name (string) and a message count (integer).

service
String (optional) 

The service that returned the error. This field is only present if the error is returned by another service, such as Access Manager.

Delete History DELETE /v3/history/sub-key/{sub_key}/channel/{channels}

Delete is allowed only when Delete-with-History is enabled in the subkey settings. If not it will return:

{status: 403, error: true, error_message: "Do not have permission to delete"}.

If parsing the request fails, will return:

{status: 400, error: true, error_message: "Parse error"}.

Delete API is asynchronously processed. Getting a {status: 200, error: false, error_message: ""} implies the Delete request has been received and will be processed soon.

After the delete has been processed, a webhook is called if the subkey specifies one. If multiple (say N) channels are given in the request a single 200 is returned but N webhook calls will be made.

Note

There is a setting to accept delete from history requests for a key, which you must enable by checking the Enable Delete-From-History checkbox in the key settings for your key in the Administration Portal.

Example URI

curl -s -X DELETE -i  https://ps.pndsn.com/v3/history/sub-key/mySubKey/channel/channelfoo?start=14993928130000000&end=14992200130000000
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

channel

string (required) Example: demo-animal-forest
The channel name.

Query Parameters
start
number  (optional) Example:  14993928130000000
end
number  (optional) Example:  14992200130000000
  • If neither start nor end is given, we delete all messages for that channel.
  • If start is given and no end, we delete all messages before the start time. Start time is exclusive, as in message with timestamp start will not be deleted.
  • If end is given and no start, we delete all messages from the current time till the end time. End time is inclusive, as in message with timestamp end will be deleted.
  • If start and end are given, we delete all messages from the start time till the end time. Start time is exclusive and the end time is inclusive.
  • If auth is enabled for subkey, the request needs to have signature.
Response   200
Headers
response.set_header('Content-Type', 'text/javascript; charset="UTF-8"') response.set_header('Cache-Control', 'no-cache') response.set_header('Access-Control-Allow-Origin', '*') response.set_header('Access-Control-Allow-Methods', 'GET') //if message_count is not None: response.set_header('PN-Messages', str(message_count)) if request.headers.get('SSL'): response.set_header('PN-SSL', 'ssl')
Body
{ "status": 200, "error": false, "error_message": "", }
Response   400
Headers
response.set_header('Content-Type', 'text/javascript; charset="UTF-8"') response.set_header('Cache-Control', 'no-cache') response.set_header('Access-Control-Allow-Origin', '*') response.set_header('Access-Control-Allow-Methods', 'GET') //if message_count is not None: response.set_header('PN-Messages', str(message_count)) if request.headers.get('SSL'): response.set_header('PN-SSL', 'ssl')
Body
{ "status": 400, "error": true, "error_message": "Parse error", }
Response   403
Headers
response.set_header('Content-Type', 'text/javascript; charset="UTF-8"') response.set_header('Cache-Control', 'no-cache') response.set_header('Access-Control-Allow-Origin', '*') response.set_header('Access-Control-Allow-Methods', 'GET') //if message_count is not None: response.set_header('PN-Messages', str(message_count)) if request.headers.get('SSL'): response.set_header('PN-SSL', 'ssl')
Body
{ "status": 403, "error": true, "error_message": "Do not have permission to delete", }

Webhook Method POST /v3/history/sub-key/<sub-key>/channel/<channels>

Once the deletion of the requested messages has been performed, PubNub will make a callback to your application to inform you that your request has been completed, and all the requested messages / channels have been completely deleted.

Example URI

curl -i  http://<balancer>/v3/history/sub-key/<sub-key>/channel/<channels>

Retry Policy: Exponential Total retries: 3

The URL that PubNub will make a web hook call to is configurable on a per key basis. You can configure this URL in the Administration Portal under the Storage & Playback settings for your key.

PubNub expects your application to respond to our webhook informing you of the completion of the delete request with an appropriate status response. This can be either 200 or 400, to indicate success or failure to receive the webhook, respectively.

PubNub will include a message in the body of the POST request to your server that indicates more detail of what happened to your deletion request.

Successful completion of the message delete request
Body
{ "error": false, "error_message": "", "channel": channel_deleted }
Unsuccessful completion of the message delete request
Body
{ "error": true, "error_message": "Storage Error", "channel": "" }

Creating a signature with JS Standalone

// Requires the request module: https://www.npmjs.com/package/request

var request = require("request");

// Set your keys (replace with your own)

var pnAPIKeys = {
"subKey": "MySubKey",
"pubKey": "MyPubKey",
"secKey": "MySecretKey"
};

// In this config as it stands, it will delete all messages in the channel
// To delete from an offset or range
// Add start and/or end parameters with PN timetoken integers as values
show all 123 lines

Encrypt Msg Using secret-key as the Encryption Key

key = "mySubKey" //Secret-key

msg = "

{subkey}

{pubkey}

{path}

{params}"

Example:
subkey= mySubKey, pubkey= myPubKey, path= '/v3/history/sub-key/mySubKey/channel/channel1' , params= '"timestamp"=1506666034'

params is REST Query parameters and the timestamp should be the current epoch timestamp when signing.

Then the URI with signature will be

curl -s -X DELETE -i 'http://ps.pndsn.com/v3/history/sub-key/mySubKey/channel/channel1?timestamp=1506666034&signature=uVRcaYccGYlmNUAjHBOSGZ-10O9-sQm8HqYlGomNOCc%3D'

Channel Groups

Listing All Registered Channel Groups

Listing All Registered Channel GroupsGET/v1/channel-registration/sub-key/{sub_key}/channel-group{?uuid}

This endpoint is disabled on most subscribe keys, please contact support@ to confirm endpoint usability

Example URI

GET https://ps.pndsn.com/v1/channel-registration/sub-key/mySubKey/channel-group?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Get all channel groups for subscribe key
Response  200
Headers
Content-Type: application/json
Body
{ "service": "name of the service returning the data", "status": "HTTP status code of the performed action", "error": "returns the reason an error has occoured", "payload": { "sub_key": "subKey", "groups": [ "group1", "group2", "group3" ] } }

Listing all channels for a channel group

Listing all channels for a channel groupGET/v1/channel-registration/sub-key/{sub_key}/channel-group/{group}{?uuid}

Example URI

GET https://ps.pndsn.com/v1/channel-registration/sub-key/mySubKey/channel-group/group1?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

group
string (required) Example: group1

the group for which we need the list of channels

auth
string (optional) Example: "authKey"

If the channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read the channel group.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Get all channels for a channel group
Response  200
Headers
Content-Type: application/json
Body
{ "service": "name of the service returning the data", "status": "HTTP status code of the performed action", "error": "returns the reason an error has occoured", "payload": { "group": "group_id", "channels": [ "channel1", "channel2", "channel3" ] } }

Adding channels // New Channel Group

This endpoint supports both the addition of channels to channel groups and also creating a channel group. To create a new group, pass the name of the desired group as the group name

Adding Channels // New Channel GroupGET/v1/channel-registration/sub-key/{sub_key}/channel-group/{group}{?add,uuid}

Example URI

GET https://ps.pndsn.com/v1/channel-registration/sub-key/mySubKey/channel-group/group1?add=ch1&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

The subscriber key

group
string (required) Example: group1

The channel group to which the channels will be added

add
string (required) Example: ch1

Name of a channel to be added to the channel group. You may add mulitple channels using a comma seperator (ch1,ch2,ch3).

auth
string (optional) Example: "authKey"

If the channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to manage the channel group.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request
Response  200
Headers
Content-Type: application/json
Body
{ "service": "channel-registry", "status": "200", "error": false, "message": "OK" }

Removing channels

Removing channelsGET/v1/channel-registration/sub-key/{sub_key}/channel-group/{group}{?remove,uuid}

Example URI

GET https://ps.pndsn.com/v1/channel-registration/sub-key/mySubKey/channel-group/group1?remove=ch1&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

The subscriber key

group
string (required) Example: group1

The channel group to which the channels will be added

remove
string (required) Example: ch1

Name of a channel to be removed from the channel group. You may add mulitple channels using a comma seperator (ch1,ch2,ch3).

auth
string (optional) Example: "authKey"

If the channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to manage the channel group.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request
Response  200
Headers
Content-Type: application/json
Body
{ "service": "channel-registry", "status": "200", "error": false, "message": "OK" }

Deleting a Channel Group

Deleting a Channel GroupGET/v1/channel-registration/sub-key/{sub_key}/channel-group/{group_name}/remove{?uuid}

Example URI

GET https://ps.pndsn.com/v1/channel-registration/sub-key/mySubKey/channel-group/group1/remove?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

group_name
string (required) Example: group1

the group to be deleted

auth
string (optional) Example: "authKey"

If the channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to manage the channel group.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Deleting a Channel Groups
Response  200
Headers
Content-Type: application/json
Body
{ "service": "channel-registry", "status": "200", "error": false, "message": "OK" }

Access Manager

Access Manager v2

Access Manager v2 provides fine-grained access controls to PubNub Data Streams. It presents a minimal REST API for secure administration tasks, and transparently protects Data Stream resource access. This document divides these two responsibilities clearly into their own sections: REST API and ACL Enforcement.

General Information

  • Global Permissions

    Do not provide auth nor channel in the {signed-content} query-string parameters

  • Channel Permissions

    Provide only a channel parameter, but not auth parameter, this then sets permissions on the channel itself overriding any auth-key permissions

  • AuthKey Permissions

    Provide both auth and channel parameters to set the permissions for one or more channels and one or more auth-keys

Both auth and channel accept comma-separated lists.

Permission Mapping

  • Permissions on channel resource:

    read, write, delete, get, update, manage, join

  • Permissions on channel-group resource:

    read, manage

  • Permissions on uuid resource:

    get, update, delete

Note that wildcards are NOT supported on the uuid resource. Also, you cannot grant permissions for the uuid resource and other resources in the same operation.

Access Manager v3

Access Manager v3 allows you to manage access to PubNub APIs.

You can use Access Manager to generate a time-limited token with permissions for individual resources (such as channels, channel groups, or uuids). Once the permissions are granted, the token must be passed back to the clients so they can perform operations on the PubNub platform. Additionally, you can grant a token to a specific uuid. This uuid will then be solely authorized to perform all operations allowed in the given grant request. All subsequent PubNub API requests made with that token will have to supply that particular uuid in the query string.

You can later revoke the granted token in a single call by sending a DELETE request to the PubNub server. This will disable the token with all embedded permissions. By default, you can revoke tokens with the ttl (time-to-live) parameter set to a maximum of 30 days (43200 minutes).

Enable Access Manage

To use Access Manager, you must first enable it on the Admin Portal. To do that, navigate to your keyset and turn on the ACCESS MANAGER option under the CONFIGURATION tab. Mark the Revoke v3 Token checkbox to enable revokes.

Permission Mapping

  • Permissions on the channel resource:

    read, write, delete, get, update, manage, join

  • Permissions on the (channel) group resource:

    read, manage

  • Permissions on the uuid resource:

    get, update, delete

In Access Manager v3, you can grant permissions for multiple resources in a single API operation, even if permissions grant levels differ. For example, you can grant read to channel1 and write to channel2.

API Operations

The following tables show the mappings of API operations to resources and permissions.

Publish/Subscribe
OperationResourcePermission
Publishchannelwrite
Signalchannelwrite
Firechannelwrite
Subscribechannelread
Channel groups
OperationResourcePermission
Add channelschannel groupmanage
Remove channelschannel groupmanage
List channelschannel groupread
Delete a channel groupchannel groupmanage
Subscribe to a channel groupchannel groupread
Set state on a channel groupchannel groupread
Presence
OperationResourcePermission
Here nowchannelmanage
Where nownonenone
Set statechannelread
Get statechannelread
Subscribe to presencechannel-pnpresread
Push
OperationResourcePermission
Add a device to channelschannelread
Remove a device from channelschannelread
List devices in a channelchannelread
History
OperationResourcePermission
Historychannelmanage
Fetch historychannelnone
Get message countschannelread
Delete messageschanneldelete
Message actions
OperationResourcePermission
Add a message actionchannelwrite
Remove a message actionchanneldelete
Get message actionschannelread
Get history with actionschannelread
Objects v2
OperationResourcePermission
Get channel metadata (including its members)channelget
Set channel metadatachannelupdate
Remove channel metadatachanneldelete
Set/remove channel member metadatachannelmanage
Set/remove uuid membership metadata for a channelchanneljoin
Get uuid metadata (including its membership)uuidget
Set uuid metadata and/or set/remove its channel membership metadatauuidupdate
Remove uuid metadatauuiddelete

Manage permissions

Grant access in v2GET/v2/auth/grant/sub-key/{sub_key}{?signature,auth,uuid}

In this request, the auth-key is the client that has permissions to modify Access Manager permissions, not the auth-key you want to modify permissions on. The one you are changing permissions for is within the parameters.

Example URI

GET https://ps.pndsn.com/v2/auth/grant/sub-key/mySubKey?signature=v2rgQQ1eFzk8omugFV9V1_eKRUvvMv9jyC9ZL1ogdw%3D&auth=myAuthKey&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&
Path Parameters
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key.

Query Parameters
signature
string (required) Example: v2rgQQ1eFzk8omugFV9V1_eKRUvvMv9jyC9ZL1ogdw%3D

A signed request as described in the section above.

auth
string (required) Example: myAuthKey

The Auth key that is being granted permissions.

uuid
string (optional) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

timestamp
int (required) Example: 1234567898

The timetoken represents a 17-digit precision unix time (UTC). To convert PubNub's timetoken to Unix timestamp (seconds), divide the timetoken number by 10,000,000 (10^7).

ttl
int (optional) Example: 15

Time to live for permission to be valid

channel
string (optional) Example: ch1,ch2

Specifies the channels on which to grant permissions. Comma separated values are accepted.

channel-group
string (optional) Example: group1,group2

Specifies the channel groups on which to grant permissions. Comma separated values are accepted.

target-uuid
string (optional) Example: 'user-1,user-2'

Specifies the UUIDs on which to grant permissions. Comma separated values are accepted.

w
boolean (optional) Example: 1

Write permission

r
boolean (optional) Example: 0

Read permission

m
boolean (optional) Example: 0

Manage permission

d
boolean (optional) Example: 0

Delete permission

g
int (optional) Example: 0

Get permission

u
int (optional) Example: 0

Update permission

j
int (optional) Example: 0

Join permission

Request
Response  200
Body
// Depending on the parameters provided (channel name, auth) { "status": 200, "message": "Success", "payload": { "auths": { "myAuthKey": { "d": 0, "g": 0, "j": 0, "m": 0, "r": 1, "u": 0, "w": 0 } }, "subscribe_key": "mySubKey", "ttl": 300, "channel": "my_channel", "level": "user" }, "service": "Access Manager" }
Body (For UUID permissions)
{ "status":200, "message":"Success", "payload":{ "uuids":{ "db9c5e39-7c95-40f5-8d71-125765b6f561":{ "auths":{ "myAuthKey":{ "d":0, "g":1, "j":0, "m":0, "r":0, "u":1, "w":0 } } } }, "subscribe_key":"mySubKey", "ttl":300, "level":"uuid" }, "service":"Access Manager" }

Grant access in v3POST/v3/pam/{sub_key}/grant{?signature,timestamp,uuid}

Grant permissions to PubNub resources, such as channels, channel groups or other users' metadata.

Example URI

POST https://ps.pubnub.com/v3/pam/mySubKey/grant?uuid=uuid-1&timestamp=1595573165&signature=v2.e1H7ZHXXXNCp8X4dMx3tXFGPiIngCMF4ZtN1eKnq05I
Path Parameters
sub_key
string (required) Example: mySubKey

Your PubNub subscribe key.

Query Parameters
uuid
int (optional) Example: uuid-1

A unique alphanumeric ID for tracking and verifying the identity of the caller.

timestamp
int (required) Example: 1595573165

The timetoken represents a 17-digit precision unix time (UTC). To convert PubNub's timetoken to Unix timestamp (seconds), divide the timetoken number by 10,000,000 (10^7).

signature
string (required) Example: v2.e1H7ZHXXXNCp8X4dMx3tXFGPiIngCMF4ZtN1eKnq05I

A string to verify if the request was signed with the secret key associated with the PubNub subscribe key. Refer to v2 Signature Generation in Access Manager v3 for more details.

Request body

The request body takes the form of a JSON object containing ttl that defines the token lifetime (in minutes) and the permissions object that maps resources to permission rules. It may also contain arbitrary application metadata (meta). Permissions can be listed in a sequence (resources) and/or specified as regular expressions (RegEx) (patterns).

The permissions object must contain at least one of resources or patterns properties, meaning at least one of channels, groups, users, spaces, or uuids objects in resources or patterns must be non-empty. It can also contain meta. Additionally, the permissions object may contain the uuid property (string) to designate the uuid that will be solely authorized to use the granted token.

ParameterTypeDescription
ttlIntThe total number of minutes for which the token will remain valid. The minimum allowed ttl is 1 minute. The maximum allowed ttl is 43200 (30 days). This parameter is required and there is no default for it. Once the ttl expires, the read and write attributes are immediately set to false.
permissions.resources.channelsObjectA mapping of channel names to permissions. Read more in Permission Bits.
permissions.resources.groupsObjectA mapping of channel group names to permissions. Read more in Permission Bits.
permissions.resources.usersObjectA mapping of users to permissions. This resource is used only for Objects v1 operations. Read more in Permission Bits.
permissions.resources.spacesObjectA mapping of spaces to permissions. This resource is used only for Objects v1 operations. Read more in Permission Bits.
permissions.resources.uuidsObjectA mapping of uuids to permissions. This resource is used only for Objects v2 operations. Read more in Permission Bits.
permissions.patterns.channelsObject A mapping of regular expressions to permissions for channel names that match the pattern. Read more in Patterns.
permissions.patterns.groupsObjectA mapping of regular expressions to permissions for channel group names that match the pattern. Read more in Patterns.
permissions.patterns.usersObjectA mapping of regular expressions to permissions for Objects v1 users that match the pattern. Read more in Patterns.
permissions.patterns.spacesObjectA mapping of regular expressions to permissions for Objects v1 spaces that match the pattern. Read more in Patterns.
permissions.patterns.uuidsObjectA mapping of regular expressions to permissions for Objects v2 uuids that match the pattern. Read more in Patterns.
permissions.metaObjectThe meta mapping is available for arbitrary key-value pairs, to use as your application sees fit. This mapping may be used for identity/authentication purposes, restricting the token use (in the "public key use" sense as defined by JWK), or exclusions/exceptions.
permissions.uuidString The uuid that will be exclusively authorized to use the granted token. This uuid must be supplied in the query string with every PubNub API request where the granted token is used.
Body (for Objects v2 resources)
{ "ttl":1440, "permissions":{ "resources":{ "channels":{ "ch-1":3 } }, "patterns":{ "uuids":{ "^test\\.*$":32 } }, "uuid":"uuid-1" } }

Permission Bits

The table shows the permission to value mappings that you can assign in the grant token request.

NameValue (Binary)Value (Hex)Value (Dec)Description
READ0b0000_00010x011Applies to Subscribe, History, Presence
WRITE0b0000_00100x022Applies to Publish
MANAGE0b0000_01000x044Applies to Channel-Groups, Objects
DELETE0b0000_10000x088Applies to History, Objects
CREATE0b0001_00000x1016Applies to Objects v1
GET0b0010_00000x2032Applies to Objects v2
UPDATE0b0100_00000x4064Applies to Objects v2
JOIN0b1000_00000x80128Applies to Objects v2

Patterns

Patterns refer to regular expressions that you can use in the grant request to assign permissions to multiple resources at a time, instead of listing them one by one.

For an exact match, a pattern must start with the caret (^) and end with the dollar ($) sign. Otherwise, the permissions will apply to any resource with a full name containing a substring that meets the given pattern.

Response

See a sample response returned by the server after a successful grant token request:

{ "status":200, "data":{ "message":"Success", "token":"p0F2AkF0Gl9f3RpDdHRsGQWgQ3Jlc6REY2hhbqFkY2gtEXAMPLEJwoEN1c3KgQ3NwY6BDcGF0pERjaGFuoENncnCgQ3VzcqBDc3BjoERtZXRhoENzaWdYIIAcmurtZoh58azP5m1Y6HjDHv1Ixt72Xgz8Z2lienYu" }, "service":"Access Manager" }

Returned Token

The response body contains a token that can be provided to the end-user application for access to the resources contained within the token. The token can also be unwrapped by Base 64 decoding (add padding characters as necessary) and then CBOR decoding the binary.

This is an example of the authentication token returned by the Grant v3 API. It can be decoded, then parsed with any CBOR parser.

{ "v":2, "t":1568685146, "ttl":300, "res":{"chan":{"ch1":19}}, "pat":{}, "meta":{}, "sig":"8MzArHKY1DHZLtMOqLG+lzfkSEe8KcbngFQZB6gV1B4=" }
  • v is an integer and represents the version of the token structure. The token signature is not the same as the request signature; the two schemas are incompatible.

  • t and ttl are integers and represent timestamp and time-to-live, respectively. t is generated on the server side, but is usually within some tolerance (+/- 60 seconds) of the timestamp query parameter that generated the token.

  • resis an object that represents the mapping of resource types to resource IDs.

  • patis an object that represents the mapping of resource types to regular expressions.

  • meta is an object that represents the token metadata.

  • uuid is a string that, if requested, represents the uuid solely authorized to use the token.

  • sig is an array of bytes that represents HMAC+SHA256 signed with a PubNub confidential signing key. In the CBOR implementation, sig is a 256-bit bigint.

Revoke access in v3DELETE/v3/pam/{sub_key}/grant/{token_string}?timestamp={timestamp}&signature={v2-signature}&uuid={uuid}

Revoke previously granted token with embedded permissions to PubNub resources.

Example URI

DELETE https://ps.pndsn.com/v3/pam/mySubKey/grant/p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenVzcqBDc3BjoERtZXRhoENzaWdYIGOAeTyWGJI?timestamp=1595573165&signature=v2.e1H7ZHXXXNCp8X4dMx3tXFGPiIngCMF4ZtN1eKnq05I&uuid=uuid-1
Path Parameters
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key.

token_string
string (required) Example: p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenVzcqBDc3BjoERtZXRhoENzaWdYIGOAeTyWGJI

Token string permissions assigned to you in the grant request by the PubNub server. The token must have the URL-encoded format.

Query Parameters
timestamp
Integer (required) Example: 1595573165

Current epoch Unix timestamp (10-digit).

signature
String (required) Example: v2.e1H7ZHXXXNCp8X4dMx3tXFGPiIngCMF4ZtN1eKnq05I

A signed request as described in the section above.

uuid
String (required) Example: uuid-1

The uuid of the server instance that sends a revoke request.

Response status

The table lists all possible resopnse codes.

Status codeDescription
200Successful revoke.
400
  • Passed token is invalid (cannot be parsed by a server).
  • Token signature is invalid (the token’s signature doesn’t match the computed signature).
  • Token version is not supported.
  • Token has expired.
403
  • Request signature is invalid.
  • Token revoke feature disabled for a given subscription key.
503Server encountered unexpected internal error.
Example error response 400
{ "status": 400, "error" : { "message": "Invalid token", "source": "revoke", "details": [{ "message": "Token parse error.", "location": "token", "locationType": "path" }] }, "service": "Access Manager" }
Example error response 403
{ "status": 403, "error" : { "message": "Invalid signature", "source": "revoke", "details": [{ "message": "Client and server produced different signatures for the same inputs.", "location": "signature", "locationType": "query" }] }, "service": "Access Manager" }
Example error response 503
{ "status": 503, "error" : { "message": "Service unavailable", "source": "revoke" }, "service": "Access Manager" }

v2 Signature Generation in Access Manager v2

The signature is used to verify if the request was signed with the secret key associated with the PubNub subscribe key.

  1. Signature is computed using HMAC+SHA256 with the user's secret key as the signing key, and a signing message composed of the HTTP method, publish key, request path, query string, and request body (or empty string) in the following format:

    {method}\n{pub_key}\n{path}\n{query_string}\n{body}

  2. Query parameters must be sorted lexicographically (case-sensitive) by key. Query parameters must be unique (in other words, you may not use &uuid=pubnub-sample&uuid=pubnub-other-sample).

  3. All characters in a query parameter must be percent-encoded, except for the following characters: alphanumeric, hyphen, underscore, and period. This corresponds to the following regular expression:

    /[^0-9a-zA-Z\-_\.]/

  4. Space characters must be replaced by %20 (NOT + character).

  5. Each key-value pair must be separated by ampersand characters.

  6. Unicode characters must be broken up into UTF-8 encoded bytes before percent-encoding. Here is an example of a query string containing Unicode characters; timestamp=1234567898&PoundsSterling=£13.37. And here is the same query string after sorting and percent-encoding; PoundsSterling=%C2%A313.37&timestamp=1234567898

  7. The request body must be appended to the message verbatim (byte-for-byte as provided in the request).

  8. Final signed value should be Base64 encoded using the URL safe characters - and _ replacing + and / respectively.

If your application uses v1 signatures, check out the v1 signature documentation to know more about computing the signature for the request.

Signature Example

Here is a full example message for signature computation for the request:

  • https://ps.pndsn.com/v2/auth/grant/sub-key/sub-demo auth=myAuthKey&target-uuid=user-1&ttl=300&g=1&timestamp=1595619509

  • publish key: pub-demo

  • subscribe key: sub-demo

  • secret key: sec-demo

  • GET query params:

    • auth=myAuthKey
    • g=1
    • target-uuid=user-1
    • timestamp=1595619509
    • ttl=300

We first compose a message of the HTTP method, publish key, request path, query string, and request body (or empty string). Next, the parameters are lexicographically sorted and percent-encoded.

The signature body looks like below.

GET pub-demo /v2/auth/grant/sub-key/sub-demo auth=myAuthKey&g=1&target-uuid=user-1&timestamp=1595619509&ttl=300

Now, let's imagine the demo account's secret key is

sec-demo

The signature generated for this request is Base64 encoded as below.

acKJJbzOVpOEsxbcojtTC6z6BE17AKQRZN9q398vPDI=

Next, we use the "URL safe" characters and replace + and / with - and _ respectively. The padding = characters are stripped from the end. The final step is concatenating the version prefix v2.

Here's the expected signature for this request:

v2.acKJJbzOVpOEsxbcojtTC6z6BE17AKQRZN9q398vPDI

v2 Signature Generation in Access Manager v3

The signature is used to verify if the request was signed with the secret key associated with the PubNub subscribe key.

  • Signature is computed using HMAC+SHA256 with the user's secret key as the signing key, and a signing message composed of the HTTP method, publish key, request path, query string, and request body (or empty string) in the following format:

    {method}\n{pub_key}\n{path}\n{query_string}\n{body}

  • Query parameters must be sorted lexicographically (case-sensitive) by a key. Duplicate keys are not allowed.

  • All characters in the query parameter must be percent-encoded, except for the following characters: alphanumeric, hyphen, underscore, period, and tilde. For example, all characters matching the RegEx /[^0-9a-zA-Z\-_\.~]/ must remain unencoded.

  • Space characters must be replaced by %20 (NOT the + character).

  • Each key-value pair must be separated by an ampersand (&) character.

  • Unicode characters must be broken up into UTF-8 encoded bytes before percent-encoding.

  • See an example of a query string containing unicode characters:

    timestamp=1234567898&PoundsSterling=£13.37

    This is the same query string after sorting and percent-encoding:

    timestamp=1234567898&PoundsSterling=%C2%A313.37
  • The request body must be appended to the message verbatim (byte-for-byte, as provided in the request).

If you need help with calculating the signature, use this online tool.

Access Manager v3 uses signatures in v2, but if your application uses signatures in v1, read the v1 signature documentation to learn more about computing the signature for the request.

Signature Example

Here is a full sample message for signature computation. In this example, the POST body does not have a trailing line break character, but it does have a structural whitespace and is encoded with UTF-8.

POST demo /v3/pam/demo/grant PoundsSterling=%C2%A313.37&timestamp=1234567898 { "ttl": 1440, "permissions": { "resources" : { "channels": { "inbox-jay": 3 }, "groups": {}, "users": {}, "spaces": {} }, "patterns" : { "channels": {}, "groups": {}, "users": {}, "spaces": {} }, "meta": { "user-id": "jay@example.com", "contains-unicode": "The test." } } }

Let's imagine the demo account's secret key is wMfbo9G0xVUG8yfTfYw5qIdfJkTd7A. The signature generated for this request is Base64 encoded:e1H7ZHXXXNCp8X4dMx3tXFGPiIngCMF4ZtN1eKnq05I=. Then, let's use the "URL safe" characters and replace + and / with - and _, respectively. The padding = characters are removed from the end. The final step is concatenating the version prefix v2. The expected signature for this request will look as follows: v2.e1H7ZHXXXNCp8X4dMx3tXFGPiIngCMF4ZtN1eKnq05I.

Presence

Presence is what enables us to say who (UUID) is on a where (channel), when, and how (state).

Identifying Users with UUID

Each REST call uses a URL parameter called UUID. A client's UUID is how the system differentiates one user from another. This is how the user Bob is being differentiated from the user Alice—by UUID.

Presence Events

If you are subscribed to a Presence channel, for any given UUID, you will see Presence events occur in real time on that channel. Those events are named:

  • JOIN (Joined)

  • LEAVE (Explicitly Left)

  • TIMEOUT (Implicitly Left)

  • STATE-CHANGE

Presence events are idempotent – that is, the event will not be repeated (alerted) again until it transitions to another event.

Presence States

For any user, an optional "state" object may be attached to that user's UUID. This state may be set/changed at subscribe (Join) time, or anytime during the sustained Join lifecycle. Once a user transitions to TIMEOUT or LEAVE, that user's associated state (if any) is deleted from the server.

The Different Types of Presence Calls

There are three main classes of Presence methods

  1. The streaming, real-time, subscribe-based presence calls, generally implemented as presence()

  2. The ad-hoc, on-demand presence calls, such as here_now() and where_now(), get_state(), set_state(), and leave()

  3. Long running heartbeat calls, configured via subscribe initializer, and/or via set_hb() and set_hb_interval()

Streaming Presence Calls

To get real-time Presence Events as they occur, subscribe to the presence variant of a channel name. The variant name is the channel you wish to monitor events for, appended with "-pnpres". For example, to subscribe to presence for channel foo, under the hood, we subscribe to channel "foo-pnpres".

Aside from the channel name (channel-pnpres) and the structured data that one can expect from a presence call (vs the relatively random nature of the structured data from user data), there is nothing technically different from a presence call vs a subscribe call.

Ad-hoc, On-demand Presence Calls

In addition to the "fire and forget" streaming presence calls, there are a group of calls that can be called anytime to get the current presence and state information for a given UUID. These methods are:

  • here_now - Who is here, now, on this channel [on this subscribe key]?

  • where_now - Where (which channels) is this UUID currently subscribed on [on this subscribe-key]?

  • get_state - Give me the Presence state info for a given UUID.

  • set_state - Set the Presence state info for a given UUID.

Long running heartbeat calls

By default, the server expects the client to respond to either an intentionally published message, or an empty server "ping" (issued every 270s) within 290s. When this doesn't happen, the Server will transition the UUID from "Join" to "Timeout". (When this does happen as expected, there is no transition – the UUID stays in "Join".)

Some customers require a greater precision to detect a UUID's presence than 270s. To fulfill that requirement, an additional heartbeat (HB) call can be set to "ping", from the client, every n seconds. When this HB is enabled a long-running HB process is started on the client, which will connect to the server every HB-Interval (HBI) seconds.

Using this HB scheme, it's possible to inform the Presence system "if you don't hear from me within x seconds, mark me as TIMEOUT."

By default, if the client is set for a HB of x, the HBI is automatically set to x / 2 - 1. This enables, by default, that under excellent to average-bad network scenarios, the client should be able to "ping" the Presence server between 1 and 2 times before its HB timeout limit.

The user can always override the default HBI to a lower value, but it's important to keep in mind that making this chattier demands extra battery and network resources.

Heartbeat has no functional effect on the performance or integrity of the client itself. Its only provided for Presence functionality.

Heartbeat is the mechanism used to 'ping' back from the client to the server that the client is still online. The heartbeat is only germane to the Presence service.

It affects presence in the following ways:

  • Subscribe calls and Heartbeat calls count as heartbeat signals to Presence—but only on the server RESPONSE does the heartbeat signal register.

  • Since a subscribe call can long poll, the server RESPONSE to the subscribe REQUEST may not be immediate (could be many minutes), so it's not always beneficial to rely on only the subscribe call as the heartbeat.

  • Since the server will RESPOND immediately to the client HB REST API call REQUEST, using the heartbeat call, in concert with subscribe calls, is the perfect method to registering heartbeats with the Presence system.

Transitioning Between Presence Events

Non-Present to Present (Emitting a Join Event)

  • To be "Present", you must go from "Non-Present" to "Present" by subscribing to a channel, and/or sending heartbeats to that channel.

  • Going from "Non-Present" to "Present" emits a "JOIN" event within the Presence system.

  • If the system continues to hear Heartbeats and/or subscribe requests from this client within HEARTBEAT timeout seconds, you will remain "Present".

  • If the client is not currently "JOINED" to a channel, a client heartbeat or subscribe call will create a JOIN event.

  • If the client is currently "JOINED" to a channel, and the server hears the heartbeat or subscribe within HEARTBEAT seconds, the server resets the heartbeat timer, and keeps the client "JOINED" to the channel.

Present back to Not-Present (Emitting a Timeout or Leave Event)

  • The client issues a LEAVE REST call, and stops sending subscribe requests and heartbeat requests. This will generate a "LEAVE" Presence event.

  • The client does not issue a LEAVE REST call, but the server no longer receives subscribe or heartbeat requests from the client within HEARTBEAT timeout seconds. This will generate a "TIMEOUT" Presence event.

  • Once "Not-Present", you can always be "Present" again by repeating this process by subscribing and/or sending a heartbeat.

  • If the client is currently "JOINED" to a channel, and the server DOES NOT hear the heartbeat or subscribe within HEARTBEAT seconds, the server will issue a "TIMEOUT" event for that client.

Heartbeat

Inform presence server user is still active. If user has not been seen before, user will join the channel and send a "join event".

Announce HeartbeatGET/v2/presence/sub-key/{sub_key}/channel/{channel}/heartbeat{?callback,channel-group,heartbeat,state,uuid}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/'mySubKey'/channel/'ch1,ch2'/heartbeat?callback=myFunction&heartbeat=120&state=%7B%22text%22%3A%22hey%22%7D&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: 'mySubKey'

Your PubNub Subscribe API Key

channel
string (required) Example: 'ch1,ch2'

The channel name for which the new state will be applied. Verify that channels are comprised of valid characters. May be a single channel, or multiple channels, separated by comma.

Query Parameters
channel-group
string (optional) Example: cg1,cg2,cg3

Channel group name(s) to subscribe to. If subscribing to more than one channel group, use a comma separator between channel group names. You may subscribe to channels, channels & channel groups, or just channel groups.

auth
string (optional) Example: "authKey"

If the channel / channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

callback
string (required) Example: myFunction

JSONP callback name, or 0 if none.

heartbeat
number (optional) Example: 120

Used to set the presence timeout period. It overrides the default value of 300 for Presence Timeout.

state
string (required) Example: %7B%22text%22%3A%22hey%22%7D

When state is set, this value is an object with root keys associated with each channel you are setting state for. You must be subscribed to a channel to set state for it. (Refer to the get/set state sections)

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Heartbeat
Headers
Location: /v2/presence/sub-key/demo/channel/ch1/heartbeat?uuid=PubNubUnityExample&auth=authKey
Response  200
Headers
Location: /v2/presence/sub-key/demo/channel/ch1/heartbeat?uuid=PubNubUnityExample&auth=authKey Content-Type: application/json
Body
{ "status": 200, "message": "OK", "service": "Presence" }

Setting User State

Set state for a user for a channel(s) and/or channel-group(s).

Setting User StateGET/v2/presence/sub-key/{sub_key}/channel/{channel}/uuid/{uuid}/data{?state,callback}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561/data?state=%7B%22text%22%3A%22hey%22%7D&callback=myFunction
Path Parameters
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s) you are applying the state to. Verify that channels are comprised of valid characters. You may update state to mulitple channels using a comma seperator. If applying state to no channels (only channel groups), use a comma char (,) as a placeholder. You may apply state to channels, channels & channel groups, or just channel groups.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Query Parameters
channel-group
string (optional) Example: cg1,cg2,cg3

Channel group name(s) to which you are applying the new state. If applying state to more than one channel group, use a comma separator between channel group names. You may apply state to channels, channels & channel groups, or just channel groups.

auth
string (optional) Example: "authKey"

If the channel / channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

state
string (required) Example: %7B%22text%22%3A%22hey%22%7D

url-encoded json which will be associated with the UUID for the channels and/or channel groups

callback
string (optional) Example: myFunction

If provided, wraps the response in function (JSONP)

Request  Setting User State
Headers
Location: /v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561/data?state=%7B%22text%22%3A%22hey%22%7D&callback=0
Response  200
Headers
Location: /v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561/data?state=%7B%22text%22%3A%22hey%22%7D&callback=0 Content-Type: application/json
Body
{ "service": "presence", "status": "200", "error": false, "message": "OK", "payload": "{text:hey}" }

Getting User State

Get state for a user for a channel(s) and/or channel-group(s).

Getting User StateGET/v2/presence/sub-key/{sub_key}/channel/{channel}/uuid/{uuid}{?callback}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561?callback=myFunction
Path Parameters
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s) you are fetching the state for. Verify that channels are comprised of valid characters. You may fetch state for mulitple channels using a comma seperator. If fetching state to no channels (only channel groups), use a comma char (,) as a placeholder. You may fetch state to channels, channels & channel groups, or just channel groups.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Query Parameters
channel-group
string (optional) Example: cg1,cg2,cg3

Channel group name(s) to which you are fetching the state. If fetching state for more than one channel group, use a comma separator between channel group names. You may fetch state for channels, channels & channel groups, or just channel groups.

auth
string (optional) Example: "authKey"

If the channel / channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

callback
string (optional) Example: myFunction

If provided, wraps the response in function (JSONP)

Request  Getting User State
Headers
Location: /v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561?state=%7B%22text%22%3A%22hey%22%7D&callback=0
Response  200
Headers
Location: /v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561?state=%7B%22text%22%3A%22hey%22%7D&callback=0 Content-Type: application/json
Body
{ "service": "presence", "status": "200", "error": false, "message": "OK", "payload": "{text:hey}" }

Announce Leave

Indicate to the PubNub Presence system that a device has left a channel(s).

via GETGET/v2/presence/sub-key/{sub_key}/channel/{channel}/leave{?callback,uuid}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/mySubKey/channel/ch1/leave?callback=myFunction&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s), separated by comma, that you wish to send leave events for. Verify that channels are comprised of valid characters.

Query Parameters
channel-group
string (optional) Example: cg1,cg2,cg3

The channel group name(s), separated by comma, that you wish to send leave events for. Verify that channels are comprised of valid characters. You may leave channels, channels & channel groups, or just channel groups.

auth
string (optional) Example: "authKey"

If the channel / channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

callback
string (optional) Example: myFunction

If provided, wraps the response in function (JSONP)

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Announce Leave
Headers
Location: /v2/presence/sub-key/demo/channel/ch1/leave?pnsdk=PubNub-Go/4.2.4&uuid=pn-6ee661a1-85f5-406b-b3c7-e20ca07c07ba&auth=akey&timestamp=1565094167
Response  200
Headers
Location: /v2/presence/sub-key/demo/channel/ch1/leave?pnsdk=PubNub-Go/4.2.4&uuid=pn-6ee661a1-85f5-406b-b3c7-e20ca07c07ba&auth=akey&timestamp=1565094167 Content-Type: application/json
Body
{ "status": 200, "message": "OK", "action": "leave", "service": "Presence" }

via POSTPOST/v2/presence/sub-key/{sub_key}/channel/{channel}/leave{?callback,uuid}

Example URI

POST https://ps.pndsn.com/v2/presence/sub-key/mySubKey/channel/ch1/leave?callback=myFunction&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s), separated by comma, that you wish to send leave events for. Verify that channels are comprised of valid characters.

Query Parameters
channel-group
string (optional) Example: cg1,cg2,cg3

The channel group name(s), separated by comma, that you wish to send leave events for. Verify that channels are comprised of valid characters. You may leave channels, channels & channel groups, or just channel groups.

auth
string (optional) Example: "authKey"

If the channel / channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

callback
string (optional) Example: myFunction

If provided, wraps the response in function (JSONP)

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Here Now

Retrieve UUID and State Information for subscribed devices on a specific channel.

Here NowGET/v2/presence/sub-key/{sub_key}/channel/{channel}{?disable_uuids,state,callback,uuid}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/'mySubKey'/channel/'ch1,ch2'?disable_uuids=0&state=0&callback=myFunction&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: 'mySubKey'

Your PubNub Subscribe API Key

channel
string (required) Example: 'ch1,ch2'

The channel name from which you wish to get the UUIDs of the actively subscribed occupants. Verify that channels are comprised of valid characters. May be a single channel, or multiple channels, separated by comma.

Path Parameters
channel-group
string (optional) Example: cg1,cg2,cg3

Comma delimited list of channel groups that presence should be returned for as well. When channel-groups are included, the response format will be different than when channel-groups are not included.

auth
string (optional) Example: "authKey"

If the channel / channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

disable_uuids
string (optional) Example: 0

If true or 1, or not provided, UUIDS, and accompanying state info, will not be returned, only occupancy numbers. If 0, or false, UUIDS, will be returned with occupancy numbers.

state
string (optional) Example: 0

If false or 0, state info is not returned. If true or 1, AND disable_uuids is false, accompanying state info for each UUID is provided.

callback
string (optional) Example: myFunction

If provided, returns a JSONP function-wrapped response.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Here Now
Headers
Location: /v2/subscribe/demo/ch,ch-pnpres/0?q1=v1&auth=akey&timestamp=1565093044&heartbeat=120&tt=15650930446689601&q2=v2&uuid=pn-4152c98f-0b60-404c-9719-c42dbf8fc246
Response  200
Headers
Location: /v2/subscribe/demo/ch,ch-pnpres/0?q1=v1&auth=akey&timestamp=1565093044&heartbeat=120&tt=15650930446689601&q2=v2&uuid=pn-4152c98f-0b60-404c-9719-c42dbf8fc246 Content-Type: application/json
Body
{ "status": 200, "message": "OK", "occupancy": 1, "uuids": ["pn-4152c98f-0b60-404c-9719-c42dbf8fc246"], "service": "Presence" }

Where Now

Get list of channels user is present in.

Where NowGET/v2/presence/sub-key/{sub_key}/uuid/{uuid}{?callback,uuid}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/'mySubKey'/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561?callback=myFunction&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: 'mySubKey'

Your PubNub Subscribe API Key

Path Parameters
auth
string (optional) Example: "authKey"

If the channel / channel group is protected by Access Manager, auth must be passed with a key or token (depending on the Access Manager version) which is authorized to read from the channel.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

callback
string (optional) Example: myFunction

If provided, returns a JSONP function-wrapped response.

Request  Where Now
Headers
Location: /v2/presence/sub-key/demo/uuid/pn-4152c98f-0b60-404c-9719-c42dbf8fc246?pnsdk=PubNub-Go/4.2.4&uuid=pn-4152c98f-0b60-404c-9719-c42dbf8fc246&auth=akey&timestamp=1565093804
Response  200
Headers
Location: /v2/presence/sub-key/demo/uuid/pn-4152c98f-0b60-404c-9719-c42dbf8fc246?pnsdk=PubNub-Go/4.2.4&uuid=pn-4152c98f-0b60-404c-9719-c42dbf8fc246&auth=akey&timestamp=1565093804 Content-Type: application/json
Body
{ "status": 200, "message": "OK", "payload": { "channels": [ "my-channel" ] }, "service": "Presence" }

Push Notifications || APN & GCM

Authorize and Revoke push tokens for the Apple and Google Push Notification services.

NOTE: The PubNub Push feature now support APNs HTTP/2 and this support involves different API calls and different publish payloads.

The type parameter indicates the back end which PubNub will utilize:

  • apns - Apple Push Notification service

  • gcm - Firebase Cloud Messaging push notification service

Publishing

Given a channel ch1, and subscribed mobile clients, a server SDK must execute a publish commend by sending the following JSON payload to ch1

APNs HTTP/2 Example:

{ "pn_apns": { "aps": { "alert": "hello world" }, "pn_push": [ { "targets": [ { "environment": "production", "topic": "BUNDLE_ID_FOR_APP_1" } ], "version": "v2" } ] } }

Non-APNs HTTP/2 Example:

{ "pn_apns": { "aps": { "alert": "hi", "badge": 2, "sound": "melody" }, "pn_other": { "additional": "fields" } } }
{ "pn_gcm": { }, "pn_other": { "additional": "fields" } }

Please refer to the tutorial for additional examples

NOTE: The next set of Push-related resources are to be used for APNs HTTP/2 implementations.

Managing device registrations (APNs HTTP/2)

Add, or Remove a device from a channelGET/v2/push/sub-key/{sub_key}/devices-apns2/{devices-apns2}?{uuid,auth,add,remove,environment,topic}

Add and remove channels in a single API call. If the "add" or "remove" query parameters are absent, a list of channels that meet the provided criteria is returned.

Example URI

  https://ps.pndsn.com /v2/push/sub-key/mySubKey/devices-apns2/A332C23D?environment=development&topic=com.somedomain.appname
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

devices-apns2
string (required) Example: A332C23D

the id/token of the device

Query Parameters
uuid
string (optional) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

UUID of the client

auth
string (optional) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3

Access Manager authorization key or token (depending on the Access Manager version)

add
string (optional) Example: channel1
  • indicates list of channels to which the device should be added, for push registration (multiple channels are also supported by comma delimited (ch1,ch2,ch3) will add three channels)
remove
string (optional) Example: channel1

name of the channel for which the device will no longer receive push notifications (multiple channels are also supported by commad delimited (ch1,ch2,ch3) will remove three channels)

environment
string (required) 
  • either "development" or "production", denoting the environment of the mobile application
topic
string (required) Example: com.my.app.Application

bundle ID of the mobile application

Remove a device from a channel GET/v2/push/sub-key/{sub_key}/devices-apns2/{devices-apns2}/remove?{uuid,auth,environment,topic}

Bulk modification of a device, allowing for removal of all registered channels at once, for a given device, without specifying all of the channels.

Example URI

  https://ps.pndsn.com /v2/push/sub-key/mySubKey/devices-apns2/A332C23D/remove
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

devices-apns2
string (required) Example: A332C23D

the id/token of the device

Query Parameters
uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

UUID of the client

auth
string (required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3

Access Manager authorization key or token (depending on the Access Manager version)

add
string (required) Example: channel1
  • indicates list of channels to which the device should be added, for push registration (multiple channels are also supported by comma delimited (ch1,ch2,ch3) will add three channels)
remove
string (required) Example: channel1

name of the channel for which the device will no longer recieve push notifications (multiple channels are also supported by commad delimited (ch1,ch2,ch3) will remove three channels)

environment
string (required) 
  • either "development" or "production", denoting the environment of the mobile application
topic
string (required) Example: com.my.app.Application

bundle ID of the mobile application

NOTE: The next set of Push-related resources are to be used for non-APNs HTTP/2 implementations.

Listing registrations for device

Listing registrations for deviceGET/v1/push/sub-key/{sub_key}/devices/{push_token}{?type,uuid}

Example URI

GET https://ps.pndsn.com/v1/push/sub-key/mySubKey/devices/A332C23D?type=apns&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

push_token
string (required) Example: A332C23D

the push token of the device

Query Parameters
type
string (required) 
  • indicates the back end to use (apns for apple, gcm for google)
uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  show all channels for device for apple services
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?type=apns
Response  200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  show all channels for device for google services
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?type=gcm
Response  200
Headers
Content-Type: application/json
Body
+ [] <!-- TODO -->

Removing a Device

Removing all registrations for a deviceGET/v1/push/sub-key/{sub_key}/devices/{push_token}/remove{?type,uuid}

Example URI

GET https://ps.pndsn.com/v1/push/sub-key/mySubKey/devices/A332C23D/remove?type=apns&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

push_token
string (required) Example: A332C23D

the push token of the device

Query Parameters
type
string (required) 
  • indicates the back end to use (apns for apple, gcm for google)
uuid
string (optional) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Removing an Apple device from all push notifications
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D/remove?type=apns
Response  200
Headers
Content-Type: application/json
Request  Removing an Android device from all push notifications
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D/remove?type=gcm
Response  200
Headers
Content-Type: application/json

Adding Registrations

Adding registrationsGET/v1/push/sub-key/{sub_key}/devices/{push_token}{?uuid,auth,type,add}

Example URI

GET https://ps.pndsn.com/v1/push/sub-key/mySubKey/devices/A332C23D?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&auth=385dfa9c-6a16-4145-aaf9-043f0060c7d3&type=apns&add=channel1
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

push_token
string (required) Example: A332C23D

the push token of the device

Query Parameters
uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

UUID of the client

auth
string (required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3

Access Manager authorization key or token (depending on the Access Manager version)

type
string (required) 
  • indicates the back end to use (apns for apple, gcm for google)
add
string (required) Example: channel1

name of the channel to allow the device to recieve notifiactions for (multiple channels are also supported by commad delimited (ch1,ch2,ch3) will add three channels)

Request  Subscribe a device to channel for apple services
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=apns&add=ch1
Response  200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  Subscribe a device to channel for google services
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=gcm&add=ch1
Response  200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]

Removing Registrations

Removing registrationsGET/v1/push/sub-key/{sub_key}/devices/{push_token}{?uuid,auth,type,remove}

Example URI

GET https://ps.pndsn.com/v1/push/sub-key/mySubKey/devices/A332C23D?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&auth=385dfa9c-6a16-4145-aaf9-043f0060c7d3&type=apns&remove=channel1
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

push_token
string (required) Example: A332C23D

the push token of the device

Query Parameters
uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

UUID of the client

auth
string (required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3

Access Manager authorization key or token (depending on the Access Manager version)

type
string (required) 
  • indicates the back end to use (apns for apple, gcm for google)
remove
string (required) Example: channel1

name of the channel for which the device will no longer recieve push notifications (multiple channels are also supported by commad delimited (ch1,ch2,ch3) will remove three channels)

Request  Remove a device from push notifications for channel ch1 for apple services
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=apns&remove=ch1
Response  200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  Remove a device from push notifications for channel ch1 for google services
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=gcm&remove=ch1
Response  200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]

Mixing add & remove operations

Mixing add & remove operationsGET/v1/push/sub-key/{sub_key}/devices/{push_token}{?uuid,auth,type,add,remove}

Mixing the addition and removal operations will be executed in the following order:

  1. channels passed in the remove will be removed from the registrations list for the device

  2. channels passed in the add will be added to the registrations list for the device

Example URI

GET https://ps.pndsn.com/v1/push/sub-key/mySubKey/devices/A332C23D?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&auth=385dfa9c-6a16-4145-aaf9-043f0060c7d3&type=apns&add=channel1&remove=channel1
Path Parameters
sub_key
string (required) Example: mySubKey

the subscriber key

push_token
string (required) Example: A332C23D

the push token of the device

Query Parameters
uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

UUID of the client

auth
string (required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3

Access Manager authorization key or token (depending on the Access Manager version)

type
string (required) 
  • indicates the back end to use (apns for apple, gcm for google)
add
string (required) Example: channel1

comma delimited channels to allow the device to recieve notifiactions for. Also supports comma delited list for multiple channels. ch1,ch2,ch3 will add three channels

remove
string (required) Example: channel1

commad delimited channels for which the device will no longer recieve push notifications. Also supports comma delited list for multiple channels. (ch1,ch2,ch3) will remove three channels

Request  Remove a device from push notifications for channels ch1,ch2 for apple services
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=apns&remove=ch1,ch2
Response  200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  Remove a device from push notifications for channels ch1,ch2 for google services
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=gcm&remove=ch1,ch2
Response  200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]

Objects

The Objects V1 API has been deprecated

If you have questions about the Objects V2 API or require additional help with migrating to the new data model, please contact PubNub Support at support@pubnub.com.

 

The Objects API enables you to create and retrieve data associated with channels and users in the PubNub platform.

User

Manage metadata for users

Get metadata for all usersGET/v2/objects/{sub_key}/uuids

Returns a paginated list of metadata objects for users, optionally including custom data objects.

Example URI

GET https://ps.pndsn.com/v2/objects/{sub_key}/uuids
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex User metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

limit

integer (optional)  Default value: 100
Number of objects to return in the response. Default is 100, which is also the maximum value. Set limit to 0 (zero) and count to true if you want to retrieve only a result count.

start

string (optional) 
Previously-returned cursor bookmark for fetching the next page.

end

string (optional) 
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional)  Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted. To retrieve only a result count, set count to true, and set limit to 0 (zero).

filter

string (optional) 
Expression used to filter the results, Read more.

sort

array (optional) 
List of properties to sort by. Available options are id, name, and updated.
Append :asc or :desc to a property to specify sort direction. The default sort direction is ascending.

auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Response  200

Successfully returned the list of User metadata.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": [ { "id": "uuid-1", "name": "John Doe", "externalId": null, "profileUrl": null, "email": "john@example.com", "custom": null, "updated": "2019-02-20T23:11:20.893755", "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg==" }, { "id": "uuid-2", "name": "Bob Cat", "externalId": null, "profileUrl": null, "email": "bobc@example.com", "custom": { "phone": "999-999-9999" }, "updated": "2019-02-21T03:29:00.173452", "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg==" } ] }
Response  304

The requested resource hasn't been modified since you last retrieved it.

Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Get user metadataGET/v2/objects/{sub_key}/uuids/{uuid}

Returns metadata for the specified UUID and optionally including the user's custom data.

Example URI

GET https://ps.pndsn.com/v2/objects/{sub_key}/uuids/{uuid}
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

uuid

string (required) Example: charlie
Unique identifier of an end-user. Must not be empty, and may contain up to 92 UTF-8 byte sequences.
Prohibited characters are ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex User metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Response  200

Successfully retrieved the requested User metadata.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": { "id": "uuid-1", "name": "John Doe", "externalId": null, "profileUrl": null, "email": "john@example.com", "updated": "2019-02-20T23:11:20.893755", "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg==" } }
Response  304

The requested resource hasn't been modified since you last retrieved it.

Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  404

The requested resource wasn't found.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Set user metadataPATCH/v2/objects/{sub_key}/uuids/{uuid}

Set metadata for a uuid in the database. Returns the user metadata and optionally includes the custom data.

Notes:

  • You can change all of the User object's properties, except its identifier.
  • Invalid property names are silently ignored and will not cause a request to fail.
  • If you set the custom property, you must completely replace it; partial updates aren't supported.
  • The custom object can only contain scalar values.

Example URI

PATCH https://ps.pndsn.com/v2/objects/{sub_key}/uuids/{uuid}
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

uuid

string (required) Example: charlie
Unique identifier of an end-user. Must not be empty, and may contain up to 92 UTF-8 byte sequences.
Prohibited characters are ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex User metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Request body  (required)

JSON object with User metadata to set.

Headers
Content-Type: application/json
Body
{ "name": "John Doe", "externalId": null, "profileUrl": null, "email": "john@example.com" }
Response  200

Successfully set User metadata.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": { "id": "uuid-1", "name": "John Doe", "externalId": null, "profileUrl": null, "email": "john@example.com", "updated": "2019-02-20T23:11:20.893755", "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg==" } }
Response  400

The request body contains invalid data.

Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  412

The conditional operation can't be performed because the target resource has changed since the last retrieval.

Response  415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Remove user metadataDELETE/v2/objects/{sub_key}/uuids/{uuid}

Deletes metadata for the specified UUID.

Example URI

DELETE https://ps.pndsn.com/v2/objects/{sub_key}/uuids/{uuid}
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

uuid

string (required) Example: charlie
Unique identifier of an end-user. Must not be empty, and may contain up to 92 UTF-8 byte sequences.
Prohibited characters are ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Response  200

Successfully deleted User metadata.

Headers
Content-Type: application/json
Body
{ "status": 0, "data": {} }
Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  412

The conditional operation can't be performed because the target resource has changed since the last retrieval.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Channel

Manage metadata for channels

Get metadata for all channelsGET/v2/objects/{sub_key}/channels

Returns metadata for all channels, optionally including custom properties.

Example URI

GET https://ps.pndsn.com/v2/objects/{sub_key}/channels
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex channel metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

limit

integer (optional)  Default value: 100
Number of objects to return in the response. Default is 100, which is also the maximum value. Set limit to 0 (zero) and count to true if you want to retrieve only a result count.

start

string (optional) 
Previously-returned cursor bookmark for fetching the next page.

end

string (optional) 
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional)  Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted. To retrieve only a result count, set count to true, and set limit to 0 (zero).

filter

string (optional) 
Expression used to filter the results, Read more.

sort

array (optional) 
List of properties to sort by. Available options are id, name, and updated.
Append :asc or :desc to a property to specify sort direction. The default sort direction is ascending.

auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Response  200

Successfully returned the list of channel metadata.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": [ { "id": "my-channel", "name": "My channel", "description": "A channel that is mine", "custom": null, "updated": "2019-02-20T23:11:20.893755", "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg==" }, { "id": "main", "name": "Main channel", "description": "The main channel", "custom": { "public": true, "motd": "Always check your spelling!" }, "updated": "2019-02-20T23:11:20.893755", "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg==" } ], "totalCount": 9, "next": "MUIwQTAwMUItQkRBRC00NDkyLTgyMEMtODg2OUU1N0REMTNBCg==", "prev": "M0FFODRENzMtNjY2Qy00RUExLTk4QzktNkY1Q0I2MUJFNDRCCg==" }
Response  304

The requested resource hasn't been modified since you last retrieved it.

Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Get channel metadataGET/v2/objects/{sub_key}/channels/{channel}

Returns metadata for the specified channel, optionally including custom properties.

Example URI

GET https://ps.pndsn.com/v2/objects/{sub_key}/channels/{channel}
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

channel

string (required) Example: main
Channel identifier. Must not be empty, and may contain up to 92 UTF-8 byte sequences.
Prohibited characters are ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex channel metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Response  200

Successfully returned metadata for the requested channel.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": { "id": "my-channel", "name": "My channel", "description": "A channel that is mine", "updated": "2019-02-20T23:11:20.893755", "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg==" } }
Response  304

The requested resource hasn't been modified since you last retrieved it.

Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  404

The requested resource wasn't found.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Set channel metadataPATCH/v2/objects/{sub_key}/channels/{channel}

Sets metadata for the specified channel. Returns the channel object, optionally including custom properties.

Notes:

  • You can change all of the channel's metadata, except its identifier.
  • Invalid property names are silently ignored and will not cause a request to fail.
  • If you set the custom property, you must completely replace it; partial updates aren't supported.
  • The custom object can only contain scalar values.

Example URI

PATCH https://ps.pndsn.com/v2/objects/{sub_key}/channels/{channel}
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

channel

string (required) Example: main
Channel identifier. Must not be empty, and may contain up to 92 UTF-8 byte sequences.
Prohibited characters are ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex channel metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Request body  (required)

JSON object with channel metadata to set.

Headers
Content-Type: application/json
Body
{ "name": "My channel", "description": "A channel that is mine" }
Response  200

Successfully set channel metadata.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": { "id": "my-channel", "name": "My channel", "description": "A channel that is mine", "updated": "2019-02-20T23:11:20.893755", "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg==" } }
Response  400

The request body contains invalid data.

Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  412

The conditional operation can't be performed because the target resource has changed since the last retrieval.

Response  415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Remove channel metadataDELETE/v2/objects/{sub_key}/channels/{channel}

Deletes metadata for the specified channel.

Example URI

DELETE https://ps.pndsn.com/v2/objects/{sub_key}/channels/{channel}
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

channel

string (required) Example: main
Channel identifier. Must not be empty, and may contain up to 92 UTF-8 byte sequences.
Prohibited characters are ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Response  200

Successfully deleted channel metadata.

Headers
Content-Type: application/json
Body
{ "status": 0, "data": {} }
Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  412

The conditional operation can't be performed because the target resource has changed since the last retrieval.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Membership

Manage membership metadata by channel and user

Get membershipsGET/v2/objects/{sub_key}/uuids/{uuid}/channels

Returns channel membership metadata for the specified UUID, optionally including custom properties for the following: the User's perspective on their membership set (custom), the User's perspective on the channel (channel), and the channel's custom data (channel.custom).

Example URI

GET https://ps.pndsn.com/v2/objects/{sub_key}/uuids/{uuid}/channels
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

uuid

string (required) Example: charlie
Unique identifier of an end-user. Must not be empty, and may contain up to 92 UTF-8 byte sequences.
Prohibited characters are ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
include

array[string] (optional)  Available values : custom, channel, channel.custom
List of additional/complex membership metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

limit

integer (optional)  Default value: 100
Number of objects to return in the response. Default is 100, which is also the maximum value. Set limit to 0 (zero) and count to true if you want to retrieve only a result count.

start

string (optional) 
Previously-returned cursor bookmark for fetching the next page.

end

string (optional) 
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional)  Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted. To retrieve only a result count, set count to true, and set limit to 0 (zero).

filter

string (optional) 
Expression used to filter the results, Read more.

sort

array (optional) 
List of properties to sort by. Available options are updated channel.id, channel.name, and channel.updated.
Append :asc or :desc to a property to specify sort direction. The default sort direction is ascending.

auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Response  200

Successfully returned the User's channel memberships.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": [ { "channel": { "id": "my-channel", "name": "My channel", "description": "A channel that is mine", "custom": null, "updated": "2019-02-20T23:11:20.893755", "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg==" }, "custom": { "starred": false }, "updated": "2019-02-20T23:11:20.893755", "eTag": "RUNDMDUwNjktNUYwRC00RTI0LUI1M0QtNUUzNkE2NkU0MEVFCg==" }, { "channel": { "id": "main", "name": "Main channel", "description": "The main channel", "custom": { "public": true, "motd": "Always check your spelling!" }, "updated": "2019-02-20T23:11:20.893755", "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg==" }, "updated": "2019-02-20T23:11:20.893755", "eTag": "RUNDMDUwNjktNUYwRC00RTI0LUI1M0QtNUUzNkE2NkU0MEVFCg==" } ], "totalCount": 7, "next": "RDIwQUIwM0MtNUM2Ni00ODQ5LUFGRjMtNDk1MzNDQzE3MUVCCg==", "prev": "MzY5RjkzQUQtNTM0NS00QjM0LUI0M0MtNjNBQUFGODQ5MTk2Cg==" }
Response  304

The requested resource hasn't been modified since you last retrieved it.

Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Add, update or remove membershipsPATCH/v2/objects/{sub_key}/uuids/{uuid}/channels

Sets channel membership metadata for the specified UUID. Use the set and delete properties in the request body to perform those operations on one or more memberships.
Returns the updated User's channel membership metadata, optionally including:

  • the User's custom properties
  • the custom properties for the User's membership in each channel
  • each channel's custom properties

Notes:

  • You can change all of the membership object's properties, except its identifier.
  • Invalid property names are silently ignored and will not cause a request to fail.
  • If you set the custom property, you must completely replace it; partial updates aren't supported.
  • The custom object can only contain scalar values.

Example URI

PATCH https://ps.pndsn.com/v2/objects/{sub_key}/uuids/{uuid}/channels
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

uuid

string (required) Example: charlie
Unique identifier of an end-user. Must not be empty, and may contain up to 92 UTF-8 byte sequences.
Prohibited characters are ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
include

array[string] (optional)  Available values : custom, channel, channel.custom
List of additional/complex membership metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

limit

integer (optional)  Default value: 100
Number of objects to return in the response. Default is 100, which is also the maximum value. Set limit to 0 (zero) and count to true if you want to retrieve only a result count

start

string (optional) 
Previously-returned cursor bookmark for fetching the next page.

end

string (optional) 
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional)  Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted. To retrieve only a result count, set count to true, and set limit to 0 (zero).

filter

string (optional) 
Expression used to filter the results, Read more.

sort

array (optional) 
List of properties to sort by. Available options are id, name, and updated.
Append :asc or :desc to a property to specify sort direction. The default sort direction is ascending.

auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Request body  (required)

JSON object with changes to the User's channel membership metadata.

Headers
Content-Type: application/json
Body
{ "set": [ { "channel": { "id": "my-channel" }, "custom": { "starred": true } } ], "delete": [ { "channel": { "id": "my-channel" } } ] }
Response  200

Successfully set the User's channel membership metadata.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": [ { "channel": { "id": "my-channel", "name": "My channel", "description": "A channel that is mine", "custom": null, "updated": "2019-02-20T23:11:20.893755", "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg==" }, "custom": { "starred": false }, "updated": "2019-02-20T23:11:20.893755", "eTag": "RUNDMDUwNjktNUYwRC00RTI0LUI1M0QtNUUzNkE2NkU0MEVFCg==" }, { "channel": { "id": "main", "name": "Main channel", "description": "The main channel", "custom": { "public": true, "motd": "Always check your spelling!" }, "updated": "2019-02-20T23:11:20.893755", "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg==" }, "updated": "2019-02-20T23:11:20.893755", "eTag": "RUNDMDUwNjktNUYwRC00RTI0LUI1M0QtNUUzNkE2NkU0MEVFCg==" } ], "totalCount": 7, "next": "RDIwQUIwM0MtNUM2Ni00ODQ5LUFGRjMtNDk1MzNDQzE3MUVCCg==", "prev": "MzY5RjkzQUQtNTM0NS00QjM0LUI0M0MtNjNBQUFGODQ5MTk2Cg==" }
Response  400

The request body contains invalid data.

Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Get members in a channelGET/v2/objects/{sub_key}/channels/{channel}/uuids

Returns the members' metadata in the specified channel, optionally including:

  • each User's custom properties
  • the custom properties for each User's membership in the channel
  • the channel's custom properties

Example URI

GET https://ps.pndsn.com/v2/objects/{sub_key}/channels/{channel}/uuids
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

channel

string (required) Example: main
Channel identifier. Must not be empty, and may contain up to 92 UTF-8 byte sequences.
Prohibited characters are ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
include

array[string] (optional)  Available values : custom, uuid, uuid.custom
List of additional/complex membership metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

limit

integer (optional)  Default value: 100
Number of objects to return in the response. Default is 100, which is also the maximum value. Set limit to 0 (zero) and count to true if you want to retrieve only a result count.

start

string (optional) 
Previously-returned cursor bookmark for fetching the next page.

end

string (optional) 
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional)  Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted. To retrieve only a result count, set count to true, and set limit to 0 (zero).

filter

string (optional) 
Expression used to filter the results, Read more.

sort

array (optional) 
List of properties to sort by. Available options are updated uuid.id, uuid.name, and uuid.updated.
Append :asc or :desc to a property to specify sort direction. The default sort direction is ascending.

auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Response  200

Successfully returned the channel members' metadata.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": [ { "uuid": { "id": "uuid-1", "name": "John Doe", "externalId": null, "profileUrl": null, "email": "john@example.com", "custom": null, "updated": "2019-02-20T23:11:20.893755", "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg==" }, "custom": { "role": "admin" }, "updated": "2019-02-20T23:11:20.893755", "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg==" }, { "uuid": { "id": "uuid-2", "name": "Bob Cat", "externalId": null, "profileUrl": null, "email": "bobc@example.com", "custom": { "phone": "999-999-9999" }, "updated": "2019-02-21T03:29:00.173452", "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg==" }, "updated": "2019-02-20T23:11:20.893755", "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg==" } ], "totalCount": 37, "next": "RDIwQUIwM0MtNUM2Ni00ODQ5LUFGRjMtNDk1MzNDQzE3MUVCCg==", "prev": "MzY5RjkzQUQtNTM0NS00QjM0LUI0M0MtNjNBQUFGODQ5MTk2Cg==" }
Response  304

The requested resource hasn't been modified since you last retrieved it.

Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Add, update or remove members in a channelPATCH/v2/objects/{sub_key}/channels/{channel}/uuids

Sets all members' metadata in the specified channel. Use the set and delete properties in the request body to perform those operations on one or more memberships.
Returns the list of channel members' metadata, optionally including:

  • the channel's custom properties
  • the custom properties for each User's membership in the channel
  • each User's custom properties

Notes:

  • You can change all of the membership object's properties, except its identifier.
  • Invalid property names are silently ignored and will not cause a request to fail.
  • If you set the custom property, you must completely replace it; partial updates aren't supported.
  • The custom object can only contain scalar values.

Example URI

PATCH https://ps.pndsn.com/v2/objects/{sub_key}/channels/{channel}/uuids
Path Parameters
sub_key

string (required) Your subscribe key. Obtain this from your Admin Portal.

channel

string (required) Example: main
Channel identifier. Must not be empty, and may contain up to 92 UTF-8 byte sequences.
Prohibited characters are ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
include

array[string] (optional)  Available values : custom, uuid, uuid.custom
List of additional/complex membership metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

limit

integer (optional)  Default value: 100
Number of objects to return in the response. Default is 100, which is also the maximum value. Set limit to 0 (zero) and count to true if you want to retrieve only a result count

start

string (optional) 
Previously-returned cursor bookmark for fetching the next page.

end

string (optional) 
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional)  Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted. To retrieve only a result count, set count to true, and set limit to 0 (zero).

filter

string (optional) 
Expression used to filter the results, Read more.

sort

array (optional) 
List of properties to sort by. Available options are id, name, and updated.
Append :asc or :desc to a property to specify sort direction. The default sort direction is ascending.

auth

string (optional) 
Authorization token with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

signature

string (optional) 
Signature used to verify that the request was signed with the secret key associated with the subscriber key.
If Access Manager is enabled, either a valid authorization token or a signature is required.
See Access Manager documentation for details on how to compute the signature.

timestamp

integer (optional) Example: 1563226304
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
Required if the signature parameter is supplied.

Request body  (required)

JSON object with changes to the channel's members list.

Headers
Content-Type: application/json
Body
{ "set": [ { "uuid": { "id": "uuid-2" }, "custom": { "role": "moderator" } } ], "delete": [ { "uuid": { "id": "uuid-0" } } ] }
Response  200

Successfully set the channel members' metadata.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": [ { "uuid": { "id": "uuid-1", "name": "John Doe", "externalId": null, "profileUrl": null, "email": "john@example.com", "custom": null, "updated": "2019-02-20T23:11:20.893755", "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg==" }, "custom": { "role": "admin" }, "updated": "2019-02-20T23:11:20.893755", "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg==" }, { "uuid": { "id": "uuid-2", "name": "Bob Cat", "externalId": null, "profileUrl": null, "email": "bobc@example.com", "custom": { "phone": "999-999-9999" }, "updated": "2019-02-21T03:29:00.173452", "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg==" }, "updated": "2019-02-20T23:11:20.893755", "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg==" } ], "totalCount": 37, "next": "RDIwQUIwM0MtNUM2Ni00ODQ5LUFGRjMtNDk1MzNDQzE3MUVCCg==", "prev": "MzY5RjkzQUQtNTM0NS00QjM0LUI0M0MtNjNBQUFGODQ5MTk2Cg==" }
Response  400

The request body contains invalid data.

Response  403

Disabled - The subscriber key doesn't have Metadata API enabled.
Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Response  415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Response  429

Request rate limit exceeded.

Response  500

An internal server error occurred.

Response  503

Request processing exceeded the maximum allowed time.

Error responses

  • Response 304

    The requested resource hasn't been modified since you last retrieved it.

  • Response 400

    The request body contains invalid data.

    Headers
    Content-Type: application/json
    Body
    { "status": 400, "error": { "message": "Request payload contained invalid input.", "source": "metadata", "details": [ { "message": "The email must be a valid email address.", "location": "uuid.email", "locationType": "body" } ] } }
  • Response 403

    Disabled - The subscriber key doesn't have Metadata API enabled.
    Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

    Headers
    Content-Type: application/json
    Body
    //Forbidden { "status": 403, "error": { "message": "Invalid signature", "source": "authz", "details": [ { "message": "Client and server produced different signatures for the same inputs.", "location": "signature", "locationType": "query" } ] } } //Disabled { "status": 403, "error": { "message": "Metadata not enabled for this subscriber key.", "source": "metadata" } }
  • Response 404

    The requested resource wasn't found.

    Headers
    Content-Type: application/json
    Body
    { "status": 404, "error": { "message": "Requested resource was not found.", "source": "metadata" } }
  • Response 412

    The conditional operation can't be performed because the target resource has changed since the last retrieval.

    Headers
    Content-Type: application/json
    Body
    { "status": 412, "error": { "message": "Resource already changed by another request since last retrieval.", "source": "metadata" } }
  • Response 415

    The format of the request body you supplied isn't supported. The request body must be in JSON format.

    Headers
    Content-Type: application/json
    Body
    { "status": 415, "error": { "message": "Request payload must be in JSON format.", "source": "metadata" } }
  • Response 429

    Request rate limit exceeded.

    Headers
    Content-Type: application/json
    Body
    { "status": 429, "error": { "message": "You have exceeded the maximum number of requests per second allowed for your subscriber key.", "source": "metadata" } }
  • Response 500

    An internal server error occurred.

    Headers
    Content-Type: application/json
    Body
    { "status": 500, "error": { "message": "An unexpected error occurred while processing the request.", "source": "metadata" } }
  • Response 503

    Request processing exceeded the maximum allowed time.

    Headers
    Content-Type: application/json
    Body
    { "status": 503, "error": { "message": "The server took longer to respond than the maximum allowed processing time.", "source": "metadata" } }

The filtering language for Objects is similar to the stream filtering language.

Note the following:

  • Date/time properties, such as updated, must be compared to valid date/time strings formatted according to ISO 8601.
  • Custom properties must have the same type as the value used in the expression; it is an error to compare a custom property of one type to a value of another type.
  • Objects that do not have the referenced custom property at all are excluded regardless of the operator or value used in the expression. The null value can be used to filter out objects that do or do not have the referenced custom property.
  • The LIKE operator supports wildcards denoted by the * character. A wildcard matches any sequence of arbitrary Unicode characters, including the empty sequence. The literal asterisk is matched when escaped using the backslash (\) character.
  • Values used with LIKE must be properly encoded just like any other string value. Thus, in order to escape an asterisk, the raw value must contain \\*.
  • The entire expression must be properly URL-encoded when used in the query string.
<expression>           ::= <and_expression> ( "||" <and_expression> )*
<and_expression> ::= <binary_condition> ( "&&" <binary_condition> )*
<binary_condition> ::= "!" <binary_condition> | "(" <expression> ")" | <relational_condition>
<relational_condition> ::= <property_path> <relational_operator> <value>
<property_path> ::= <property_name> ( "." <property_name> )*
<property_name> ::= <identifier> | "[" <string> "]"
<value> ::= <string> | <number> | "true" | "false" | "null"

Tokens

<identifier> ::= <letter> | "$" | "_" ( <letter> | "$" | "_" | <digit> )*
<relational_operator> ::= "==" | "!=" | "<=" | ">=" | "<" | ">" | "LIKE"
<string> ::= <double_quote> ( "\" <double_quote> | "\" <special_char>
| "\" "u" <hex_digit> <hex_digit> <hex_digit> <hex_digit>
| <unicode_char> - <double_quote> - "\" )* <double_quote>
show all 26 lines

The following simple expression returns results whose custom property named public is equal to Boolean true.

custom.public == true

The following date/time comparison returns results that were modified on or after August 31st, 2019 (UTC):

updated >= "2019-08-31T00:00:00Z"

The following compound expression returns results that don't have a description, but do have a non-empty custom label or description property:

description == null && (custom.label != "" || custom.description != "")

The following wildcard expression returns results whose name starts with the letter X:

name LIKE 'X*'

The following escaped wildcard expression returns results whose name contains an asterisk:

name LIKE '*\\**'

Message Actions

 

APIs for sending and receiving actions on messages sent via PubNub. These actions can represent receipts, reactions or custom actions for messages.

Fetch a list of actions, ordered by action timetokenGET/v1/message-actions/{sub_key}/channel/{channel}

Pagination can be controlled using start, end and limit parameters, where start > end. If start is not provided, the server uses the current time. Providing no end or limit means there is "no limit" to the number of actions being requested. In this event the server will try and retrieve all actions for the channel, going back in time forever. In some cases, due to internal limitations on the number of queries performed per request, the server will not be able to give the full range of actions requested. In these cases a "more" link will be provided. This is a signal that internal limiting has occurred, and the more link itself can be used to continue fetching the originally requested range of actions.

Example URI

GET https://ps.pndsn.com/v1/message-actions/{sub_key}/channel/{channel}
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

channel

string (required) Example: demo-animal-forest
The channel name.

Query Parameters
start

string (optional)  Example: 15610547826970040
Action timetoken denoting the start of the range requested (return values will be less than start)

end

string (optional)  Example: 15610547826970040
Action timetoken denoting the end of the range requested (return values will be greater than or equal to end)

limit

integer (optional) Example: 500
Number of actions to return in response.

auth

string (optional) 
Authorization key with permissions to perform the request (if configured)

Response  200

The actions were fetched.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": [ { "type": "reaction", "value": "smiley_face", "actionTimetoken": "15610547826970050", "messageTimetoken": "15610547826969050", "uuid": "terryterry69420" } ], "more": { "url": "/v1/actions/sub-c-6ba5f838-6456-11e8-9307-eaaa55e2558c/channel/test_channel_1567187121_2_6_6?start=15610547826970050&end=15645905639093361&limit=2", "start": "15610547826970050", "end": "15645905639093361", "limit": 2 } }
Response  400

The subscribe key is invalid.

Headers
Content-Type: application/json
Body
{ "status": 400, "error": { "source": "actions", "message": "Invalid Subkey" } }
Response  403

The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Headers
Content-Type: application/json
Body
{ "status": 403, "error": { "source": "actions", "message": "Supplied authorization key does not have the permissions required to perform this operation." } }

Add a Message ActionPOST/v1/message-actions/{sub_key}/channel/{channel}/message/{message_timetoken}

Allows users to post actions on a "parent message" by specifying the subkey, channel, and timetoken of the parent message.

The server does not validate that the parent message exists at the time the action is posted. The server does, however, check that you have not already added this particular action to this message. In other words, for a given parent message (identified by subkey, channel, timetoken), there is at most one unique (type, value) pair per uuid.

Finally, there is a limit to the total number of actions which can be posted on a given message (default 25000). If all goes well, the message action will be stored in the database, and a specially structured "action add event" message will be published in real time on the same channel as the parent message. (See Subscribe for details)

Example URI

POST https://ps.pndsn.com/v1/message-actions/{sub_key}/channel/{channel}/message/{message_timetoken}
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

channel

string (required) Example: demo-animal-forest
The channel name.

message_timetoken

string (required) Example: 15610547826970040
The publish timetoken of a parent message.

Query Parameters
auth

string (optional) 
Authorization key with permissions to perform the request (if configured)

uuid

string (required)
The UUID associated with the action -- max 150 characters

Request  required
Headers
Content-Type: application/json
Body
{ "type": "reaction", "value": "smiley_face" }
Response  200

The message action was successfully added.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": { "type": "reaction", "value": "smiley_face", "actionTimetoken": "15610547826970050", "messageTimetoken": "15610547826969050", "uuid": "terryterry69420" } }
Response  207

The message action was stored but failed to publish.

Headers
Content-Type: application/json
Body
{ "status": 207, "data": { "type": "reaction", "value": "smiley_face", "uuid": "user-456", "actionTimetoken": 15610547826970050, "messageTimetoken": 15610547826969050 }, "error": { "message": "Stored but failed to publish message action.", "source": "actions" } }
Response  400

The post request contained invalid parameters.

Headers
Content-Type: application/json
Body
{ "status": 400, "error": { "source": "actions", "message": "Request payload contained invalid input.", "details": [ { "message": "Missing field", "location": "value", "locationType": "body" } ] } }
Response  403

The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Headers
Content-Type: application/json
Body
{ "status": 403, "error": { "source": "actions", "message": "Supplied authorization key does not have the permissions required to perform this operation." } }
Response  409

The action was already added

Headers
Content-Type: application/json
Body
{ "status": 409, "error": { "source": "actions", "message": "Action Already Added" } }

Remove actions from a given messageDELETE/v1/message-actions/{sub_key}/channel/{channel}/message/{message_timetoken}/action/{action_timetoken}

Allows users to remove their previously-posted message actions, by specifying the parent message, and the single timetoken of the action(s) they wish to delete. It is technically possible to delete more than one action here, if the same UUID posted different actions on the same parent message at the same time. If all goes well, the action(s) will be deleted from the database, and one or more "action remove event" messages will be published in real time on the same channel as the parent message. (See subscribe for details)

Example URI

DELETE https://ps.pndsn.com/v1/message-actions/{sub_key}/channel/{channel}/message/{message_timetoken}/action/{action_timetoken}
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

channel

string (required) Example: demo-animal-forest
The channel name.

message_timetoken

string (required) Example: 15610547826970040
The publish timetoken of a parent message.

action_timetoken

string (required) Example: 15610547826970040
The publish timetoken of the action.

Query Parameters
auth

string (optional) 
Authorization key with permissions to perform the request (if configured)

uuid

string (optional) 
The UUID associated with the action -- max 150 characters

Response  200

The action was removed.

Headers
Content-Type: application/json
Body
{ "status": 200, "data": {} }
Response  207

The action was deleted but the action-deletion message was not published.

Headers
Content-Type: application/json
Body
{ "status": 207, "error": { "source": "actions", "message": "Deleted but failed to publish removed events." } }
Response  400

Wrong uuid specified for the given message action.

Headers
Content-Type: application/json
Body
{ "status": 400, "error": { "source": "actions", "message": "Not deleting message action: wrong uuid specified" } }
Response  403

The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Headers
Content-Type: application/json
Body
{ "status": 403, "error": { "source": "actions", "message": "Supplied authorization key does not have the permissions required to perform this operation." } }

Miscellaneous

Time

Get current PubNub Time in the form of a Timetoken.

About Timetokens

The timetoken represents a 17-digit precision unix time (UTC). To convert PubNub's timetoken to Unix timestamp (seconds), divide the timetoken number by 10,000,000 (10^7).

To convert back and forth between current time, A Ruby example follows as:

> now = Time.now => 2012-11-02 14:27:11 -0700 > timetoken = now.to_f * 10000000 => 13518916319742640 > Time.at(timetoken / 10000000) => 2012-11-02 14:27:11 -0700

Fetch TimeGET/time/{callback}{?uuid}

Example URI

GET https://ps.pndsn.com/time/0?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
Path Parameters
callback
string (required) Example: 0

pass function name to wrap in JSONP or 0 to disable JSONP

Query Parameters
uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  fetch time without JSONP
Headers
Location: /time/0
Response  200
Headers
Content-Type: application/json
Body
[16068755276514766]
Request  fetch time with JSONP
Headers
Location: /time/moose
Response  200
Headers
Content-Type: text/javascript
Body
moose([14374273908474349])
Last updated on
On this page