Send messages

Sending messages is the cornerstone of PubNub. We guarantee that any message you send is delivered worldwide in under 30 ms. Messages arrive in the blink of an eye.

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.

JSON

{
    "content": {
        "type": "text",
        "message": "This is a message!"
    },
    "sender": "Thomas Anderson"
}

Plain text

"This is a message! Sender: Thomas Anderson"

URL-encoded object

"%7B%0A%20%20%20%20%22content%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%22
type%22%3A%20%22text%22%2C%0A%20%20%20%20%20%20%20%20%22message%22%3A%
20%22This%20is%20a%20message%21%22%0A%20%20%20%20%7D%2C%0A%20%20%20%20
%22sender%22%3A%20%22Thomas%20Anderson%22%0A%7D"

After you publish a message, PubNub returns a response that includes a timetoken, an exact timestamp (17‑digit value to the nearest 10th nanosecond) of when the message was published. Timetokens help you work with historical messages.

Depending on your needs, you can change the structure and add a custom type to your messages, send small bits of data designed for high volumes, or even send a file. If you need an extra layer of security, you might want to consider encrypting your messages and files.

Regardless of the payload, you always send it to a channel.

Think of a channel as a tunnel that PubNub uses to transmit data between devices. When you send a message, you must specify the channel. You can send a message to one channel at a time.

In the code below, the message of the text-message custom type is sent to the channel with the ID of my_channel. Note that not all SDKs yet support sending messages with a custom message type.

JavaScript

pubnub.publish(
  {
    channel: "my_channel",
    message: {"text": "This is my first realtime message!"},
    customMessageType: "text-message"
  },
  function(status, response) {
    console.log(status);
    console.log(response);
  }
);

Swift

pubnub.publish(
  channel: "my_channel",
  message: ["text": "This is my first realtime message!"]
  customMessageType: "text-message",
){ result in
  switch result {
    case let .success(response):
      print("succeeded: \(response)")

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

Objective-C

self.client.publish()
    .channel(@"my_channel")
    .message(@"This is my first realtime message!")
    .customMessageType(@"text-message")
    .performWithCompletion(^(PNPublishStatus *status) {

    if (!status.isError) {

        // Message successfully published to specified channel.
    }
    else {

        /**
         Handle message publish error. Check 'category' property to find
         out possible reason because of which request did fail.

show all 22 lines

Java

JsonObject data = new JsonObject();
data.addProperty("text", "This is my first realtime message!");

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

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

C#

Dictionary<string, string> data = new Dictionary<string, string>();
data.Add("text", "This is my first realtime message!");

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

show all 16 lines

Python

def publish_callback(result, status):
    if status.is_error():
        print(status.status_code, status.error_data.__dict__)
    else:
        print(result.timetoken)

pubnub.publish()\
  .channel("my_channel") \
  .message({"text": "This is my first realtime message!"})\
  .custom_message_type("text-message") \
  .pn_async(publish_callback)

Dart

var result = await pubnub.publish('my_channel', 'This is my first realtime message!');

Kotlin

val channel = pubnub.channel("myChannel")

val myMessage = JsonObject().apply {
    addProperty("text", "this is my first realtime message!")
}

channel.publish( 
  message = myMessage, 
  customMessageType = "text-message"
  ).async { result ->
    result.onFailure { exception ->
        println("Error while publishing")
        exception.printStackTrace()
    }.onSuccess { value ->
        println("Message sent, timetoken: ${value.timetoken}")

show all 17 lines

You don't need to create a channel before you send a message to it. A channel is created automatically when the first message is sent. All you need to do is provide the channel name. Try to be as descriptive as possible and adopt our channel naming convention in order not to miss out on certain PubNub features.

When you've sent your first message, you can check if it's been correctly sent by using the PubNub Debug Console, but now it's only natural to wonder how to receive messages someone else sent. Let's look into that.