Subscribe V2

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

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

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

Success Responses​

On success, an object is returned. Check the Responses section for more information. 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.

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.

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.

Path Parameters
sub_key string — REQUIRED

Your app's subscribe key from Admin Portal.

channel string — REQUIRED

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

Example: myChannel

callback string — REQUIRED

The JSONP callback name to wrap the function in. Use 0 for no callback.

Example (myCallback): myCallback

Example (zero): 0

Query Parameters
tt string

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

Example: 1231312313123

tr string

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

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

Example: cg1,cg2,cg3

state string

This parameter can be used to set the state. State is an object with root keys associated with each channel you are setting state for.

Example: %7B%22text%22%3A%22hey%22%7D

heartbeat integer

This query parameter can be used to set the presence timeout period. Heartbeat is the mechanism used to 'ping' back from the client to the server that the client is still online. Heartbeat has no functional effect on the performance or integrity of the client itself. Its only provided for Presence functionality. The heartbeat is only germane to the Presence service. Default value is 300

auth string

If the channel / channel group is protected by PAM, auth must be passed with a string which is either the auth key (PAM v2) or a valid token (Access Manager) used to authorize the operation.

Example: myAuthKey / p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenVzcqBDc3BjoERtZXRhoENzaWdYIGOAeTyWGJI

uuid string

A UTF-8 encoded string of up to 92 characters used to identify the client.

Example: myUniqueUserId

filter-expr string

Set filter expression for Subscribe message filtering.

Example: uuid%20!%3D%20%27cvc1%27

signature string

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 are required.

See Access Manager documentation for details on how to compute the signature.

timestamp integer

Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.

Required if signature parameter is supplied.

Responses
200

Success

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",
show all 22 lines
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
},
show all 23 lines
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-s9n4nan48rn-casd2-1123123e9-8b24-569e8a5c3af3",
show all 33 lines
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",
show all 31 lines
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",
show all 28 lines
Schema — OPTIONAL
t object — OPTIONAL
t string — OPTIONAL

the timetoken

r integer — OPTIONAL

the region

m object[] — OPTIONAL
a string — OPTIONAL

Shard

f integer — OPTIONAL

Flags

e integer — OPTIONAL

The value of this parameter denotes the type of messages e.g. 1 is for Signal, 2 is for Objects messages, 3 is for MessageAction messages, 4 is for Files messages

i string — OPTIONAL

Issuing Client Id

s integer — OPTIONAL

Sequence number

p object — OPTIONAL

Publish Timetoken Metadata

t string — OPTIONAL
r integer — OPTIONAL
k string — OPTIONAL

Subscribe Key

c string — OPTIONAL

Channel

d string — OPTIONAL

The payload

b string — OPTIONAL

Subscription match or the channel group

cmt string — OPTIONAL

Published custom message type data if query parameter set

400

Bad Request

Schema — OPTIONAL
status integer — OPTIONAL
service string — OPTIONAL
error boolean — OPTIONAL
message string — OPTIONAL
403

Unauthorized access

Schema — OPTIONAL
message string — OPTIONAL
payload object — OPTIONAL
channels string[] — OPTIONAL
error boolean — OPTIONAL
service string — OPTIONAL
status integer — OPTIONAL
413

Request Entity too large (larger than 30 bytes).

Schema — OPTIONAL
status integer — OPTIONAL
service string — OPTIONAL
error boolean — OPTIONAL
message string — OPTIONAL
429

Request rate limit exceeded.

Schema — OPTIONAL
status integer — OPTIONAL
error boolean — OPTIONAL
message string — OPTIONAL