This add-on is operated by Ably

Simply better realtime for any enabled device

Last updated October 02, 2023

Ably Ably is a realtime data delivery platform.

We provide the infrastructure, services and support to make it easy for you to add realtime experiences to your apps, websites and any other internet connected device. Ably is architected to be reliable. So reliable, in fact, that we offer a 100% data delivery guarantee.

Customers use Ably to provide limitless scale and global performance for their realtime chat, games, live streaming, betting and financial apps. See examples of Ably in use.

Provisioning the Heroku add-on

Ably can be attached to a Heroku application via the Dashboard, or the CLI:

$ heroku addons:create ably:bootstrap

Once Ably has been added, the ABLY_API_KEY setting will be available in the app configuration. Find out more about Ably API keys. This can be confirmed using the heroku config:get command.

$ heroku config:get ABLY_API_KEY
6pdNVA.p11x45:SeTwcAAP4EC7wIi

After installing Ably the application should be configured to fully integrate with the add-on.

Accessing your Ably dashboard

From within your Ably dashboard, you can view and access your live statistics, set up and manage API keys, configure channel rules and webhooks, and use the Ably developer console.

The dashboard can be accessed via the CLI:

$ heroku addons:open ably
Opening ably for sharp-mountain-4005

or by visiting the Heroku Dashboard and selecting the application in question. Select Ably from the Add-ons menu.

You will then be taken to your app dashboard

Using the Ably JavaScript (browser or Node.js) client library

For node.js

Installation from npm

$ npm install ably

Usage

For the realtime library:

var realtime = require('ably').Realtime;

For the rest-only library:

var rest = require('ably').Rest;

For browsers

Include the Ably library in your HTML:

<script src="https://cdn.ably.io/lib/ably.min-1.js"></script>

For the realtime library:

var realtime = Ably.Realtime;

For the rest-only library:

var rest = Ably.Rest;

JavaScript example

This example demonstrates a straightforward way to publish and receive a message on a channel. See the Ably Realtime client library documentation for complete usage.

var apiKey = process.env['ABLY_API_KEY'];
/* API key available in Heroku Node.js, we recommend token auth in the browser */
var client = new Ably.Realtime({ key: apiKey });
var channel = client.channels.get('test');
channel.subscribe(function(message) {
  message.name // 'greeting'
  message.data // 'Hello World!'
});
channel.publish('greeting', 'Hello World!');

Using the Ably Ruby client library

The client library is available as a gem from RubyGems.org.

Add this line to your application’s Gemfile:

gem 'ably'

And then install this Bundler dependency:

$ bundle

Or install it yourself as:

$ gem install ably

Ruby Realtime API example

This example, which runs under the asynchronous evented EventMachine library, demonstrates a straightforward way to publish and receive a message on a channel. See the Ably Realtime client library documentation for complete usage.

EventMachine.run do
  client = Ably::Realtime.new(key: ENV['ABLY_API_KEY'])
  channel = client.channels.get('test')
  channel.subscribe do |message|
    message.name #=> "greeting"
    message.data #=> "Hello World!"
  end
  channel.publish('greeting', 'Hello World!')
end

Ruby REST API example

This example demonstrates a straightforward way to publish a message over REST on a channel. See the Ably REST client library documentation for complete usage.

client = Ably::Rest.new(key: ENV['ABLY_API_KEY'])
channel = client.channels.get('test')
channel.publish('greeting', 'Hello World!')

Using the Ably PHP REST client library

The client library is available as a composer package on packagist. Install composer if you don’t have it.

Install Ably from the shell with:

$ composer require ably/ably-php --update-no-dev

Omit the --update-no-dev parameter, if you want to run tests. Then simply require composer’s autoloader:

require_once __DIR__ . '/../vendor/autoload.php';

PHP REST API example

This example demonstrates a straightforward way to publish a message over REST on a channel. See the Ably REST client library documentation for complete usage.

$client = new Ably\AblyRest($_ENV["ABLY_API_KEY"]);
$channel = $client->channel('test');
$channel->publish('myEvent', 'Hello!');
``
channel.publish('greeting', 'Hello World!')

Using the Ably Python REST client library

The client library is available as a PyPI package.

Installing From PyPI

$ pip install ably

Installing Locally

$ git clone https://github.com/ably/ably-python.git
$ cd ably-python
$ python setup.py install

Python REST API example

This example demonstrates a straightforward way to publish a message over REST on a channel. See the Ably REST client library documentation for complete usage.

from ably import AblyRest
client = AblyRest(os.environ['ABLY_API_KEY'])
channel = client.channels.get('channel_name')
channel.publish('event', 'message')

Using the Ably Java client library

The Realtime library for Java is downloadable as a JAR at our GitHub releases page. You can either download the full JAR which includes all dependencies, or just the library but it will be your responsibility to ensure all dependencies are met. Please see the GitHub repo for the latest installation instructions.

Java Realtime example

This example demonstrates a straightforward way to publish and receive a message on a channel. See the Ably Realtime client library documentation for complete usage.

String apiKey = System.getenv("ABLY_API_KEY");
AblyRealtime ably = new AblyRealtime(apiKey);
Channel channel = ably.channels.get("test");
channel.subscribe(new MessageListener() {
    @Override
    public void onMessage(Message[] messages) {
    for(Message message : messages) {
            System.out.println("Received `" + message.name + "` message with data: " + message.data);
        }
    }
});
channel.publish("greeting", "Hello World!");

Java REST API example

This example demonstrates a straightforward way to publish a message over REST on a channel. See the Ably REST client library documentation for complete usage.

String apiKey = System.getenv("ABLY_API_KEY");
AblyRest ably = new AblyRest(apiKey);
Channel channel = ably.channels.get("test");
channel.publish("event", "message");

Support

We have a host of engineers available to help you if have any questions or problems. Visit the Ably support site that includes live chat.

We also have a host of documentation and examples available:

• Quickstart guide
• Examples
• How Ably works
• Realtime library documentation
• REST library documentation
• Authentication explained

If you believe there is a disruption or problem with the service, visit the Ably status site.

Next steps

Ably provides a straightforward API to publish and receive messages on channels over WebSockets. However, our feature set is much broader than simply pub/sub providing access to Mobile and browser push notifications, Presence and device status, Message history, End-to-End Encryption, Statistics, WebHooks and a rich authentication system.

We recommend you read the documentation or get in touch with our team if you have any questions.

Removing the Ably add-on

Ably can be removed via the CLI:

$ heroku addons:destroy ably
Destroying ably-adjacent-53647 on test-ably-addon... done, (free)