--- source_url: https://www.pubnub.com/docs/sdks/rest-api/subscribe-v-2 title: Subscribe V2 --- # Subscribe V2 > For AI agents: documentation index at https://www.pubnub.com/llms-full.txt 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 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 | | Query Parameters | | --- | | `tt`string0 (zero) for the initial subscribe, or a valid timetoken if resuming / continuing / fast-forwarding from a previous subscribe flow.Example: 1231312313123 | | `tr`stringRegion 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`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 | | `filter-expr`stringSet filter expression for Subscribe message filtering.Example: uuid%20!%3D%20%27cvc1%27 | | `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`SuccessBody (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","cmt": "chat_custom_message_type","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-s9n4nan48rn-casd2-1123123e9-8b24-569e8a5c3af3","c": "userid0","d": "my-signal","cmt": "chat_custom_message_type","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-s9n4nan48rn-casd2-1123123e9-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"}]}Schema — 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. tt Type: string 0 (zero) for the initial subscribe, or a valid timetoken if resuming / continuing / fast-forwarding from a previous subscribe flow. tr Type: 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 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) . filter-expr Type: string Set filter expression for Subscribe message filtering. 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. 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", "c": "my-channel", "d": "my message", "cmt": "chat_custom_message_type", "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-s9n4nan48rn-casd2-1123123e9-8b24-569e8a5c3af3", "c": "userid0", "d": "my-signal", "cmt": "chat_custom_message_type", "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-s9n4nan48rn-casd2-1123123e9-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" } ] } ``` 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" } ] } ```