Skip to main content

Subscribe & Unsubscribe

Overview​

Subscribing allows your application to receive messages published to specific topics or topic patterns. When you subscribe to a topic, your client opens a message stream and gets real-time delivery of all messages sent to that topic by other clients.

Unsubscribing stops message delivery for the specified topic, freeing up resources on both client and server.

How Subscribe / Unsubscribe Works​

Subscribe​

  • Specify the topic: You subscribe to a valid topic or topic pattern, following the topic naming rules described earlier. Wildcards (* and >) are supported for flexible, broad subscriptions.
  • Receive messages: The SDK delivers all matched messages to your subscription callback or event handler in real time.
  • Multiple subscriptions: You can maintain multiple subscriptions simultaneously, each independently delivering messages for different topics or patterns.
  • System Reserved Topics: You can also subscribe to system reserved topics to receive connection events and other system-level notifications.
// Select a platform to see code

on() returns a boolean,

  • Returns true if a topic has been subscribed to
  • Returns false if,
    • The topic has already been subscribed to
    • OR if the SDK failed to create a subscription to the topic

Unsubscribe​

Call off() and pass the topic you want to unsubscribe from.

// Select a platform to see code

The off() method returns a boolean,

  • Returns true if the topic was successfully unsubscribed from
  • Returns false if unsubscribing from the topic failed

Wildcard Behaviour​

Wildcards let subscribers match messages from multiple related topics without specifying each one individually:

  • Asterisk (*): Matches exactly one token at the position it appears.
    • devices.*.temperature matches devices.kitchen.temperature and devices.livingroom.temperature.
  • Greater-than (>): Matches one or more tokens at the end of a subject and must only appear as the last token.
    • devices.> matches devices.kitchen.temperature, devices.kitchen.humidity, and devices.livingroom.temperature.
    • > matches all topics.
  • Mixing wildcards: You can use multiple * in a topic and can mix both wildcards.
    • *.us.> matches topics beginning with any token, followed by us, then any other sequence (e.g., temp.us.nyc, humidity.us.la.outdoor).

Wildcard use is only supported in subscriptions, not when publishing, and allows for highly flexible, scalable subscription patterns.

By defining and using topics with hierarchical names and wildcards, you can build scalable, flexible message routing in your applications and ensure that each component or service receives only the messages it needs.

Message Replay & Delivery Guarantees​

  • Automatic Replay: If your client disconnects and then reconnects, the SDK automatically delivers any messages that were published during the offline period, ensuring you do not miss messages.
  • Replay Scope: Message replay is only done for active subscriptions prior to disconnection.
  • Ordering: Messages are delivered in the order they were published, preserving sequence integrity.
  • At Least Once Delivery: Messages may be delivered more than once in rare failure scenarios—your application should be idempotent where necessary.

By adhering to these subscription guidelines, your application will efficiently and reliably receive real-time messages relevant to your topics of interest.


Need Help?

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