Document guild time outs #4075
Document guild time outs #4075
Conversation
|
Yeah, a few users already reported that they played with it and can't remove it anymore 😅 |
Co-authored-by: Jake Ward <[email protected]>
Co-authored-by: Vitor <[email protected]>
msciotti
added
the
not released
There was a problem hiding this comment.
Modify Guild Member needs to be updated too
(also, is it definitely optional?)
Co-authored-by: Josey Wörmann <[email protected]>
The needed permission is `KICK_MEMBERS`
Co-authored-by: Advaith <[email protected]>
|
Discord added a permission for managing guild time outs - I've never documented permissions, but I assume it should be documented as
|
The new permission seems to be named |
|
Free |
…t names in the client
Co-authored-by: Advaith <[email protected]>
Co-authored-by: Advaith <[email protected]>
| | mute | boolean | whether the user is muted in voice channels | | ||
| | pending? | boolean | whether the user has not yet passed the guild's [Membership Screening](#DOCS_RESOURCES_GUILD/membership-screening-object) requirements | | ||
| | permissions? | string | total permissions of the member in the channel, including overwrites, returned when in the interaction object | | ||
| | communication_disabled_until? | ?ISO8601 timestamp | when the user's [timeout](https://support.discord.com/hc/en-us/articles/4413305239191-Time-Out-FAQ) will expire and the user will be able to communicate in the guild again, null or a time in the past if the user is not timed out | |
There was a problem hiding this comment.
When can this property be missing?
There was a problem hiding this comment.
It seems to be on every guild member object.
Had no case yet, where it was missing.
There was a problem hiding this comment.
oh this is a good point - @hemu is it optional?
There was a problem hiding this comment.
ah to be honest the optionality of fields from the perspective of the public api is always a tricky question to answer definitively for me. b/c the objects we define in the docs are defined more for convenience, so they can be referred to from other places in the docs rather than something that always maps 1:1 to how we use models internally. I think the best answer I can give is when we serialize the guild member model, we currently always seem to include the communication_disabled_until field. But this still doesn't 100% guarantee it is always included unless we thoroughly check every single endpoint where this model is included in some way currently. And this could change in the future at any time. But I think that means we can remove the optional?
There was a problem hiding this comment.
since from a pure data model perspective communication_disabled_until isn't a core field for the member model like joined_at is, how about we leave it as optional just in case, since I'd imagine the opposite -- assuming it is required now and at some point in the future an endpoint whose document references this Guild Member Object in docs fails to include this field -- is a worse developer experience. What do you think?
There was a problem hiding this comment.
We should leave it as optional :)
Co-authored-by: Advaith <[email protected]>
Co-authored-by: Advaith <[email protected]>
|
also, is this field supported in the Add Guild Member endpoint? |
|
Could the permissions section be updated to explain how being timed out affects the permissions? Such as, which permissions it disables. |
The hesitation here is that in the future if another action is introduced and gated by the MODERATE_MEMBERS perm, then we'd have to introduce api / docs churn for all devs to keep it consistent. But changing the client facing description to accommodate the additional action is less impactful |
great idea, I can add this as a followup |
not currently. would the use case be to add a member that is already timed out initially? |
Wouldn't this overlap with the features of membership screening? |
|
I was just asking to make sure it wasn't being missed in the docs, I don't have a use case |
|
alright going to merge this in and deploy at this point so we can make these core parts available -- can save improvements for follow up PR's at this point. Big thank you to everyone who contributed!! 🙂 |
Discord API PR (initial documentation): discord/discord-api-docs#4075 Discord API PR (further documentation): discord/discord-api-docs#4266
night
removed
the
not released
This PR adds documentation for guild time outs, which currently mainly only consist of the
communication_disabled_untilfield on guild member objects. Since this field has been showing up on guild member objects for quite some time now and the field getting functionality on the API-side, I feel like it's at least worth creating a draft PR mentioning this field, since this can affect bots on servers where this gets tested. For example, someone could be time outing the bot and the bot would be getting errors regarding "Missing Permissions" with the bot owner possibly being puzzled as to why this happens despite checking for permissions etc.I know this information is technically just data-mined but due to the aforementioned reasons I felt like still creating at least draft PR.