New Chatters API endpoint now available in open beta

Loyalty systems, moderation, safety, giveaways, and in-stream games. These are just a few genres of third-party applications that creators have adopted to make their community special. All these applications have one common aspect that makes their success a lot easier to achieve; they all need to know who’s in Twitch Chat. To further drive the innovation of these use cases, we are launching an official Twitch API endpoint to obtain the list of chatters for a given Twitch broadcaster.

What’s new?

Get Chat Chatters — Gets the list of users that are connected to the specified broadcaster’s chat session.

moderator:read:chatters – A new authentication scope to obtain the list of users connected to a chat session.

What else should I know?

To request a chatters list, the authenticated token must belong to the broadcaster themselves or any of their moderators, and include the moderator:read:chatters scope.

If the authentication token is used on behalf of a broadcaster, then you would set both the broadcaster_id and the moderation_id to the same value. In any case, the moderator_id must match the user_id associated with the authentication token.

Regarding pagination, the number of objects returned per page by default is 100 and the maximum you can request per page is 1000. Providing these higher paging numbers will help creators and their developers use this information when a broadcast has a large audience.

What about…you know…that other endpoint?

It is no secret that third-party developers have been aware of an unsupported and undocumented endpoint to retrieve a list of users in chat. In full transparency, we do intend to withdraw the “TMI chatters” endpoint in the future. However, we are not setting a decommission date until we have received feedback during this open beta period, made any necessary changes based on that feedback, and are ready to make an announcement for general availability. The open beta timeframe will depend on the amount of feedback and the actions or updates necessary. We will make sure to have a discussion publicly about a shutdown timeline for TMI chatters and provide ample time to migrate applications at that time.

Thank you

We are also excited to finally mark one of the most requested third-party developer features as completed (or at least partially released as we consider adding user_ids to the response during the beta period). Thanks to @TheElm for being the first reporter and all 200+ developers who have voted for this feature since.

We also want to thank the 72 developers who provided feedback for this endpoint in our last quarterly survey. Your answers help guide our product decisions and you might have already seen this coming because of the question! I may be biased, but I’d say getting hints (aka twitchdevLeeks) about product direction is a good reason to check out these surveys when you have the time.

UPDATE (2022-11-17): user_id and user_name have been added to the return payload for each user in the list.

10 Likes

Your Honor, I rest my case.

I can die in peace now.

2 Likes

Really happy to see this being added today.

There’s that joke “Is it my birthday?” Well yes, it was, Yesterday. So, thanks for this :smiley:

My only addendum that I’d like to see in the future is user_ids being added to this. Otherwise it’s still functionally identical to that other one. Not having to make secondary requests would be great, especially since the /chatters can return up to 1000 chatters- which can be another 10 requests (100 per user lookup).

However, Great work as always to the dev team.

3 Likes

It’s unfortunate that if you need role information, you have to call the API to get the list of chatters by name, then call the API again to get user IDs, then call the API a few more times to check if they’re a subscriber, a VIP, or a moderator. It’s nice to get a list of 1000 users from the API, but less nice that you then have to funnel that through other APIs that are capped at 100 and only tell you one possible role. The website of course has this info available to anyone, permissions or not, so…

Thankfully for my bot, what I need is the chatter count, and a list of all chatters that aren’t the broadcaster (for a raffle-style command); the former is trivially a part of the API response, and I can get the latter by just filtering out the broadcaster in the new response (rather than the old “API” response splitting things out).

But, I’m a little worried for something like Chatty, which displays the user list and shows user info; hopefully all of that is available by JOIN/PART/ROOMSTATE or similar over IRC and won’t eventually go away either…

I’m glad that this feature got an official endpoint by why make it need a broadcaster or moderator token? The viewerlist is something anyone can use in the web app, regardless if they are logged in or not.

no it changed recently to:

image

So an incomplete list is in the Web App

This was touched on during todays TwitchDev stream. So best to rewatch that

1 Like

Hello Hello,

What happy news when I saw this ad! After all this time we finally have a great route to list viewers!

Except that… It’s not as good as the TMI system. And for a very simple and basic reason : You imposed pagination.

It is inconceivable for me as a developer to base my “watchtime” or “loyalties” system on a system that requires me to paginate 1,000 by 1,000 on streams that have TENS OF THOUSANDS of viewers. Which is the case most of the time. I will have to interest dozens of calls to twitch regularly ??? By taking the risk that no request in the loop fails.

