Skip to main content

Publish

Overview​

The publish operation allows your application to send messages to a specific topic. When you publish a message to a topic, all subscribers to that topic immediately receive the message. This is the core mechanism for broadcasting updates, events, or data within a real-time messaging system.

How Publishing Works​

  • Specify the topic: Every message must be published to a valid topic name, following the topic naming rules described earlier.
  • Prepare your payload: The message can be any serializable data (JSON, dictionary, hash map, string, or number), depending on your SDK/language.
  • Publish the message: Use the SDK’s publish method to send the message to the selected topic.
  • Delivery semantics: Messages are delivered to all current subscribers of the topic, in real time with At Least Once QoS.
// Select a platform to see code

tip

publish($topic, $message) won't throw an error if you publish to a wildcard, but subscribers matching the pattern will not receive the message.


publish($topic, $message) returns true if publish was successful. It returns false if,

  • The message was not sent
  • The SDK was in a reconnect state. In this state, the message is stored offline and published upon reconnect.
  • The connection between the SDK & the Relay Network is closed.

Error Handling​

publish($topic, $message) throws errors when,

  • Topic is invalid
  • Topic is a system reserved topic
  • Publishing a message is attempted when the message limit has been exceeded. This is only for the free plan.

Message Republish on Reconnect​

When the client SDK is in the reconnecting state, any messages that are published are stored in an offline buffer for 2 mins (before the client permanently closes connection). When the client reconnects successfully, the messages are republished.

To get confirmation that the messages were sent, subscribe to the MESSAGE_RESEND topic,

// Select a platform to see code

By following these guidelines and examples, you can reliably publish messages to any topic and enable real-time communication across your applications and services.


Need Help?

Join our Discord server, post your concern & someone from our team will help you out ✌️