Live Threads

reddit rolled out support for WebSocket-based event streams in the form of a "live thread" in 2014. These threads are typically dedicated to timely and newsworthy topics like natural disasters, big sporting events, or major political happenings (see /r/live for examples).

Creating a live thread requires the ability to create a subreddit. Generally, the user needs to have more than 100 karma. Once the user jumps this hurdle, creating a live thread is a simple process.

LiveThreadPatch initialSettings = new LiveThreadPatch.Builder()
    .description("a description of what's going on")
    .nsfw(false)
    .resources("some external links for viewers of the thread")
    .title("test thread")
    .build();

LiveThreadReference createdThread = redditClient.me()
    .createLiveThread(initialSettings);

If you want information about an existing thread, you can create a reference for it by its ID.

LiveThreadReference someLiveThread =
    redditClient.liveThread("<ID goes here>");

Sometimes reddit features a live thread for a particularly prominent event.

// If there's no featured thread, this will return null
LiveThread liveThread = redditClient.happeningNow();

if (liveThread != null) {
    LiveThreadReference reference = liveThread.toReference(redditClient);
    // do something with reference (probably read its updates)
}

Updates

A live thread consists of a stream of updates. Once an update is posted by an approved thread contributor, it is available to everyone.

BarebonesPaginator.Builder<LiveUpdate> paginatorBuilder = liveThreadReference.latestUpdates();
BarebonesPaginator<LiveUpdate> paginator = paginatorBuilder.limit(25).build();

// Fetch up to the last 25 updates
Listing<LiveUpdate> latestUpdates = paginator.next();

If Paginators are unfamiliar to you, make sure to check out the Pagination page.

We can update a live thread fairly easily.

liveThreadReference.postUpdate("Something just happened!");

If we find out that an update is incorrect or no longer applicable, we can strike it from the thread. The update will still appear on the thread, but it will have a strikethrough effect. If this isn't good enough, we can permanently remove the update from the thread.

// This update is incorrect, strike it
liveThreadReference.strikeUpdate(liveUpdate.getId());

// This update needs to be permanently removed from the thread
liveThreadReference.deleteUpdate(liveUpdate.getId());

Updates cannot be edited, if there's a typo the user has to either strike it or delete it and post a new update.

Once the contributors have decided that there's no more content to share about this event, it can be closed. After that, no further updates can be sent. This process is not reversible.

liveThreadReference.close();

WebSockets

As stated in the introduction, live threads are based on WebSockets. Instead of polling for updates with latestUpdates at a fixed interval, we can leverage WebSockets to let us know when something happens to the thread.

LiveThreadListener listener = new LiveThreadListener() {
    @Override
    public void onUpdate(@NotNull LiveWebSocketUpdate update) {
        // do something with the update
    }
};

// Open a connection to the live thread's WebSocket and react to updates with listener
ReadOnlyWebSocketHelper webSocketHelper = liveThreadReference.liveUpdates(listener);

// When we don't want to listen to any more updates, make sure to close the connection
webSocketHelper.close(ReadOnlyWebSocketHelper.CLOSE_CODE_DEFAULT);