Upcoming change for moderation APIs currently in open beta

Announcements
1

Since we released the moderation APIs in an open beta, it has been inspiring to observe how many developers have already tried out these endpoints and the use cases they support. The beta period allows us to make adjustments to confirm that we are providing reliable services and that the requests and responses are designed well for general availability. To that end, we have a few updates for the moderation APIs while they are still in beta. Please see the details below.

Removing bulk bans

The option to ban users in bulk will be removed tomorrow, December 16, 2021. During the beta testing period we determined that the batching model is not yet optimized for scalability, so we have made the decision to not provide this option until a more scalable solution is available. The documentation will be updated for this change to indicate that the data body parameter should include a single object with user_id and reason rather than an array of these objects. In other words, the format will follow:

{"data": {"user_id":"9876","reason":"no reason"}}

If an array is provided with the request, developers can expect to receive a “Bad Request” response when bulk support is removed.

Error message formatting for “Ban User” and “Unban User”

Due to the change above, error responses for ban user and unban user will utilize the same structure as other API endpoints. See the example below. This change will take place in tandem with the removal of bulk bans.

{
   "error": "Bad Request",
   "status": 400,
   "message": "user cannot be banned"
}

Allow custom values for “Update Chat Settings”

This change is already in production as it is not a breaking change. Instead of choosing from a fixed set of values for slow_mode_wait_time and follower_mode_duration, custom values can now be used beyond what was previously defined. The documentation will be updated to reflect this change and will include the valid ranges.

Thank you again for participating in the open beta for the moderation APIs. We appreciate the direct and indirect feedback that has been provided to continually improve this functionality.

3 Likes
2

Rather disappointing change - would’ve preferred to see a lowered bulk limit (e.g. 100 → 25 instead of 100 → 1)

Alternatively, with scalability being an issue, I would be happy with a bulk bans endpoint that doesn’t send a CLEARCHAT over irc (assuming tmi is the bottleneck) – so if people wanted message removal on ban they’d simply use the traditional command instead of helix

2 Likes
3

Well a message still has to be sent to hide the chat/inform the end user that got banned they are banned. So I don’t think the TMI CLEARCHAT’s are the issue here. It’s the “tell the user they got banned” I think.

1 Like
4

(post deleted by author)

5

On chat load, there’s a gql request to see if a user is banned. Since this occurs on load, I doubt this is the bottleneck at hand

If you’re referring to the real-time ban notification for the target user, yes, there is unofficial pubsub at play. Twitch should probably remove this for bulk bans (and simply send a NOTICE upon the target’s next sent chat message informing them of the ban)

6

While I prefered the old behaviour I understand the reasoning behind the change. It would have been nice if both ways of calling the API would be possible until the switch so I don’t have to wait for it to break until I can change to the new single user way.
Could you let us know when the change was pushed to prod so I don’t have to wait for users to complain?

1 Like
7

@prod I empathize with your reaction. As is evident by its inclusion in the beta, bulk requests is a feature that teams want to enable, but more work is needed to get this right.

@CommanderRoot I’ve inquired about timing. Given when the effort is scheduled to begin and the time needed to propagate to production, the change will likely take place around 2021-12-16T19:30:00Z.

2 Likes
8

While testing my changes to accommodate this change I noticed something undocumented.
I got HTTP 429 responses even while being within helix rate limits. It would be nice if this could be documented on the docs.

grafik
grafik696Ă—521 15 KB

grafik

9

This was being discussed; thanks for confirming it would be helpful to add!

10

I’d just like to clarify if it was decision to document this was the thing being discussed?

1 Like
11

Yes, the discussion was in regards to documenting that a 429 could occur even within the normal Twitch API rate limits specifically for the Ban User endpoint. A note regarding this was added to the description for the 429 response on December 16.