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 V1 via GET
Publish a message to a channel.
Publish v1 - Valid / Success Responses #
Successful (HTTP Status 200) Publish() calls will always return a three-element array: #
Array Element 0 - Integer – 1 or 0, where 1 is success, and 0 is error.
Array Element 1 - String – Description of the success or error, if available.
Array Element 2 - String – The current PubNub time expressed as a Timetoken, on success only.
A sample response from server [1,"Sent","14375189629170609"]
contains the following fields: #
The first element is an integer of value 1 representing success.
The second element is a string description of the success, which for 200 response codes will always be "Sent".
The third element is the string Timetoken value the system accepted the Publish() operation at.
Publish v1 - Invalid / Error Responses #
In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned. If you do, and it has a second element, and that element is a string, you may parse it for a description of the error.
Errors specific to Publish() will occur when URL (e.g., message payload) is too large (>=32K), and invalid publish and/or subscribe keys are used.
Publish JSON to channel via GETGET/publish/{pub_key}/{sub_key}/0/{channel}/{callback}/{payload}{?store,uuid}
Example URI
- pub_key
string
(required) Example: myPubKeythe publish key to use
- sub_key
string
(required) Example: mySubKeythe subscriber key
- channel
string
(required) Example: ch1the destination of the message
- callback
string
(required) Example: myCallbackresponse will be wrapped in JSONP function,
0
for no JSONP- payload
string
(required) Example: %7B%22text%22%3A%22hey%22%7Durl-encoded JSON
- store
number
(optional) Example: 0this 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-125765b6f561A unique alphanumeric ID for identifying the client to Presence and PubNub Analytics.
- ttl
integer
(optional) Example: 1Set a per-message time to live in storage.
- If
store
=1
, andttl
=0
, the message is stored with no expiry time. - If
store
=1
andttl
=X
(X
is an Integer value), the message is stored with an expiry time ofX
hours. - If
store
=0
, thettl
parameter is ignored. - If
ttl
is not specified, then expiration of the message defaults back to the expiry value for the key.
- If
without JSON
Headers
Location: /publish/myPubKey/mySubKey/0/ch1/0/%7B%22text%22%3A%22hey%22%7D
200
Headers
Content-Type: application/json
Body
[1,"Sent","14375220012064619"]
with JSONP
Headers
Location: /publish/myPubKey/mySubKey/0/ch1/myCallback/%7B%22text%22%3A%22hey%22%7D
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
- pub_key
string
(required) Example: myPubKeythe publish key to use
- sub_key
string
(required) Example: mySubKeythe subscriber key
- channel
string
(required) Example: ch1the destination of the message
- callback
string
(required) Example: myCallbackresponse will be wrapped in JSONP function,
0
for no JSONP
- store
number
(optional) Example: 0this 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-125765b6f561A unique alphanumeric ID for identifying the client to Presence and PubNub Analytics.
- ttl
integer
(optional) Example: 1Set a per-message time to live in storage.
- If
store
=1
, andttl
=0
, the message is stored with no expiry time. - If
store
=1
, andttl
=X
(X
is an Integer value), the message is stored with an expiry time ofX
hours. - If
store
=0
, thettl
parameter is ignored. - If
ttl
is not specified, then expiration of the message defaults back to the expiry value for the key.
- If
without JSONP
Headers
Content-Type: application/json Location: /publish/myPubKey/mySubKey/0/ch1/0
Body
{ "message": "All your base are belong to us." }
200
Headers
Content-Type: application/json
Body
[ 1, "Sent", "14375220012064619" ]
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." }
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
- pub_key
string
(required) Example: myPubKeyThe publish key to use.
- sub_key
string
(required) Example: mySubKeyThe subscriber key.
- channel
string
(required) Example: ch1The destination of the message.
- callback
string
(required) Example: myCallbackResponse will be wrapped in JSONP function, 0 for no JSONP.
- store
number
(required, should be0
for Fire)- norep
boolean
(required, should betrue
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-125765b6f561A unique alphanumeric ID for identifying the client to Presence and PubNub Analytics.
without JSONP
200
with JSONP
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
- 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, or0
if no callback.- payload
string
(required)
The message body to signal. This can be unstructured text or JSON, for example.
- 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.
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" } ] }
400
There was an error with the request
Headers
Content-Type: text/javascript
Body
{ "message": "Invalid Subscribe Key", "error": true, "status": 400 }
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 }
404
Requested object was not found.
Headers
Content-Type: text/javascript
Body
[]
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" }
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
- sub_key
string
(required) Example: mySubKeyYour PubNub Subscribe API Key
- channel
string
(required) Example: ch1The 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: myFunctionJSONP callback name, or 0 if none.
- timetoken
string
(required) Example: 12313123131230 (zero) for the initial subscribe, or a valid timetoken if resuming / continuing / fast-forwarding from a previous subscribe flow.
- channel-group
string
(optional) Example: cg1,cg2,cg3Channel 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%7DWhen 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: 412If 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-125765b6f561A 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 to0
. The server responds with thet
(timetoken) andr
(region) parameters. - In subsequent calls, set the
tt
parameter to the value of thet
parameter and thetr
parameter to the value of ther
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 forObjects
messages, 3 is forMessageAction
messages, 4 is forFiles
messages) - f - Int - Flags
- i - String - Issuing Client Id
- k - String - Subscribe Key
- o - Object - Originating Timetoken, containing: t - String - the timetoken and r - Int - the region.
- p - Object - Publish Timetoken Metadata containing: t - String - the timetoken and r - Int - the region.
- u - Object - User Metadata
If you are subscribed to a channel group named myCG, and you receive a message on myCG from a member channel named myCH, b will contain "myCG", and c will contain "myCH".
The value of e
denotes the type of messages. If e
is 1
the message is of type Signal
and if e
is 2
the message is of type Objects
. A value of 0
or no e
field means the message is a regular message. (See Body for more details.)
Each time a message action is added or removed, a specially-structured action event message will be published on the same channel as the parent message. These action event messages will come through the same subscribe event loop as the user's regular messages, but the envelope of the message will show an "e" field of 3
. The data of the action event message will show whether the action was added or removed, and the data of the message action in question. The UUID
that caused this event will also be returned in the envelope of the message, in the "i" field.
When subscribing to both channels and channel groups, the corresponding entry for an non-CG member channel will be identical to that of the entry for it element 2.
Subscribe v2 - Invalid / Error Responses #
In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned.
Common HTTP Status Codes should be expected. In the event of a non-Common HTTP Status Code and/or unparseable JSON, assume an error, fire your error callback with as much information as possible, wait 1 second, and retry the failed request indefinitely.
It is critical to design your subscribe logic to be durable and always retry. Although it should try indefinately, since its calling the error callback on each failure, the developer will be able to unsubscribe from the channel(s) if needed.
SubscribeGET/v2/subscribe/{sub_key}/{channel}/{callback}{?uuid,tt,tr,state,filter-expr}
This resource allows a developer to Subscribe to PubNub.
Example URI
- sub_key
string
(required) Example: mySubKeyYour PubNub Subscribe API Key
- channel
string
(required) Example: ch1The 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: myFunctionJSON callback name, or 0 if none.
- tt
string
(required) Example: 12313123131230 (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,cg3Channel 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%7DWhen 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: 412If 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-125765b6f561A 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%27Set filter expression for Subscribe message filtering.
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" } ] }
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 }
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 }
414
Request size exceeds 32KiB.
Headers
Content-Type: text/javascript
Body
{ "status": 414, "service": "Balancer", "error": true, "message": "Request URI Too Long" }
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
- sub_key
string
(required) example: demoSubscribe key
- channel
string
(required) example: my_channelChannel
on which to perform the file operation- id
string
(required) example: 5a3eb38c-483a-4b25-ac01-c4e20deba6d6PubNub generated ID for the uploaded file.
- name
string
(required) example: cat_picture.jpgUser-supplied filename
- 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
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 |
400
One or more request parameters are invalid.
402
The File Sharing service is not enabled for the subkey.
500
Internal Server Error.
List FilesGET/v1/files/{sub_key}/channels/{channel}/files
List files uploaded to the channel.
Example URI
- sub_key
string
(required) example: demoSubscribe key
- channel
string
(required) example: my_channelChannel
on which to perform the file operation
- limit
integer
(optional) Default value: 100
Number of objects to return in the response. Default is 100, which is also the maximum value. Setlimit
to 0 (zero) andcount
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
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 }
400
One or more request parameters are invalid.
402
The File Sharing service is not enabled for the subkey.
500
Internal Server Error.
Delete FileDELETE/v1/files/{sub_key}/channels/{channel}/files/{id}/{name}
Delete a file.
Example URI
- sub_key
string
(required) example: demoSubscribe key
- channel
string
(required) example: my_channelChannel
on which to perform the file operation- id
string
(required) example: 5a3eb38c-483a-4b25-ac01-c4e20deba6d6PubNub generated
id
for the uploaded file.- name
string
(required) example: cat_picture.jpgUser-supplied filename
- 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
200
The operation was successful.
Headers
Content-Type: application/json
Body
{ "status": 200 }
400
One or more request parameters are invalid.
402
The File Sharing service is not enabled for the subkey.
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
- sub_key
string
(required) Example: mySubKeythe subscriber key
- channel
string
(required) Example: ch1channel for which the history is requested
- count
number
(optional) Example: 100The 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: 12332312312312312If 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: 12332312312312312If 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: falseDirection of time traversal. Default is false, which means timeline is traversed newest to oldest.
- include_meta
boolean
(optional) Example: trueSet to
true
to include metadata with returned messages. This metadata is set using themeta
parameter with thepublish
operation. Default isfalse
.- stringtoken
boolean
(optional) Example: falseIf 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: falsepass
true
to recieve a timetoken with each history message. Defaults tofalse
- string_message_token
boolean
(optional) Example: falseThis 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-125765b6f561A unique alphanumeric ID for identifying the client to Presence and PubNub Analytics.
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
- sub_key
string
(required) Example: mySubKeythe subscriber key
- channel
string
(required) Example: ch1, ch2comma separated channels for which the history is requested
- max
number
(optional) Example: 25The 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: 12332312312312312If 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: 12332312312312312If 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: truePass
true
to receive the message type with each history message.
Defaults tofalse
- include_uuid
boolean
(optional) Example: trueSet to
true
to include uuid with returned messages. This is set using the uuid parameter with the publish operation.
Default isfalse
.- include_meta
boolean
(optional) Example: trueSet to
true
to include metadata with returned messages. This metadata is set using themeta
parameter with thepublish
operation. Default isfalse
.- 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: trueSet to
true
, the channel names in the response will be url encoded. Set tofalse
, the channel names in the response will not be url encoded. Default istrue
.
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 thetimetoken
when the post occurred. Pagination can be controlled withstart
,end
, andmax
parameters, similar to theget_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
- sub_key
string
(required) Example: mySubKey
The subscriber key.- channel
string
(required) Example: demo-animal-forest
The channel name.
- include_message_type
boolean
(optional) Example: truePass
true
to receive the message type with each history message.
Defaults tofalse
- include_uuid
boolean
(optional) Example: truePass
true
to receive the publisheruuid
with each history message.
Defaults tofalse
.- 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 themeta
parameter with thepublish
operation. Default isfalse
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 } }
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
- 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.
- 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.
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
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 } }
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
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
andis_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
- sub_key
string
(required) Example: mySubKey
The subscriber key.- channel
string
(required) Example: demo-animal-forest
The channel name.
- 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.
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": "", }
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", }
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
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.
Body
{ "error": false, "error_message": "", "channel": channel_deleted }
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 linesEncrypt Msg Using secret-key as the Encryption Key #
key = "mySubKey" //Secret-key
msg = "
{subkey}
{pubkey}
{path}
{params}"
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
- sub_key
string
(required) Example: mySubKeythe subscriber key
- uuid
string
(required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561A unique alphanumeric ID for identifying the client to Presence and PubNub Analytics.
Get all channel groups for subscribe key
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
- sub_key
string
(required) Example: mySubKeythe subscriber key
- group
string
(required) Example: group1the 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-125765b6f561A unique alphanumeric ID for identifying the client to Presence and PubNub Analytics.
Get all channels for a channel group
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
- sub_key
string
(required) Example: mySubKeyThe subscriber key
- group
string
(required) Example: group1The channel group to which the channels will be added
- add
string
(required) Example: ch1Name 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-125765b6f561A unique alphanumeric ID for identifying the client to Presence and PubNub Analytics.
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
- sub_key
string
(required) Example: mySubKeyThe subscriber key
- group
string
(required) Example: group1The channel group to which the channels will be added
- remove
string
(required) Example: ch1Name 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-125765b6f561A unique alphanumeric ID for identifying the client to Presence and PubNub Analytics.
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
- sub_key
string
(required) Example: mySubKeythe subscriber key
- group_name
string
(required) Example: group1the 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-125765b6f561A unique alphanumeric ID for identifying the client to Presence and PubNub Analytics.
Deleting a Channel Groups
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
norchannel
in the {signed-content} query-string parametersChannel Permissions
Provide only a
channel
parameter, but notauth
parameter, this then sets permissions on the channel itself overriding any auth-key permissionsAuthKey Permissions
Provide both
auth
andchannel
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
- sub_key
string
(required) Example: mySubKeyYour PubNub Subscribe API Key.
- signature
string
(required) Example: v2rgQQ1eFzk8omugFV9V1_eKRUvvMv9jyC9ZL1ogdw%3DA signed request as described in the section above.
- auth
string
(required) Example: myAuthKeyThe Auth key that is being granted permissions.
- uuid
string
(optional) Example: db9c5e39-7c95-40f5-8d71-125765b6f561A unique alphanumeric ID for identifying the client to Presence and PubNub Analytics.
- timestamp
int
(required) Example: 1234567898The 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: 15Time to live for permission to be valid
- channel
string
(optional) Example: ch1,ch2Specifies the channels on which to grant permissions. Comma separated values are accepted.
- channel-group
string
(optional) Example: group1,group2Specifies 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: 1Write permission
- r
boolean
(optional) Example: 0Read permission
- m
boolean
(optional) Example: 0Manage permission
- d
boolean
(optional) Example: 0Delete permission
- g
int
(optional) Example: 0Get permission
- u
int
(optional) Example: 0Update permission
- j
int
(optional) Example: 0Join permission
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
- sub_key
string
(required) Example: mySubKeyYour PubNub subscribe key.
- uuid
int
(optional) Example: uuid-1A unique alphanumeric ID for tracking and verifying the identity of the caller.
- timestamp
int
(required) Example: 1595573165The 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.e1H7ZHXXXNCp8X4dMx3tXFGPiIngCMF4ZtN1eKnq05IA 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
andttl
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.res
is an object that represents the mapping of resource types to resource IDs.pat
is 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-bitbigint
.
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
- sub_key
string
(required) Example: mySubKeyYour PubNub Subscribe API Key.
- token_string
string
(required) Example: p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenVzcqBDc3BjoERtZXRhoENzaWdYIGOAeTyWGJIToken string permissions assigned to you in the grant request by the PubNub server. The token must have the URL-encoded format.
- timestamp
Integer
(required) Example: 1595573165Current epoch Unix timestamp (10-digit).
- signature
String
(required) Example: v2.e1H7ZHXXXNCp8X4dMx3tXFGPiIngCMF4ZtN1eKnq05IA signed request as described in the section above.
- uuid
String
(required) Example: uuid-1The 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 |
|
403 |
|
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×tamp=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×tamp=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×tamp=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.The request body must be appended to the message verbatim (byte-for-byte, as provided in the request).
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
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×tamp=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
- 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.
- channel-group
string
(optional) Example: cg1,cg2,cg3Channel 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: myFunctionJSONP callback name, or 0 if none.
- heartbeat
number
(optional) Example: 120Used 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%7DWhen 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-125765b6f561A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.
Heartbeat
Headers
Location: /v2/presence/sub-key/demo/channel/ch1/heartbeat?uuid=PubNubUnityExample&auth=authKey
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
- sub_key
string
(required) Example: mySubKeyYour PubNub Subscribe API Key
- channel
string
(required) Example: ch1The 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-125765b6f561A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.
- channel-group
string
(optional) Example: cg1,cg2,cg3Channel 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%7Durl-encoded json which will be associated with the UUID for the channels and/or channel groups
- callback
string
(optional) Example: myFunctionIf provided, wraps the response in function (JSONP)
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
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
- sub_key
string
(required) Example: mySubKeyYour PubNub Subscribe API Key
- channel
string
(required) Example: ch1The 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-125765b6f561A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.
- channel-group
string
(optional) Example: cg1,cg2,cg3Channel 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: myFunctionIf provided, wraps the response in function (JSONP)
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
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
- sub_key
string
(required) Example: mySubKeyYour PubNub Subscribe API Key
- channel
string
(required) Example: ch1The channel name(s), separated by comma, that you wish to send leave events for. Verify that channels are comprised of valid characters.
- channel-group
string
(optional) Example: cg1,cg2,cg3The 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: myFunctionIf provided, wraps the response in function (JSONP)
- uuid
string
(required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.
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×tamp=1565094167
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×tamp=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
- sub_key
string
(required) Example: mySubKeyYour PubNub Subscribe API Key
- channel
string
(required) Example: ch1The channel name(s), separated by comma, that you wish to send leave events for. Verify that channels are comprised of valid characters.
- channel-group
string
(optional) Example: cg1,cg2,cg3The 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: myFunctionIf provided, wraps the response in function (JSONP)
- uuid
string
(required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561A 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
- 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.
- channel-group
string
(optional) Example: cg1,cg2,cg3Comma 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: 0If 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: 0If 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: myFunctionIf provided, returns a JSONP function-wrapped response.
- uuid
string
(required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.
Here Now
Headers
Location: /v2/subscribe/demo/ch,ch-pnpres/0?q1=v1&auth=akey×tamp=1565093044&heartbeat=120&tt=15650930446689601&q2=v2&uuid=pn-4152c98f-0b60-404c-9719-c42dbf8fc246
200
Headers
Location: /v2/subscribe/demo/ch,ch-pnpres/0?q1=v1&auth=akey×tamp=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
- sub_key
string
(required) Example: 'mySubKey'Your PubNub Subscribe API Key
- 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-125765b6f561A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.
- callback
string
(optional) Example: myFunctionIf provided, returns a JSONP function-wrapped response.
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×tamp=1565093804
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×tamp=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 servicegcm
- Firebase Cloud Messaging push notification service
Publishing #
Given a channel ch1
, and subscribed mobile clients, a server SDK must execute a publish commend by sending the following JSON payload to ch1
APNs HTTP/2 Example:
{ "pn_apns": { "aps": { "alert": "hello world" }, "pn_push": [ { "targets": [ { "environment": "production", "topic": "BUNDLE_ID_FOR_APP_1" } ], "version": "v2" } ] } }
Non-APNs HTTP/2 Example:
{ "pn_apns": { "aps": { "alert": "hi", "badge": 2, "sound": "melody" }, "pn_other": { "additional": "fields" } } }
{ "pn_gcm": { }, "pn_other": { "additional": "fields" } }
Please refer to the tutorial for additional examples
NOTE: The next set of Push-related resources are to be used for APNs HTTP/2 implementations.
Managing device registrations (APNs HTTP/2) #
Add, or Remove a device from a channelGET/v2/push/sub-key/{sub_key}/devices-apns2/{devices-apns2}?{uuid,auth,add,remove,environment,topic}
Add and remove channels in a single API call. If the "add" or "remove" query parameters are absent, a list of channels that meet the provided criteria is returned.
Example URI
- sub_key
string
(required) Example: mySubKeythe subscriber key
- devices-apns2
string
(required) Example: A332C23Dthe id/token of the device
- uuid
string
(optional) Example: db9c5e39-7c95-40f5-8d71-125765b6f561UUID of the client
- auth
string
(optional) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3Access 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)
- indicates list of channels to which the device should be added, for push registration (multiple channels are also supported by comma delimited (
- remove
string
(optional) Example: channel1name 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.Applicationbundle 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
- sub_key
string
(required) Example: mySubKeythe subscriber key
- devices-apns2
string
(required) Example: A332C23Dthe id/token of the device
- uuid
string
(required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561UUID of the client
- auth
string
(required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3Access 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)
- indicates list of channels to which the device should be added, for push registration (multiple channels are also supported by comma delimited (
- remove
string
(required) Example: channel1name 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.Applicationbundle 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
- sub_key
string
(required) Example: mySubKeythe subscriber key
- push_token
string
(required) Example: A332C23Dthe push token of the device
- type
string
(required)- indicates the back end to use (
apns
for apple,gcm
for google)
- indicates the back end to use (
- uuid
string
(required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.
show all channels for device for apple services
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?type=apns
200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
show all channels for device for google services
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?type=gcm
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
- sub_key
string
(required) Example: mySubKeythe subscriber key
- push_token
string
(required) Example: A332C23Dthe push token of the device
- type
string
(required)- indicates the back end to use (
apns
for apple,gcm
for google)
- indicates the back end to use (
- uuid
string
(optional) Example: db9c5e39-7c95-40f5-8d71-125765b6f561A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.
Removing an Apple device from all push notifications
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D/remove?type=apns
200
Headers
Content-Type: application/json
Removing an Android device from all push notifications
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D/remove?type=gcm
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
- sub_key
string
(required) Example: mySubKeythe subscriber key
- push_token
string
(required) Example: A332C23Dthe push token of the device
- uuid
string
(required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561UUID of the client
- auth
string
(required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3Access 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)
- indicates the back end to use (
- add
string
(required) Example: channel1name 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)
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
200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
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
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
- sub_key
string
(required) Example: mySubKeythe subscriber key
- push_token
string
(required) Example: A332C23Dthe push token of the device
- uuid
string
(required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561UUID of the client
- auth
string
(required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3Access 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)
- indicates the back end to use (
- remove
string
(required) Example: channel1name 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)
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
200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
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
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 devicechannels passed in the
add
will be added to the registrations list for the device
Example URI
- sub_key
string
(required) Example: mySubKeythe subscriber key
- push_token
string
(required) Example: A332C23Dthe push token of the device
- uuid
string
(required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561UUID of the client
- auth
string
(required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3Access 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)
- indicates the back end to use (
- add
string
(required) Example: channel1comma 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: channel1commad 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
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
200
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
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
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
- sub_key
string
(required) Your subscribe key. Obtain this from your Admin Portal.
- 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. Setlimit
to 0 (zero) andcount
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, setcount
to true, and setlimit
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 areid
,name
, andupdated
.
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 thesignature
parameter is supplied.
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==" } ] }
304
The requested resource hasn't been modified since you last retrieved it.
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.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- 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.
- 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 thesignature
parameter is supplied.
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==" } }
304
The requested resource hasn't been modified since you last retrieved it.
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.
404
The requested resource wasn't found.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- 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.
- 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 thesignature
parameter is supplied.
JSON object with User metadata to set.
Headers
Content-Type: application/json
Body
{ "name": "John Doe", "externalId": null, "profileUrl": null, "email": "john@example.com" }
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==" } }
400
The request body contains invalid data.
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.
412
The conditional operation can't be performed because the target resource has changed since the last retrieval.
415
The format of the request body you supplied isn't supported. The request body must be in JSON format.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- 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.
- 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 thesignature
parameter is supplied.
200
Successfully deleted User metadata.
Headers
Content-Type: application/json
Body
{ "status": 0, "data": {} }
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.
412
The conditional operation can't be performed because the target resource has changed since the last retrieval.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- sub_key
string
(required) Your subscribe key. Obtain this from your Admin Portal.
- 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. Setlimit
to 0 (zero) andcount
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, setcount
to true, and setlimit
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 areid
,name
, andupdated
.
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 thesignature
parameter is supplied.
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==" }
304
The requested resource hasn't been modified since you last retrieved it.
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.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- 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.
- 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 thesignature
parameter is supplied.
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==" } }
304
The requested resource hasn't been modified since you last retrieved it.
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.
404
The requested resource wasn't found.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- 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.
- 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 thesignature
parameter is supplied.
JSON object with channel metadata to set.
Headers
Content-Type: application/json
Body
{ "name": "My channel", "description": "A channel that is mine" }
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==" } }
400
The request body contains invalid data.
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.
412
The conditional operation can't be performed because the target resource has changed since the last retrieval.
415
The format of the request body you supplied isn't supported. The request body must be in JSON format.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- 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.
- 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 thesignature
parameter is supplied.
200
Successfully deleted channel metadata.
Headers
Content-Type: application/json
Body
{ "status": 0, "data": {} }
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.
412
The conditional operation can't be performed because the target resource has changed since the last retrieval.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- 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.
- 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. Setlimit
to 0 (zero) andcount
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, setcount
to true, and setlimit
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 areupdated
channel.id
,channel.name
, andchannel.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 thesignature
parameter is supplied.
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==" }
304
The requested resource hasn't been modified since you last retrieved it.
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.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- 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.
- 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. Setlimit
to 0 (zero) andcount
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, setcount
to true, and setlimit
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 areid
,name
, andupdated
.
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 thesignature
parameter is supplied.
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" } } ] }
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==" }
400
The request body contains invalid data.
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.
415
The format of the request body you supplied isn't supported. The request body must be in JSON format.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- 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.
- 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. Setlimit
to 0 (zero) andcount
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, setcount
to true, and setlimit
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 areupdated
uuid.id
,uuid.name
, anduuid.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 thesignature
parameter is supplied.
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==" }
304
The requested resource hasn't been modified since you last retrieved it.
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.
429
Request rate limit exceeded.
500
An internal server error occurred.
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
- 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.
- 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. Setlimit
to 0 (zero) andcount
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, setcount
to true, and setlimit
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 areid
,name
, andupdated
.
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 thesignature
parameter is supplied.
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" } } ] }
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==" }
400
The request body contains invalid data.
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.
415
The format of the request body you supplied isn't supported. The request body must be in JSON format.
429
Request rate limit exceeded.
500
An internal server error occurred.
503
Request processing exceeded the maximum allowed time.
Error responses #
- Response
304
The requested resource hasn't been modified since you last retrieved it.
- Response
400
The request body contains invalid data.
Headers
Content-Type: application/json
Body
{ "status": 400, "error": { "message": "Request payload contained invalid input.", "source": "metadata", "details": [ { "message": "The email must be a valid email address.", "location": "uuid.email", "locationType": "body" } ] } }
- Response
403
Disabled - The subscriber key doesn't have 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.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 linesSample 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
- sub_key
string
(required) Example: mySubKey
The subscriber key.- channel
string
(required) Example: demo-animal-forest
The channel name.
- 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)
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 } }
400
The subscribe key is invalid.
Headers
Content-Type: application/json
Body
{ "status": 400, "error": { "source": "actions", "message": "Invalid Subkey" } }
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
- 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.
- 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
required
Headers
Content-Type: application/json
Body
{ "type": "reaction", "value": "smiley_face" }
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" } }
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" } }
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" } ] } }
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." } }
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
- 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.
- 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
200
The action was removed.
Headers
Content-Type: application/json
Body
{ "status": 200, "data": {} }
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." } }
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" } }
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
- callback
string
(required) Example: 0pass function name to wrap in JSONP or
0
to disable JSONP
- uuid
string
(required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.
fetch time without JSONP
Headers
Location: /time/0
200
Headers
Content-Type: application/json
Body
[16068755276514766]
fetch time with JSONP
Headers
Location: /time/moose
200
Headers
Content-Type: text/javascript
Body
moose([14374273908474349])