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
+85 −81
Merged

Document guild time outs #4075

Show file tree
Hide file tree
Changes from 6 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
40 changes: 21 additions & 19 deletions docs/resources/Guild.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,18 +278,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 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 |
| communication_disabled_until? | ?ISO8601 timestamp | timestamp of when the time out will be removed; until then, they cannot interact with the guild |
Copy link
Contributor

Choose a reason for hiding this comment

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

should we reword the description to something more like:

"when the user's timeout will expire and the user's interaction in the guild is re-enabled. null if the user is not timed out."

timeout / timed out / timing out was avoided internally to keep the fields more generic and b/c timeout is an overloaded term, but it could be clearer to use timeout / timed out terminology at least in the descriptions here where we have more context, for the sake of having easily understandable docs. What do you think?

(same note for descriptions in the rest of the PR too)

Copy link
Contributor

Choose a reason for hiding this comment

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

Done


> 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 @@ -774,13 +775,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 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 |
| communication_disabled_until | ?ISO8601 timestamp | how long the user can not interact with the guild; set to null to remove timeout | KICK_MEMBERS |
NurMarvin marked this conversation as resolved.
Show resolved Hide resolved

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

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 @@ -991,18 +991,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 | whether and how long the user can not interact with the guild |

#### Guild Members Chunk

Expand Down