Satori Docs

Your definitive guide to subscribing and publishing live data

Publishing Direct link

You publish messages by specifying a channel name and attaching your content. With RTM SDKs, you pass the content as a message parameter of the publish function. If using raw RTM API, you place the content inside the message field of the Publish PDU.

The message content can be any valid json object but be aware of the size limit if you are sending very large payloads: see formal specification of Publish PDU in RTM API.

Examples Direct link

RTM SDK code snippets assume the RTM client instance and connecting code as shown in the Setup section.

Full source code for all RTM SDK examples is available on github:

JavaScript | Java | Python | C | C# | Go

RTM SDKs example

The example below shows how to publish a message with an acknowledgement to a channel and handle a publish response from the RTM service. In this example, a location of a zebra is published to the "animals" channel.

var channelName = 'animals';
var message = {
  who: 'zebra',
  where: [ 34.134358, -118.321506 ]
client.publish(channelName, message , function (pdu) {
  if (pdu.action === 'rtm/publish/ok') {
    console.log('Publish confirmed');
  } else {
    console.log('Failed to publish. RTM replied with the error  ' +
        pdu.body.error + ': ' + pdu.body.reason);

Wire protocol example

Below is full raw json publish PDU example on the wire.

  "action": "rtm/publish",
  "id": "42",
  "body": {
    "channel": "animals",
    "message": {
      "who": "zebra",
      "where": [34.134358,-118.321506]
  • action field instructs that this is a publish operation for RTM service

  • user assigned id “42” to this publish request

  • body structure for publish operation request contains:

    • “animals” channel name to publish a message to
  • “message field with user payload: custom JSON object with “who” and “where” fields.

Because the id field was specified in the publish request, we will receive either “ok” or “error” response from RTM.

ok outcome

Response with ok outcome confirms that our messages has been successfully published to a channel:

  "action": "rtm/publish/ok",
  "body": {
    "position": "1491076785:3"
  "id": "42"
  • action field indicates “ok” outcome: publish succeeded

  • id “42” matches id in the publish request

  • message was published to channel position "1491076785:3"

For completeness, we show a data PDU seen by the subscribers of “animals” channel from the publish. Subscribing is described here.

  "action": "rtm/subscription/data",
  "body": {
    "subscription_id": "animals",
    "position": "1491076785:4",
    "messages": [{ "who": "zebra", "where": [34.134358, -118.321506]}]

error outcome

Below example illustrates error repose to a publish attempt without proper permissions.

  "action": "rtm/publish/error",
  "id": "42",
  "body": {
    "error": "authorization_denied",
    "reason": "Unauthorized"

Publishing with acks Direct link

When publish request contains id field, it instructs RTM to acknowledge our request. In other words RTM will send a response with the outcome (ok or error). We refer to this mode as publishing with acks. Acknowledgment, ack and response refer to the same thing.

Publishing with acks is a typical choice because it allows error checking and obtaining a position of the published message (position returned in the response PDU).

Pipelined publishing

You should not wait for an ack to continue publishing, unless your business logic requires such “blocking” wait.  Pipelining is just a fancy word to describe this mode: keep on sending, -- responses will arrive some time later, in the expected order. RTM guarantees the same order of response for consecutive publish requests per channel basis.

Pipelined mode minimizes effective latency, both for the publisher and in terms of data delivery to the channel (and in turn to its subscribers).

Fire & forget publishing (no id field) Direct link

Fire & forget mode refers to publishing without specifying id in the request PDU. In RTM v2 protocol, if no id was specified in a request, no response is generated by RTM (including error outcome). The choice between with and without ack mode is a tradeoff between reliability and efficiency. 

You should consider fire & forget mode only if you do not care about the outcome of your publish request (whether it succeeded or failed) or about the info supplied with the reply (position of the published message).

This mode may benefit certain types of publishers, such as in high throughput scenarios, where cutting down on the amount of response traffic could provide significant savings, yet there is no impact of occasional data loss due to an error (publisher will not resend or handle it elsehow).

You should estimate the benefit from this mode and consider setting up some sort monitoring in case of persistent failures if choosing this mode.

Position field in publishing Direct link

Successful publish response includes a position field. Position value is generated by RTM and uniquely identifies message placement within a channel. It can be used in more complex interactions to back-reference the messages.

Both publish reply and subscription data PDUs contain the position field but notice the difference in values in the example above: semantics are slightly different. Publisher receives a position corresponding to the message itself, while subscribers get the position next after the message.

See more comprehensive position coverage in RTM API