--- source_url: https://www.pubnub.com/docs/sdks/rest-api/subscribe-v-1 title: Subscribe V1 --- # Subscribe V1 > For AI agents: documentation index at https://www.pubnub.com/llms-full.txt 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 ID(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): myCallbackExample (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): 1231312313123Example (zero): 0 | | 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: cg1,cg2,cg3 | | `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: %7B%22text%22%3A%22hey%22%7D | | `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 Access Manager, auth must be passed with a string which is either the auth key (Access Manager legacy) or a valid token (Access Manager) used to authorize the operation.Example: myAuthKey | | `uuid`stringA UTF-8 encoded string of up to 92 characters used to identify the client.Example: myUniqueUserId | | `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 signature parameter is supplied. | | Responses | | --- | | `200`SuccessSchema — OPTIONALt object — OPTIONALt string — OPTIONALthe timetokenr integer — OPTIONALthe regionm object[] — OPTIONALa string — OPTIONALShardf integer — OPTIONALFlagse integer — OPTIONALThe 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 messagesi string — OPTIONALIssuing Client Ids integer — OPTIONALSequence numberp object — OPTIONALPublish Timetoken Metadatat string — OPTIONALr integer — OPTIONALk string — OPTIONALSubscribe Keyc string — OPTIONALChanneld string — OPTIONALThe payloadb string — OPTIONALSubscription match or the channel groupcmt string — OPTIONALPublished custom message type data if query parameter set | Schema—**OPTIONAL** | `t`object—**OPTIONAL**t string — OPTIONALthe timetokenr integer — OPTIONALthe region | `t`string—**OPTIONAL**the timetoken | `r`integer—**OPTIONAL**the region | `m`object[]—**OPTIONAL**a string — OPTIONALShardf integer — OPTIONALFlagse integer — OPTIONALThe 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 messagesi string — OPTIONALIssuing Client Ids integer — OPTIONALSequence numberp object — OPTIONALPublish Timetoken Metadatat string — OPTIONALr integer — OPTIONALk string — OPTIONALSubscribe Keyc string — OPTIONALChanneld string — OPTIONALThe payloadb string — OPTIONALSubscription match or the channel groupcmt string — OPTIONALPublished custom message type data if query parameter set | `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 Metadatat string — OPTIONALr integer — OPTIONAL | `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 | | Schema—**OPTIONAL** | | `t`object—**OPTIONAL**t string — OPTIONALthe timetokenr integer — OPTIONALthe region | `t`string—**OPTIONAL**the timetoken | `r`integer—**OPTIONAL**the region | | `t`string—**OPTIONAL**the timetoken | | `r`integer—**OPTIONAL**the region | | `m`object[]—**OPTIONAL**a string — OPTIONALShardf integer — OPTIONALFlagse integer — OPTIONALThe 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 messagesi string — OPTIONALIssuing Client Ids integer — OPTIONALSequence numberp object — OPTIONALPublish Timetoken Metadatat string — OPTIONALr integer — OPTIONALk string — OPTIONALSubscribe Keyc string — OPTIONALChanneld string — OPTIONALThe payloadb string — OPTIONALSubscription match or the channel groupcmt string — OPTIONALPublished custom message type data if query parameter set | `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 Metadatat string — OPTIONALr integer — OPTIONAL | `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 | | `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 Metadatat string — OPTIONALr integer — OPTIONAL | `t`string—**OPTIONAL** | `r`integer—**OPTIONAL** | | `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 RequestSchema — OPTIONALstatus integer — OPTIONALservice string — OPTIONALerror boolean — OPTIONALmessage string — OPTIONAL | Schema—**OPTIONAL** | `status`integer—**OPTIONAL** | `service`string—**OPTIONAL** | `error`boolean—**OPTIONAL** | `message`string—**OPTIONAL** | | Schema—**OPTIONAL** | | `status`integer—**OPTIONAL** | | `service`string—**OPTIONAL** | | `error`boolean—**OPTIONAL** | | `message`string—**OPTIONAL** | | `403`Unauthorized accessSchema — OPTIONALmessage string — OPTIONALpayload object — OPTIONALchannels string[] — OPTIONALerror boolean — OPTIONALservice string — OPTIONALstatus integer — OPTIONAL | Schema—**OPTIONAL** | `message`string—**OPTIONAL** | `payload`object—**OPTIONAL**channels string[] — OPTIONAL | `channels`string[]—**OPTIONAL** | `error`boolean—**OPTIONAL** | `service`string—**OPTIONAL** | `status`integer—**OPTIONAL** | | Schema—**OPTIONAL** | | `message`string—**OPTIONAL** | | `payload`object—**OPTIONAL**channels string[] — OPTIONAL | `channels`string[]—**OPTIONAL** | | `channels`string[]—**OPTIONAL** | | `error`boolean—**OPTIONAL** | | `service`string—**OPTIONAL** | | `status`integer—**OPTIONAL** | | `413`Request Entity too large (larger than 64 bytes).Schema — OPTIONALstatus integer — OPTIONALservice string — OPTIONALerror boolean — OPTIONALmessage string — OPTIONAL | Schema—**OPTIONAL** | `status`integer—**OPTIONAL** | `service`string—**OPTIONAL** | `error`boolean—**OPTIONAL** | `message`string—**OPTIONAL** | | Schema—**OPTIONAL** | | `status`integer—**OPTIONAL** | | `service`string—**OPTIONAL** | | `error`boolean—**OPTIONAL** | | `message`string—**OPTIONAL** | | `429`Request rate limit exceeded.Schema — OPTIONALstatus integer — OPTIONALerror boolean — OPTIONALmessage string — OPTIONAL | Schema—**OPTIONAL** | `status`integer—**OPTIONAL** | `error`boolean—**OPTIONAL** | `message`string—**OPTIONAL** | | Schema—**OPTIONAL** | | `status`integer—**OPTIONAL** | | `error`boolean—**OPTIONAL** | | `message`string—**OPTIONAL** | sub_key * Type: string Your app's subscribe key from [Admin Portal](https://admin.pubnub.com) . channel * Type: string The channel ID(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 * Type: string The JSONP callback name to wrap the function in. Use 0 for no callback. timetoken * Type: string 0 for the initial subscribe, or a valid timetoken if resuming / continuing / fast-forwarding from a previous subscribe flow. channel-group Type: 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. state Type: 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. heartbeat Type: 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 Type: string If the channel / channel group is protected by Access Manager, auth must be passed with a string which is either the auth key (Access Manager legacy) or a valid token ( [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) ) used to authorize the operation. uuid Type: string A UTF-8 encoded string of up to 92 characters used to [identify the client](https://www.pubnub.com/docs/architecture/core-concepts.md) . signature Type: 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 Type: 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. t Type: object m Type: array Array items: items Type: object Example Response ``` { "t": { "t": "96137360022444528", "r": 4 }, "m": [ { "a": "1", "f": 514, "i": "pn-0ca50551-4bc8-446e-8829-c70b704545fd", "s": 1, "p": { "t": "0", "r": 4 }, "k": "demo", "c": "my-channel", "d": "my message", "b": "my-channel", "cmt": "chat_custom_message_type" } ] } ```