Message Publish

The foundation of all our PubNub offerings is the ability to send a message that will be delivered anywhere in less than 30ms. Below, we will walk you step by step through different ways of sending a message.

Need help. Flat tire. Kansas City.

A PubNub Message can contain any kind of serializable data, like objects, numbers and UTF-8 encoded strings. Its format may be plain text, a URL-encoded object, or most commonly, JavaScript Object Notation (JSON). The max size of a message is 32 Kibibytes (KiB). You can check the size of your message payload using our message size calculator.

Receiving messages

We hope you already know you need to add a listener to receive and handle incoming messages, signals, and events.

If you're new to PubNub, make sure to check out how to set up your account as well.

Send Messages

The primary means for sending messages is using the Publish API. You may only send a message to one channel at a time. If you want to publish to multiple channels, you must create a channel group.

PubNub's network supports sending unlimited publishes without waiting for response on the same TCP socket connection.

pubnub.publish(
  {
    channel: "my_channel",
    message: {"text": "Hello World!"}
  },
  function(status, response) {
    console.log(status);
    console.log(response);
  }
);

pubnub.publish(
  channel: "my_channel",
  message: ["text": "Hello World!"]
){ result in
  switch result {
    case let .success(response):
      print("succeeded: \(response)")

    case let .failure(error):
      print("failed: \(error.localizedDescription)")
  }
}

[self publish: @{@"text" : @"Hello World!"} toChannel:@"my_channel"
    completion:^(PNPublishStatus *status) {
    NSLog(@"%@status '%@'", status);
}];

JsonObject data = new JsonObject();
data.addProperty("text", "Hello World!");

Channel channel = pubnub.channel("my_channel");

channel.publish(data)
  .async(result -> { /* check result */ });

Dictionary<string, string> data = new Dictionary<string, string>();
data.Add("text", "Hello World!");

