How to send a Heartbeat via HTTP Tracking API

Hi all!

I am developing an open-source tool to send realtime data from Icecast and Shoutcast to Matomo. I would like to track when a user connects to a stream until he disconnects in realtime (users usually spend hours listening to a stream).

I think this could be achieved doing something similar to the Heartbeat that the JS Tracking client provides: JavaScript Tracking Client: Integrate - Matomo Analytics (formerly Piwik Analytics) - Developer Docs - v3

I have not been able to find that function on the HTTP Tracking API, how can I achieve that?

Basically I want to track this:

  • User connects to a stream /myradio.mp3 -> Add user to Matomo
  • User is still connected -> Send heartbeat to Matomo
  • [ repeat while user is connected ]
  • User stop listening to the stream -> End session in Matomo

I also haven’t figured out how to mark an user as disconnected instantly. Seems like Matomo mark a user as disconnected after the “visit_standard_length” timeout is over: How is a ‘visit’ defined in Piwik? - Analytics Platform - Matomo Is there a way to actively mark a user as disconnected/session has finished so I don’t need to wait for the timeout?

Every help will be appreciated. I haven’t found any tool that covers realtime analytics for streaming servers, and I think this would be a nice addition to the open source world.


Good news, the ping parameter is finally documented here:

Amazing! Thanks.

I think there is no way to actively end a user session, so I think I will setup a short “visit_standard_length” and send a ping for every online user a little before the session times out.

1 Like

Hi @Lukas,

I have tried using that parameter, and I think I am not getting the described behaviour.

I have setup the visit length as 60 seconds:

visit_standard_length = 60

And, after the first visit, I keep sending a heartbeat every 10 seconds (the same request but with ping=1).
It works great during 60 seconds, as the visit time increases, and the user is shown on the “Real time visitor Count” and the “Real time map”, so far so good, but after the “visit_standard_length” passes (60 seconds), the user disappears from those widgets, and marked visit finished.

I understand that this shouldn’t happen with ping=1, instead, the user should be kept online and the session time running as long as I keep sending those events, right?

Please, find here [JSON] matomo_logs - the logs returned from the tracking API, together with the payload that I am sending to matomo.

You can see how before the 60s the tracking API returns:

DEBUG: Visit is known (IP =
DEBUG: Updated existing visit: array (
DEBUG:   'idvisitor' => '0000000000030854',
DEBUG:   'visit_total_time' => 52,

and after that:

DEBUG: The visitor was not matched with an existing visitor...


This is currently expected behaviour see Fix total time of visit is not the sum of times of page visits if heartbeat feature is used by tsteur · Pull Request #9617 · matomo-org/matomo · GitHub

The ping is not there to extend the visit, only to report more accurate visit length time, especially when there is only one page view in a visit.

It would need basically a new option to keep the visit active as well.

1 Like

Thanks for the answer @thomas_matomo, I guess I didn’t understand what ping does.

Then, I don’t see a way of being able to define a user visit length accurately, or am I missing something?

I’m not quite sure what you are trying to achieve. Can you set visit_standard_length for example to an hour or longer and then the visit length would be more accurate maybe?

I agree with @xipher and I have the same concern. Ping is enabled, but visits don’t get counted past their default lifetime. I think this behavior should be modified. Do you agree? It would better match the counters on Chartbeat and Google Analytics, which keep counting a visitor as long as the page is open.