Messages

Ably Platform allows for clients to send information with messages, which contain data the client wishes to communicate. These messages are published through channels, which other users can subscribe to in order to receive them. This scalable and resilient messaging pattern is commonly called pub/sub.

The Ably REST client library provides a straightforward API for publishing messages and retrieving message history from a channel.

JavaScriptNode.jsRubyPythonPHPJavaC# .NETObjective-CSwift
JavaScript

var rest = new Ably.Rest('<loading API key, please wait>');
var channel = rest.channels.get('mud-ate-ago');
channel.publish('example', 'message data', function() {
  channel.history(function(err, resultPage) {
    console.log('Last published message:' + resultPage.items[0]);
  });
});

API Key:
Demo Only
Copy
Copied!

If you would prefer to just dive into code and see some examples of how to use messages, then we recommend you take a look at our REST tutorials.

Each message published has an optional event name property and a data property carrying the payload of the message. Various primitive and object types are defined, portable and supported in all clients, enabling clients to be interoperable despite being hosted in different languages or environments.

The supported payload types are Strings, JSON objects and arrays, plain c# objects which are converted to json, buffers containing arbitrary binary data, and Null objects. Client libraries detect the supplied message payload and encode the message appropriately.

The REST client library does not offer message realtime subscription but instead provides access to the “live” history using the REST history API. Find out more about subscribing to messages in realtime using the Realtime API.

The name property of published messages does not affect the distribution of a channel message to clients but may be used as a subscription filter, allowing a client to register a listener that only sees a subset of the messages received on the channel. Find out more about registering listeners using the Realtime API.

Channels expose a publish method whereby a client can publish either a single message or an array of messages to a channel over REST.

JavaScriptNode.jsRubyPythonPHPJavaC# .NETObjective-CSwift
JavaScript
channel.publish('event', 'This is my payload', function(err) {
  if(err) {
    console.log('Unable to publish message; err = ' + err.message);
  } else {
    console.log('Message successfully sent');
  }
});
Copy
Copied!

Message published using the REST API may be done so on behalf of an existing realtime connection when a valid connectionKey is present in the published message. For example, if you want to publish a message using the REST client library so that it appears to come from an existing connected realtime client, then the connection’s private (secret) connection key must be included. See a publish on behalf of a realtime client example.

If the connectionKey is invalid or belongs to a connection that has since been closed, then the publish operation will fail.

Channels expose a history method providing a means for clients to obtain messages previously sent on the channel. Channel history can be used to return continuous message history up to the exact point a realtime channel was attached.

History provides access to instantaneous “live” history as well as the longer term persisted history for attached channels. If persisted history is enabled for the channel, then messages will typically be stored for 24 – 72 hours. If persisted history is not enabled, Ably retains the last two minutes of message history in memory.

The following example retrieves the first two pages of historical messages published up until the point the channel was attached.

JavaScriptNode.jsJavaC# .NETRubyPythonPHPObjective-CSwift
JavaScript
channel.history(function(err, resultPage) {
  if(err) {
    console.log('Unable to get channel history; err = ' + err.message);
  } else {
    console.log(resultPage.items.length + ' messages received in first page');
    if(resultPage.hasNext()) {
      resultPage.next(function(err, nextPage) { ... });
    }
  }
});
Copy
Copied!

See the history documentation for further details of the supported query parameters.

Channels expose a presence member which a client can use to obtain present members and presence event history for the channel itself. See the REST presence documentation for details.

View the Messages API Reference.