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 Presence and PubNub Analytics.
auth – optional - An Access Manager authentication key (v2) or token (v3), to be used on Access Manager-enabled endpoints:
- Publishing
- Subscribing
- Message Persistence
- 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 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 Presence and PubNub Analytics.

ttl

integer (optional) Example: 1

Set a per-message time to live in storage.

If store = 1, and ttl = 0, the message is stored with no expiry time.
If store = 1 and ttl = X (X is an Integer value), the message is stored with an expiry time of X hours.
If store = 0, the ttl parameter is ignored.
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 Presence and PubNub Analytics.

ttl

integer (optional) Example: 1

Set a per-message time to live in storage.

If store = 1, and ttl = 0, the message is stored with no expiry time.
If store = 1, and ttl = X (X is an Integer value), the message is stored with an expiry time of X hours.
If store = 0, the ttl parameter is ignored.
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 Presence and 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 Presence and 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 Subscribe V2 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 Presence and PubNub Analytics.

Subscribe v2 - Subscribe Process #

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

In the first call, set the tt parameter to 0. The server responds with the t (timetoken) and r (region) parameters.
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.

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." }

File Sharing #

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.

Retrieving a file 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

Name	Description	Type
Location	The URL to which you're redirected for download	string Example: https://s3.presigned.url.com
Cache-Control	Time, in seconds, the response will be cached	string Example: public, max-age=3300, immutable

Response 400

One or more request parameters are invalid.

Response 402

The File Sharing 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 File Sharing 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 File Sharing 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 File Sharing 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 } }

Message Persistence #

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 Message Persistence, 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 Presence and 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 File Sharing 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 10,000.

If there are more than 10,000 message counts for all requested channels, the response is paginated and contains the more parameter.

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 HistoryResponseV3

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). HistoryResponseV3