In the same logic, we have systems that use, and indeed your APIs often require it, the user’s ID. which is not on display here. So if I want to track a user who has changed his login, it’s not possible (Again for a loyalty system) If we want to resolve user IDs we have to do DOUBLE the number of query, one per user ?

What the whole community wants is a result close to TMI, therefore a complete list of viewers (Or with much larger pagination so as not to overwhelm Twitch with requests which, on top of that, draw on our Rate Limit) I don’t really see the point of having to fetch information ourselves with a thousand requests when you already have it…

2 Likes

I totally agree. For example we would like to get chatters periodically every 5minutes to track engagement and retention of the users. For big streams (40k+) this means 40+ requests. Not mentioning other calls we have to do. Before it was just one call (although the accuracy wasn’t the best, that’s true). Bigger pages would solve this. Also we lost the information about VIPs, mods, etc. If we want that, the need to call GetUsers with 100max page is impossible periodically.

VIPs/mods isn’t found on the GetUsers endpoint.

And each can be loaded in one call to Get Mods/Get VIPS which yes (at time of writing) needs a broadcaster token. So to split out into groups. You need additional calls.

But VIPS/Mods don’t change that often so you can precache those.

In the case of Mods you can use EventSub to keep up with Mod add/remove (VIPs doesn’t have an eventsub but I just made a uservoice to request it Topic Notify when VIPs are added/removed – Twitch UserVoice)

1 Like

40 requests every 5 minutes is a very small number of requests, and only a small number of channels on Twitch reach that size (and even then it’s usually only for hours, not 24/7), and only a smaller subset of those would great you the scopes to access their chatters list in the first place, so compared to the rate limit the number of requests is not significant.

Different endpoints, different scopes. A broadcaster may grant your app access to see their chatters list but they may not want you to be able to access their mod list. These changes have given broadcasters more granular control over what data they give apps access to.

Glad to see this update! Actually, both user_id and user_login in the payload would be perfect. But if you choose between them, user_id is preferred, IMO.

Will this affect the normal users? I.e, will users still be able to click on the chatroom to see who is there?

or is this information exclusive to the broadcaster and moderators now?

1 Like

No changes have been announced to the first party product, that I am aware of

A follow-up to this announcement; user_id and user_name are now included in each user object as of today.

7 Likes

I wish it was public as was the TMI endpoint. I try to build a cartography of communities overlaps, basically to determine which communities blend together, what are their relationship and common interests, how does it affect their viewerships compared to communities that have little to none overlapping.

Basically analysis of data, that I then model into a graph, which I then share. Which now will be impossible because I could not possibly get the thousands of creators’ agreement to get the moderator:read:chatters permission, it would in itself be a full-time job.

I watched part related to new Chatters endpoint in the TwitchDev stream from 29th of September but I couldn’t find a reason why this data would now be locked behind a new authentification scope.
I also am wondering if you plan on creating a new API key that would require an application to obtain, that would specifically allow for such API requests ?

Thanks

GDPR and/or other privacy laws is my speculation.

Additionally you would be tracking people without their consent and using that data in a way thats “not an acceptable use case”.

GDPR and other privacy laws again here.

What about an endpoint to retrieve the chatters ID that would previously get anonymized based on the API Key of the caller ? That would solve the problem.

I guess an issue would be the meaningfulness of such endpoint. If it’s used by 3 people would it have been worth it to develop, I guess no. However I personally think it would be a good thing for people who want to propose data analysis.

if you are operating on a channel you have permission to operate on then you would have the necassary scoped token.

I suppose what you describe is similar to the opaque_id that extensions have, so if you have a valid use case for this, you need a uservoice.

All the channels I run bots on utilise this endpoint…

Data analysis is a whole different ball game and may requrie permission from Twitch to exist, please refer to the developer TOS

1 Like

If you want to get the data, get the appropriate permissions for it.

If they were to anonymize the data for channels you don’t have the scopes for then there’s the issue that a developer could use the channels they do have the scopes for as a key to translate some of those anonymized ID’s into user ID’s and see what channels they’re on.

Additionally, the sort of thing you’re looking to do may fall under Research, or Marketing, which would require entering in to a separate agreement with Twitch anyway, and if they wish to support such things they may have other options for you.

1 Like

I just read the TOS and you’re right they say for educational and non-commercial projects that examine trends over specific time periods, that we can enter into an agreement for the use of their API. I’m going to e-mail them about it, as you say maybe they will have other options.

Hope it’ll work out !
Thanks to you and Barry for your answers btw