pubnub.Publish()
  .Channel("my_channel")
  .Message(data)
  .Execute(new PNPublishResultExt(
    (result, status) => {
      if (status.is_error()) {
        Console.WriteLine("status code: " + status.ErrorData.Information);
      }
      else {
        Console.WriteLine("timetoken: " + result.Timetoken.ToString());
      }
    }
show all 16 lines

def publish_callback(result, status):
  if status.is_error():
    print status.status_code
  elif
    print result.timetoken

pubnub.publish()\
  .channel("my_channel") \
  .message({"text": "Hello World!"})\
  .pn_async(publish_callback)

When you publish a message to a channel, you're asking PubNub Platform to deliver that message to everyone who is subscribed to that channel.

A PubNub message may be sent as plain text, URL-encoded object, and most commonly, JSON. For more information, refer to message types.

As you can see, in the above publish method we specify the channel on which to send the message, the message content we want to send and a way to capture the server response, which in most languages is an asynchronous callback. A successful response looks like this:

[1,"Sent","14375189629170609"]

The response has three parts:

success flag: 1 = success, 0 = failed
response message: Sent or Failed
publish timetoken: exact timestamp of the message which is a 17 digit value to the nearest 10th nanosecond (can be converted to UNIX epoch by dividing by 10000).

The publish timetoken can be used later to retrieve (or augment) that message using Message Persistence.

HTTP Streaming and pipelining

For more information about streaming and pipelining, refer to this gist.

Send announcements to all users

You can send announcements to all users, or a limited set of users, in your application by using a channel to which the announcer has read/write access, and to which all other users have read-only access.

Once you have the channel set up, you can display any messages sent on the channel as announcements. Users with read access can subscribe to the channel to receive announcements, but can't send messages on the same channel.

JavaScript
Swift
Java
Unity

pubnub.publish({
  message: {
    type: 'announcement',
    text: 'Hello, this is an announcement'
  },
  channel: 'ch-1',
}, (status, response) => {
  // handle status, response
});

pubnub.publish(
  channel: "ch-1",
  message: ["type": "announcement", "text": "Announcement message to all users"]
) { result in
  switch result {
  case let .success(response):
    print("Successful Publish Response: \(response)")
  case let .failure(error):
    print("Failed Publish Response: \(error.localizedDescription)")
  }
}

// Java SDK uses channel-based publish
JsonObject messagePayload = new JsonObject();
messagePayload.addProperty("type", "announcement");
messagePayload.addProperty("text", "Hello, this is an announcement");

Channel channel = pubnub.channel("ch-1");

channel.publish(messagePayload)
        .async(result -> { /* check result */ });

Dictionary<string, string> payload = new Dictionary<string, string>();
payload.Add("type", "announcement");
payload.Add("text", "Hello, this is an announcement");

pubnub.Publish()
    .Channel("ch-1")
    .Message(payload)
    .Async((result, status) => {
        if (!status.Error) {
            Debug.Log(result.Timetoken);
        } else {
            Debug.Log(status.Error);
            Debug.Log(status.ErrorData.Info);
        }
    });

Message Specifications

The message property can contain any JSON serializable data (JSON isn't required, just recommended and is typical in most use cases), including: Objects, Arrays, Integers and Strings. String content can include any single-byte or multi-byte UTF-8 character.

JSON Serialization

There is no need to serialize your JSON object when sending messages via PubNub Platform. PubNub SDKs does that for you.

Delivery

Though we provide as much information about the delivery as possible, PubNub is not a guaranteed message delivery service, as there is no way to guarantee that the network connection between the subscribers and PubNub has not been interrupted.

For example, while the Sent status code returned to the message publisher does not guarantee that the message is delivered, it does mean that the PubNub Network has received the message and has already sent it along to all currently connected subscribers.

We are constantly adding features which improve deliverability but the quality of service of the last mile of connectivity is not within PubNub's control.

Subscribers with troubled connections or that were offline by intention can still retrieve missed messages. For more information about status codes, and retrieving missed and historical messages, refer to Connection Management and Message Persistence.

Order

As long as the publisher sends messages at a slower rate than the consumer can receive them, you can assume with high confidence that messages will be kept in order.

However, PubNub doesn't guarantee that messages are stored or sent in the exact same order in which they're published. If your application requires messages to be processed in the same order they were published, we recommend adding a sequence field to the message payload and use it to order messages by.

Message Size Limit

The maximum number of characters per message is 32 KiB. The maximum message size is based on the final escaped character count, including the channel name.

If the message you publish exceeds the configured size, you'll receive the following message:

["PUBLISHED",[0,"Message Too Large","13524237335750949"]]

If you expect your messages will be pushing the size limit, check the size of your message in our payload size calculator.

Channel nameMessage body

Payload Size: 0.00 KiB (0 bytes)

For more information on calculating payload size within your application, refer to our knowledge base.

Receive Messages

To receive a message, your client should implement a message listener and subscribe to a channel in which the message is being published.

Send Signals

Signals are ideal for high-volume, low-cost use cases. They're intended for sending small bits of data where the last sent data is the only important piece of information. For example, chat typing indicators, live GPS location updates, and sensor updates from IoT devices.

Sounds like a solution: How we used PubNub to jazz up in-store audio experiences

Messages vs Signals

Signals are similar to regular messages, with the following exceptions:

Feature	Signals	Messages
Payload size	Limited to 64 bytes (64B)	Up to 32 kilobytes (32KB)
Cost efficiency	Cost less than standard messages	Generally more expensive than signals
Persistence	Cannot be saved in Message Persistence (past signals cannot be accessed)	Can be saved and accessed through Message Persistence
Push Notifications	Cannot trigger Mobile Push Notifications	Can trigger Mobile Push Notifications
Use case suitability	Best for non-critical data streams, like geolocation updates	Suitable for critical and non-critical use cases
Metadata support	Do not support metadata	Support metadata

Channel separation

Signals and messages should be sent on separate channels to improve connection recovery behaviour.

Sending a signal is similar to publishing a message:

let gps = ["35.9296","-78.9482"];

pubnub.signal(
  {
    channel: "locations.route1",
    message: gps
  },
  function(status, response) {
    console.log(status, response);
  }
);

let gps = ["35.9296","-78.9482"]

pubnub.signal(
  channel: "locations.route1",
  message: gps
) { result in
  switch result {
  case let .success(response):
    print("succeeded: \(response)")

  case let .failure(error):
    print("failed: \(error.localizedDescription)")
  }
}

NSArray *gps = [NSArray arrayWithObjects:@"35.9296,@"-78.9482",nil];

[self signal: gps toChannel: @"locations.route1"
    completion:^(PNPublishStatus *status) {

  NSLog(@"%@status '%@'", status);
}];

// Java SDK uses channel-based publish
String[] gps = new String[]{"35.9296","-78.9482"};

Channel channel = pubnub.channel("locations.route1");

channel.signal(gps)
  .async(result -> { /* check result */ });

string[] arrayMessage = new string[] {"35.9296","-78.9482"};

pubnub.Signal()
  .Message(data)
  .Channel("locations.route1")
  .Execute(new PNPublishResultExt(
    (result, status) => {
      if (status.is_error()) {
        Console.WriteLine("status code: " + status.ErrorData.Information);
      }
      else {
        Console.WriteLine("timetoken: " + result.Timetoken);
      }
    }
  ));

def signal_callback(result, status):
  if status.is_error():
    print status.status_code
  elif
    print result.timetoken

pubnub.signal()\
  .channel("locations.route1") \
  .message({"msg": "Hello, my friend!"})\
  .pn_async(signal_callback)

The Signal response may not be as important to your application and could be omitted, but is dependent on your use case.

Receive Signals

To receive a signal, your client should implement a signal listener and subscribe to a channel in which the signal is being sent.

Publish with Message Filters

Message Filters allow a client to send messages to only those clients that satisfy the conditions of the filter. To use Message Filters, it's important to include filtering conditions when publishing a new message. The meta parameter isn't a part of the message data and allows subscribing clients to filter based on the included information.

Filtering origin

The filtering takes place server-side.

To include metadata that can be used for message filters, prepare the data and pass it to the publishing function.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

pubnub.publish(
  {
    channel: "chats.room1",
    message: "Hello to everyone (except me)",
    meta: {
      userId: pubnub.getUserId()
    }
  },
  function(status, response) {
    console.log(status, response);
  }
);

pubnub.publish(
  channel: "chats.room1",
  message: "Hello to everyone (except me)",
  meta: ["userId": pubnub.configuration.userId]
) { result in
  switch result {
  case let .success(response):
    print("Successful Publish Response: \(response)")

  case let .failure(error):
    print("Failed Publish Response: \(error.localizedDescription)")
  }
}

NSDictionary *meta = @{@"uuid": self.pubnub.uuid};

[self.pubnub publish:@"Hello to everyone (except me)"
      toChannel:@"chats.room1" withMetadata:meta
      completion:^(PNPublishStatus *status) {

  NSLog(@"%@status '%@'", status);
}];

// Java SDK uses channel-based publish
Map<String, Object> meta = new HashMap<>();
meta.put("userId", pubnub.getUserId());

Channel channel = pubnub.channel("chats.room1");

channel.publish("Hello to everyone (except me)")
  .meta(meta)
  .async(result -> { /* check result */ });

Dictionary<string, object> meta = new Dictionary<string, object>();
meta.Add("UserId", pubnub.GetCurrentUserId());

pubnub.Publish().Channel("chats.room1").Meta(meta)
  .Message("Hello to everyone (except me)")
  .Execute(new DemoPublishResult());

meta = {"user_id": pubnub.get_user_id()}

pubnub.publish()\
  .channel("chats.room1")\
  .meta(meta)\
  .message("Hello to everyone (except me)")\
  .sync()

In the above example, the metadata will allow the client to filter messages based on the User ID of the sender.

To learn more about the filter options, refer to the table in the Message Filters section.

Need help. Flat tire. Kansas City.

Receiving messages

Send Messages​

HTTP Streaming and pipelining

Send announcements to all users​

Message Specifications​

JSON Serialization

Delivery​

Order​

Message Size Limit​

Receive Messages​

Send Signals​