Listen for messages on a specified channel. options contains channel, callbacks for network status and error events (such as connect, disconnect, and reconnect), and a callback for receiving messages.

Code Example

PUBNUB.subscribe({    channel    : "my-channel",    callback   : function(message) { log(message) },    connect    : function() { log("Connected") },    disconnect : function() { log("Disconnected") },    reconnect  : function() { log("Reconnected") },    error      : function() { log("Network Error") },    restore    : true})


Message, connect, disconnect, and reconnect callbacks

Each time the PubNub client subscribes to a channel, a “subscription-based connection” is established to the PubNub cloud. During the lifecycle of this “subscription-based connection”:

  1. When the subscribe connection is initially made to the server, the connect callback will fire only once.
  2. The message callback (aptly named "callback") will fire each time a message is received.
  3. If the client loses connection to the server, the disconnect callback will fire only once.
  4. If the client is able to reconnect to the server after a disconnect, the reconnect callback will fire only once upon


RESTful Example


_ NOTE _ : It is critical that you make sure that all special characters are URL-encoded to ensure proper operation.

URL and Parameters


SUBSCRIBE_KEY is your assigned subscribe key. Subscribe keys begin with the prefix "sub-"

CHANNEL is channel or channels (separated by commas) you wish to publish messages to.

JSONP_CALLBACK (Optional) is the name of the callback function you wish to wrap the response around.

_ NOTE: _ If you are not using a JSONP callback, use 0 as a placeholder.

TIMETOKEN : The timetoken represents a nanosecond precision UNIXTIME value. When subscribing use TIMETOKEN = 0 for the first request to get the current timetoken.

UUID_STRING (Optional): This is used to uniquely identify a client. By default, it uses a system-generated UUID, but you can override this with a custom value during init().

_ NOTE: _ For unique clients to be tracked, a UUID value should be included with each subscribe request. The UUID may be any string value such as a user name or user ID, but the default string generated by PubNub's client libraries follow the uuid4 spec resembling c05cca54-45ab-49d3-861b-d50fe2be9304. It is recommended the client cache the UUID so that the same UUID is used consistently on each subscribe connection. Clients that do not include a UUID will not be counted in presence stats. Do not share this UUID between clients or presence will have inconsistent behavior.

Subscribe Call Repetition Flow

In order for the server to chronologically discern messages, i.e, identify messages based on the time that they were published, a timetoken must be passed in each subsequent subscribe request. This timetoken acts as a “last sent” pointer in the channel's message stream.

_ NOTE: _ During the subscribe flow, there is a continue flow of client<->server<->client data. As such, it is imperative to implement HTTP Keep-Alive on the client-side to decrease the latencies involved in establishing and tearing down the repeated connections.

On the initial subscribe call, TIMETOKEN should be set to the integer 0. This will register a "Presence" event against that UUID and channel (see presence() for more information).

Subscribing with a TIMETOKEN of 0 will also return an empty messages element (element 0), along with the the current timetoken (element 1). An example is of an initial subscribe with TIMETOKEN = 0 is shown below:

$ curl\_key/my-channel/0/0?uuid=MY\_UNIQUE\_ID

[[], 123456789]


On all subsequent subscribe calls, when using the value of TIMETOKEN from the last call (123456789 from the above example), the server will long poll until it either:

  1. Times-out after 300s.
  2. Receives one or more messages from the server.

If the server times-out after 300s, it will return a response similar to the initial TIMETOKEN = 0 request, i.e., an empty message element with the current timetoken. The client should use this returned timetoken as the TIMETOKEN value to subscribe again with.

If the server receives one or more messages from the server,

If you are subscribed to only one channel , your response will look similar to:

$ curl

[[{"foo":"bar"}, 1, "foobar], 123459876]


When subscribed to more than one channel, there will be an element 2, as depicted by the array value " channel_a,channel_b,channel_a" above. This correlates, in order, to the channels the messages in element 0 were received on.

So, if you are subscribed to more than one channel , your response will look similar to:

$ curl,channel_b/0/123456789?uuid=MY_UNIQUE_ID

[[{"foo":"bar"}, 1, "foobar], 123459876, "channel_a,channel_b,channel_a"]


The following graphically depicts the subscribe flow:



Regardless if you subscribe to one, or many channels, for each message item in element 0 , the message callback should be fired once with the following signature:


Where MESSAGE_ITEM is from element 0 message payload, TIMETOKEN is element 1 of the response, and CHANNEL is the channel the message was received on.

Successful Response

See "Subscribe Call Repetition Flow" above for examples of successful responses.

Failure Response

[0,"Error description here"]