Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document guild time outs #4075

Merged
merged 23 commits into from
Dec 20, 2021
Merged

Document guild time outs #4075

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
fc4ea37
Document `communication_disabled_until` on guild member object
Nov 9, 2021
bc423c8
Fix wording
Nov 9, 2021
5bea5ad
Fix punctuation
Nov 9, 2021
eba451f
Update docs/resources/Guild.md
Nov 11, 2021
dd7535e
Add modify payload for timeouts
Lulalaby Nov 12, 2021
033c612
Add Guild Member Update field
Lulalaby Nov 12, 2021
00fcb6f
Add disclaimer for 28 day limit
Nov 20, 2021
a425614
Fix wording, add permission
Lulalaby Dec 17, 2021
29da1cd
Fix permissions..?
Lulalaby Dec 17, 2021
a56422f
Merge branch 'master' into guild-time-out
Lulalaby Dec 17, 2021
53c7290
Update Permissions.md
Lulalaby Dec 17, 2021
05c57d2
Fix description of permission 1L<<40
Lulalaby Dec 17, 2021
497d2ce
Merge branch 'guild-time-out' of https://github.com/NurMarvin/discord…
Lulalaby Dec 17, 2021
1585f10
Update Permissions.md
Lulalaby Dec 18, 2021
2acfd85
chore: reference support article
Dec 20, 2021
be51418
Update docs/resources/Guild.md
Lulalaby Dec 20, 2021
6c934c1
chore: add `MODERATE_MEMBERS` to list of internal names with differen…
Dec 20, 2021
95e71b0
fix: punctuation
Dec 20, 2021
65bbb10
Update docs/resources/Guild.md
Lulalaby Dec 20, 2021
d363509
Update docs/topics/Gateway.md
Lulalaby Dec 20, 2021
8da728b
Update docs/resources/Guild.md
Lulalaby Dec 20, 2021
6ba9994
add apostrophe
typpo Dec 20, 2021
ff789a4
more apostrophes!!
typpo Dec 20, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 28 additions & 26 deletions docs/resources/Guild.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,18 +280,19 @@ A partial [guild](#DOCS_RESOURCES_GUILD/guild-object) object. Represents an Offl

###### Guild Member Structure

| Field | Type | Description |
| -------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| user? | [user](#DOCS_RESOURCES_USER/user-object) object | the user this guild member represents |
| nick? | ?string | this users guild nickname |
| avatar? | ?string | the member's [guild avatar hash](#DOCS_REFERENCE/image-formatting) |
| roles | array of snowflakes | array of [role](#DOCS_TOPICS_PERMISSIONS/role-object) object ids |
| joined_at | ISO8601 timestamp | when the user joined the guild |
| premium_since? | ?ISO8601 timestamp | when the user started [boosting](https://support.discord.com/hc/en-us/articles/360028038352-Server-Boosting-) the guild |
| deaf | boolean | whether the user is deafened in voice channels |
| 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 |
| Field | Type | Description |
| ----------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| user? | [user](#DOCS_RESOURCES_USER/user-object) object | the user this guild member represents |
| nick? | ?string | this user's guild nickname |
| avatar? | ?string | the member's [guild avatar hash](#DOCS_REFERENCE/image-formatting) |
| roles | array of snowflakes | array of [role](#DOCS_TOPICS_PERMISSIONS/role-object) object ids |
| joined_at | ISO8601 timestamp | when the user joined the guild |
| premium_since? | ?ISO8601 timestamp | when the user started [boosting](https://support.discord.com/hc/en-us/articles/360028038352-Server-Boosting-) the guild |
| deaf | boolean | whether the user is deafened in voice channels |
| 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 |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When can this property be missing?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems to be on every guild member object.
Had no case yet, where it was missing.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh this is a good point - @hemu is it optional?

Copy link
Contributor

@hemu hemu Dec 20, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should leave it as optional :)


> info
> The field `user` won't be included in the member object attached to `MESSAGE_CREATE` and `MESSAGE_UPDATE` gateway events.
Expand Down Expand Up @@ -757,7 +758,7 @@ For guilds with [Membership Screening](#DOCS_RESOURCES_GUILD/membership-screenin
| Field | Type | Description | Permission |
| ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------- |
| access_token | string | an oauth2 access token granted with the `guilds.join` to the bot's application for the user you want to add to the guild | |
| nick | string | value to set users nickname to | MANAGE_NICKNAMES |
| nick | string | value to set user's nickname to | MANAGE_NICKNAMES |
| roles | array of snowflakes | array of role ids the member is assigned | MANAGE_ROLES |
| mute | boolean | whether the user is muted in voice channels | MUTE_MEMBERS |
| deaf | boolean | whether the user is deafened in voice channels | DEAFEN_MEMBERS |
Expand All @@ -777,13 +778,14 @@ Modify attributes of a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object)

###### JSON Params

| Field | Type | Description | Permission |
| ---------- | ------------------- | ------------------------------------------------------------------------------------------------------ | ---------------- |
| nick | string | value to set users nickname to | MANAGE_NICKNAMES |
| roles | array of snowflakes | array of role ids the member is assigned | MANAGE_ROLES |
| mute | boolean | whether the user is muted in voice channels. Will throw a 400 if the user is not in a voice channel | MUTE_MEMBERS |
| deaf | boolean | whether the user is deafened in voice channels. Will throw a 400 if the user is not in a voice channel | DEAFEN_MEMBERS |
| channel_id | snowflake | id of channel to move user to (if they are connected to voice) | MOVE_MEMBERS |
| Field | Type | Description | Permission |
| ---------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| nick | string | value to set user's nickname to | MANAGE_NICKNAMES |
| roles | array of snowflakes | array of role ids the member is assigned | MANAGE_ROLES |
| mute | boolean | whether the user is muted in voice channels. Will throw a 400 if the user is not in a voice channel | MUTE_MEMBERS |
| deaf | boolean | whether the user is deafened in voice channels. Will throw a 400 if the user is not in a voice channel | DEAFEN_MEMBERS |
| channel_id | snowflake | id of channel to move user to (if they are connected to voice) | MOVE_MEMBERS |
| 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 (up to 28 days in the future), set to null to remove timeout | MODERATE_MEMBERS |

## Modify Current Member % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/members/@me

Expand All @@ -794,9 +796,9 @@ Modifies the current member in a guild. Returns a 200 with the updated member ob

###### JSON Params

| Field | Type | Description | Permission |
| ----- | ------- | ------------------------------ | --------------- |
| nick? | ?string | value to set users nickname to | CHANGE_NICKNAME |
| Field | Type | Description | Permission |
| ----- | ------- | ------------------------------- | --------------- |
| nick? | ?string | value to set user's nickname to | CHANGE_NICKNAME |

## Modify Current User Nick % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/members/@me/nick

Expand All @@ -810,9 +812,9 @@ Modifies the nickname of the current user in a guild. Returns a 200 with the nic

###### JSON Params

| Field | Type | Description | Permission |
| ----- | ------- | ------------------------------ | --------------- |
| nick? | ?string | value to set users nickname to | CHANGE_NICKNAME |
| Field | Type | Description | Permission |
| ----- | ------- | ------------------------------- | --------------- |
| nick? | ?string | value to set user's nickname to | CHANGE_NICKNAME |

## Add Guild Member Role % PUT /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/members/{user.id#DOCS_RESOURCES_USER/user-object}/roles/{role.id#DOCS_TOPICS_PERMISSIONS/role-object}

Expand Down
25 changes: 13 additions & 12 deletions docs/topics/Gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1010,18 +1010,19 @@ Sent when a guild member is updated. This will also fire when the user object of

###### Guild Member Update Event Fields

| Field | Type | Description |
|----------------|---------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| guild_id | snowflake | the id of the guild |
| roles | array of snowflakes | user role ids |
| user | a [user](#DOCS_RESOURCES_USER/user-object) object | the user |
| nick? | ?string | nickname of the user in the guild |
| avatar | ?string | the member's [guild avatar hash](#DOCS_REFERENCE/image-formatting)
| joined_at | ?ISO8601 timestamp | when the user joined the guild |
| premium_since? | ?ISO8601 timestamp | when the user starting [boosting](https://support.discord.com/hc/en-us/articles/360028038352-Server-Boosting-) the guild |
| deaf? | boolean | whether the user is deafened in voice channels |
| 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 |
| Field | Type | Description |
| ----------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| guild_id | snowflake | the id of the guild |
| roles | array of snowflakes | user role ids |
| user | a [user](#DOCS_RESOURCES_USER/user-object) object | the user |
| nick? | ?string | nickname of the user in the guild |
| avatar | ?string | the member's [guild avatar hash](#DOCS_REFERENCE/image-formatting) |
| joined_at | ?ISO8601 timestamp | when the user joined the guild |
| premium_since? | ?ISO8601 timestamp | when the user starting [boosting](https://support.discord.com/hc/en-us/articles/360028038352-Server-Boosting-) the guild |
| deaf? | boolean | whether the user is deafened in voice channels |
| 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 |
| 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 |

#### Guild Members Chunk

Expand Down
Loading