Mastodon::Listener - Access the streaming API of a Mastodon server


  # From Mastodon::Client
  my $listener = $client->stream( 'public' );

  # Or use it directly
  my $listener = Mastodon::Listener->new(
    url => '',
    access_token => $token,
    coerce_entities => 1,

  $listener->on( update => sub {
    my ($listener, $status) = @_;
    printf "%s said: %s\n",



A Mastodon::Listener object is created by calling the stream method from a Mastodon::Client, and it exists for the sole purpose of parsing a stream of events from a Mastodon server.

Mastodon::Listener objects inherit from Role::EventEmitter. Please refer to its documentation for details on how to register callbacks for the different events.

Once callbacks have been registered, the listener can be set in motion by calling its start method, which takes no arguments and never returns. The stop method can be called from within callbacks to disconnect from the stream.



The OAuth2 access token of your application, if authorization is needed. This is not needed for streaming from public timelines.


The API version to use. Defaults to 1.


Whether JSON responses should be coerced into Mastodon::Entity objects. Currently defaults to false (but this will likely change in v0.01).


The instance to use, as a Mastodon::Entity::Instance object. Will be coerced from a URL, and defaults to


The stream to use. Current valid streams are public, user, and tag timelines. To access a tag timeline, the argument to this value should begin with a hash character (#).


The full streaming URL to use. By default, it is constructed from the values in the instance, api_version, and stream attributes.



A new status has appeared. Callback will be called with the listener and the new status.


A new notification has appeared. Callback will be called with the listener and the new notification.


A status has been deleted. Callback will be called with the listener and the ID of the deleted status.


A new :thump has been received from the server. This is mostly for debugging purposes.


Inherited from Role::EventEmitter, will be emitted when an error was found. The callback will be called with a fatal flag, an error message, and any relevant data as a single third arghument.

If the error event is triggered in response to a 4xx or 5xx error, the data payload will be an array reference with the response and request objects as received from Net::Async::HTTP.


  • José Joaquín Atria <>


This software is copyright (c) 2017 by José Joaquín Atria.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.