Subscribe V1

Subscribe to channels and/or channel groups.

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.

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

timetoken string — REQUIRED

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

Example (nonZero): 1231312313123

Example (zero): 0

Query Parameters
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

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

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