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 — REQUIREDYour app's subscribe key from Admin Portal. |
channel string — REQUIREDThe 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:
|
callback string — REQUIREDThe JSONP callback name to wrap the function in. Use Example (myCallback):
Example (zero):
|
timetoken string — REQUIRED0 for the initial subscribe, or a valid timetoken if resuming / continuing / fast-forwarding from a previous subscribe flow. Example (nonZero):
Example (zero):
|
Query Parameters |
---|
channel-group stringChannel 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:
|
state stringThis 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:
|
heartbeat integerThis 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 stringIf the channel / channel group is protected by PAM, Example:
|
uuid stringA UTF-8 encoded string of up to 92 characters used to identify the client. Example:
|
signature stringSignature 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 integerUnix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP. Required if |
Responses | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 Success
| ||||||||||||||||||
400 Bad Request
| ||||||||||||||||||
403 Unauthorized access
| ||||||||||||||||||
413 Request Entity too large (larger than 30 bytes).
| ||||||||||||||||||
429 Request rate limit exceeded.
|