The TwentyThree API supports realtime data consumption in a number of different cases. For example your client can subscribe to realtime notifications and information when live analytics updates, when news comments are added, or when a user interacts with a video.

Bayeaux

The realtime scheme centres around the Bayeaux protocol. Bayeaux is a web standard built to send and deliver of asynchronous messages between a web server and a web client, most often af browser. The protocol supports a number of different transports for the communication, for example web sockets or long polling. This means that realtime communication will be supported (in different ways) on virtually every browser.

In order to use the realtime API, you should familiarize yourself with how the protocol runs connections, handshakes, pushes and more -- but in general your client will subscribe to one or more realtime channels, and as events occur elsewhere the client is notified with relevant information in the form of a JSON payload.

We strongly recommend using Faye and the Faye browser client to handle realtime subscriptions.

Communicating with the TwentyThree realtime API

All realtime communication is run from //realtime.23video.com, and you must architect your application to works gracefully even when the service isn't available on this address. Realtime information from any service and for any given object is published to a signed root channel with a sub-channel denoting the contents of the channel for the object. For example, all realtime updates to comment on a video might be sent to /0dda8.../all_json while the channel /0dda8.../promoted_json only receives events for promoted commons.

Using Faye, subscription data can be received like this in the browser

<script>
  var client = new Faye.Client('//realtime.23video.com/faye');
  client.subscribe('/0dda8.../all_json', function(commentData) {
    doStuffWithComment(commentData);
  });
</script>

The signed root channel is available through the REST API on the individual objects. For example, /api/live/log lists the realtime_channel used to subscribe to all events surrounding the publishing and recording of a live video stream.

Data is pushed to clients with JSON payloads.

Catch-up to real time

By default, realtime data will allow you to be notified about events that happens after the client starts subscribing to updates, but in certain cases it can be very convenient to have the realtime client load recent data as well -- for example, to show live analytics from the past 30 minutes and then be further notified about updates as a part of same process. For this reason, certain services such as realtime analytics for live and on-demand video supports catch-up by subscribing to a secondary channel.

The name of the secondary channel follows this pattern: <base_channel>/catchup/<interval>. The interval is a count followed by a unit (either h for hour, m for minute or sfor seconds), eg. 12h for 12 hours.

So if you want to catch up for the last 6 hours for the channel /0dda8.../all_json you subscribe to /0dda8.../all_json/catchup/6h.

In Faye, this can be done like this:

<script>
  var client = new Faye.Client('//realtime.23video.com/faye');
  client.subscribe(['/1234abcd.../all_json', '/1234abcd.../all_json/catchup/12h'], function(analyticsData) {
    doStuffWithAnalytics(analyticsData);
  });
</script>

This is turn will have relevant messages with data from the past pushed to the subscription. You should note that this data is only pushed to the extent that it is available and isn't guarenteed to come in in chronological order. Also, different services and objects types support different catch-up intervals if at all.

Realtime service: Comments

Comment updates are pushed through the signed object channel for a live event or a video, and the channel is available with the realtime_channel property in /api/photo/list and /api/live/list.

Real-time data for comments is published in four channels:

• /<signed root for object>/all_json: All comments added to the specified object (usually a video or a live event) with all relevant meta data for the comment in the payload.
• /<signed root for object>/promoted_json: A comment has been added as protomoted, or a previous comment has been promoted. All relevant meta data for the comment is included in the payload.
• /<signed root for object>/all_html: All the same comments as with the all_json channel above, but the JSON payload includes an html property with a full pre-rendered HTML version of the comment.
• /<signed root for object>/promoted_html: A comment has been added as protomoted, or a previous comment has been promoted. Payload includes an html property with pre-rendered comment.

This service doesn't support catch-up.

Realtime service: Live stream events

When a live event's status or meta data changes certain information is pushed through in real time. The signed channel name is available with admin permissions through the  /api/live/realtime API endpoint.

Available channels are:

• /<signed root for live>/updates: The meta data for the live event, for example the title or descriptions has been changed. The payload includes only a live_id property.
• /<signed root for live>/events: Streaming, broadcasting or recording has started or stopped on the live stream. Attributes include live_id, timestamp, event (possible values are streaming, recording, broadcasting) and tyoe (possible values are start and stop).

This service doesn't support catch-up.

Realtime service: Live analytics

This service doesn't supprt catch-up.