{ "status": 200, "error": false, "error_message": "", "channels": { "peach1": 2 }, "more": { "peach1": { "url": "/v3/history/sub-key/sub-c-d5fjghj08-b124-11ec-9ce0-a2ghjgj8c6ce19d/message-counts/peach1?timetoken=16588767063367817", "is_more": false } }

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. HistoryResponseV3

Response 403

Storage is not enabled for this subscribe key. HistoryResponseV3

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.
more: Object (optional)
If the number of requested message counts for all channels exceeds 10,000, a dictionary of channel objects is added. Each channel has the url and is_more properties.
url: String (optional)
The URL used to get the results that weren't returned in the previous call.
is_more: Boolean (optional)
A flag indicating if there is any more data to be fetched.

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 Presence and 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 Presence and 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 Presence and 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 Presence and 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 Presence and 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#

PAM v2 #

PAM 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 #

Access Manager 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 Manager

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, 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

Operation	Resource	Permission
Publish	channel	`write`
Signal	channel	`write`
Fire	channel	`write`
Subscribe	channel	`read`

Channel groups

Operation	Resource	Permission
Add channels	channel group	`manage`
Remove channels	channel group	`manage`
List channels	channel group	`read`
Delete a channel group	channel group	`manage`
Subscribe to a channel group	channel group	`read`
Set state on a channel group	channel group	`read`

Presence

Operation	Resource	Permission
Here now	channel	`manage`
Where now	none	none
Set state	channel	`read`
Get state	channel	`read`
Subscribe to presence	channel-pnpres	`read`

Mobile Push Notifications

Operation	Resource	Permission
Add a device to channels	channel	`read`
Remove a device from channels	channel	`read`
List devices in a channel	channel	`read`

Message Persistence

Operation	Resource	Permission
History	channel	`manage`
Fetch history	channel	none
Get message counts	channel	`read`
Delete messages	channel	`delete`

Message Reactions

Operation	Resource	Permission
Add a message action	channel	`write`
Remove a message action	channel	`delete`
Get message actions	channel	`read`
Get history with actions	channel	`read`

App Context

Operation	Resource	Permission
Get channel metadata (including its members)	channel	`get`
Set channel metadata	channel	`update`
Remove channel metadata	channel	`delete`
Set/remove channel member metadata	channel	`manage`
Set/remove uuid membership metadata for a channel	channel	`join`
Get uuid metadata (including its membership)	uuid	`get`
Set uuid metadata and/or set/remove its channel membership metadata	uuid	`update`
Remove uuid metadata	uuid	`delete`

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 Presence and 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 Access ManagerPOST`/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.

Parameter	Type	Description
`ttl`	Int	The 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.channels`	Object	A mapping of channel names to permissions. Read more in Permission Bits.
`permissions.resources.groups`	Object	A mapping of channel group names to permissions. Read more in Permission Bits.
`permissions.resources.users`	Object	A mapping of users to permissions. This resource is used only for Objects v1 operations. Read more in Permission Bits.
`permissions.resources.spaces`	Object	A mapping of spaces to permissions. This resource is used only for Objects v1 operations. Read more in Permission Bits.
`permissions.resources.uuids`	Object	A mapping of uuids to permissions. This resource is used only for App Context operations. Read more in Permission Bits.
`permissions.patterns.channels`	Object	A mapping of regular expressions to permissions for channel names that match the pattern. Read more in Patterns.
`permissions.patterns.groups`	Object	A mapping of regular expressions to permissions for channel group names that match the pattern. Read more in Patterns.
`permissions.patterns.users`	Object	A mapping of regular expressions to permissions for Objects v1 users that match the pattern. Read more in Patterns.
`permissions.patterns.spaces`	Object	A mapping of regular expressions to permissions for Objects v1 spaces that match the pattern. Read more in Patterns.
`permissions.patterns.uuids`	Object	A mapping of regular expressions to permissions for App Context uuids that match the pattern. Read more in Patterns.
`permissions.meta`	Object	The 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.uuid`	String	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 App Context 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.

Name	Value (Binary)	Value (Hex)	Value (Dec)	Description
`READ`	`0b0000_0001`	`0x01`	1	Applies to Subscribe, Message Persistence, Presence
`WRITE`	`0b0000_0010`	`0x02`	2	Applies to Publish
`MANAGE`	`0b0000_0100`	`0x04`	4	Applies to Channel-Groups, App Context
`DELETE`	`0b0000_1000`	`0x08`	8	Applies to Message Persistence, App Context
`CREATE`	`0b0001_0000`	`0x10`	16	Applies to Objects v1
`GET`	`0b0010_0000`	`0x20`	32	Applies to App Context
`UPDATE`	`0b0100_0000`	`0x40`	64	Applies to App Context
`JOIN`	`0b1000_0000`	`0x80`	128	Applies to App Context

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 Access ManagerDELETE`/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 code	Description
`200`	Successful 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.
`503`	Server 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.

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 key. Query parameters must be unique (in other words, you may not use &uuid=pubnub-sample&uuid=pubnub-other-sample).
All characters in a query parameter must be percent-encoded, except for the following characters: alphanumeric, hyphen, underscore, period, and tilde. This corresponds to the following regular expression:
/[^0-9a-zA-Z\-_\.~]/
Space characters must be replaced by %20 (NOT + character).
Each key-value pair must be separated by ampersand characters.
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
The request body must be appended to the message verbatim (byte-for-byte as provided in the request).
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

The streaming, real-time, subscribe-based presence calls, generally implemented as presence()
The ad-hoc, on-demand presence calls, such as here_now() and where_now(), get_state(), set_state(), and leave()
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 Presence 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" }

Mobile Push Notifications || APNs & GCM #

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

NOTE: The PubNub's Mobile Push Notifications 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

apple push notification service

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" } } }

google push notification service

{ "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:

channels passed in the remove will be removed from the registrations list for the device
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"]

App Context #

The Objects V1 API has been deprecated

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

The App Context 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 App Context 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

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

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

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

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

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

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

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

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

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

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

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

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" } }

App Context Filtering Language Definition #

The filtering language for App Context 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

Sample object filtering operations #

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 Reactions #

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 ReactionPOST`/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])

PubNub REST API Documentation

Common REST Query String Parameters#

Common HTTP Request Headers#

Common HTTP Status Codes#

Publish / Subscribe #

Publish V1 via GET

Publish v1 - Valid / Success Responses #

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

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

Publish v1 - Invalid / Error Responses #

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

Example URI

Headers

Headers

Body

Headers

Headers

Body

Publish V1 via POST #

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

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Fire #

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

Example URI

Signals #

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

Example URI

Headers

Body

Receiving a signal message

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Subscribe #

Subscribe v1 - Valid / Success Responses #

Subscribe v1 - Invalid / Error Responses #

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

Example URI

Subscribe v2 - Subscribe Process #

Subscribe v2 - Valid / Success Responses #

Subscribe v2 - Invalid / Error Responses #

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

Example URI

Headers

Body (For normal messages)

Body (For messages of type Signal)

Body (For messages of type Objects)

Body (For messages of type Message Actions)

Body (For messages of type Files)

Headers

Body

Headers

Body

Headers

Body

Headers

Body

File Sharing #

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

Example URI

Headers

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

Example URI

Headers

Body

Common REST Query String Parameters

Common HTTP Request Headers

Common HTTP Status Codes

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

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

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

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

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

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

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

Body (For messages of type `Signal`)

Body (For messages of type `Objects`)

Body (For messages of type `Message Actions`)

Body (For messages of type `Files`)

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

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

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

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

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

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

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

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

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

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

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

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

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