From 61e106c96a28d5b372ef15feac9ab6833269e35d Mon Sep 17 00:00:00 2001 From: Shay Date: Mon, 9 Jan 2023 11:41:58 -0800 Subject: [PATCH 1/5] Add thread member pagination and details changes --- docs/Change_Log.md | 15 +++++++++++++++ docs/resources/Channel.md | 36 +++++++++++++++++++++++++++++------- 2 files changed, 44 insertions(+), 7 deletions(-) diff --git a/docs/Change_Log.md b/docs/Change_Log.md index b86fb35ff3..a9891a4331 100644 --- a/docs/Change_Log.md +++ b/docs/Change_Log.md @@ -1,5 +1,20 @@ # Change Log +## Thread Member Details and Pagination + +> danger +> This entry includes breaking changes + +#### Jan 09, 2023 + +A new `member` field was added to the [thread member object](#DOCS_RESOURCES_CHANNEL/thread-member-object). `member` is a [guild member object](#DOCS_RESOURCES_GUILD/guild-member-object) that will be included within returned thread member objects when the new `with_member` field is set to `true` in the [List Thread Members](#DOCS_RESOURCES_CHANNEL/list-thread-members) (`GET /channels//thread-members`) and [Get Thread Member](#DOCS_RESOURCES_CHANNEL/get-thread-member) (`GET /channels//thread-members/`) endpoints. + +Setting `with_member` to `true` will also make enable pagination for the [List Thread Members](#DOCS_RESOURCES_CHANNEL/list-thread-members) endpoint. When the results are paginated, you can use the new `after` and `limit` fields to fetch additional thread members and limit the number of thread members returned. By default, `limit` is 100. + +#### Upcoming Changes + +Starting in API v11, [List Thread Members](#DOCS_RESOURCES_CHANNEL/list-thread-members) (`GET /channels//thread-members`) will *always* return paginated results, regardless of whether `with_member` is passed or not. + ## Add Default Layout setting for Forum channels #### Dec 13, 2022 diff --git a/docs/resources/Channel.md b/docs/resources/Channel.md index 0c9c19c5b8..a6a73d26e6 100644 --- a/docs/resources/Channel.md +++ b/docs/resources/Channel.md @@ -559,16 +559,17 @@ The thread metadata object contains a number of thread-specific channel fields t ### Thread Member Object -A thread member is used to indicate whether a user has joined a thread or not. +A thread member object contains information about a user that has joined a thread. ###### Thread Member Structure -| Field | Type | Description | -| -------------- | ----------------- | --------------------------------------------------------------- | -| id? \* | snowflake | the id of the thread | -| user_id? \* | snowflake | the id of the user | -| join_timestamp | ISO8601 timestamp | the time the current user last joined the thread | -| flags | integer | any user-thread settings, currently only used for notifications | +| Field | Type | Description | +| -------------- | ----------------------------------------------------------- | --------------------------------------------------------------- | +| id? \* | snowflake | ID of the thread | +| user_id? \* | snowflake | ID of the user | +| join_timestamp | ISO8601 timestamp | Time the user last joined the thread | +| flags | integer | Any user-thread settings, currently only used for notifications | +| member? \* | [guild member](#RESOURCES_GUILD/guild-member-object) object | Additional information about the user | **\* These fields are omitted on the member sent within each thread in the [GUILD_CREATE](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) event** @@ -1302,13 +1303,34 @@ Removes another member from a thread. Requires the `MANAGE_THREADS` permission, Returns a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object for the specified user if they are a member of the thread, returns a 404 response otherwise. +When `with_member` is set to `true`, the thread member object will include a `member` field containing a [guild member](#RESOURCES_GUILD/guild-member-object) object. + +###### Query String Params + +| Field | Type | Description | +| ------------ | --------- | ------------------------------------------------------------------------------------------------------ | +| with_member? | boolean | Whether to include a [guild member](#RESOURCES_GUILD/guild-member-object) object for the thread member | + ## List Thread Members % GET /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/thread-members +> warn +> Starting in API v11, this endpoint will always return paginated results. Paginated results can be enabled before API v11 by setting `with_member` to `true`. Read [the changelog](#DOCS_CHANGE_LOG/thread-member-details-and-pagination) for details. + Returns array of [thread members](#DOCS_RESOURCES_CHANNEL/thread-member-object) objects that are members of the thread. +When `with_member` is set to `true`, the results will be paginated and each thread member object will include a `member` field containing a [guild member](#RESOURCES_GUILD/guild-member-object) object. + > warn > This endpoint is restricted according to whether the `GUILD_MEMBERS` [Privileged Intent](#DOCS_TOPICS_GATEWAY/privileged-intents) is enabled for your application. +###### Query String Params + +| Field | Type | Description | +| ------------ | --------- | ------------------------------------------------------------------------------------------------------- | +| with_member? | boolean | Whether to include a [guild member](#RESOURCES_GUILD/guild-member-object) object for each thread member | +| after? | snowflake | Get thread members after this user ID | +| limit? | integer | Max number of thread members to return (1-100). Defaults to 100. | + ## List Public Archived Threads % GET /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/threads/archived/public Returns archived threads in the channel that are public. When called on a `GUILD_TEXT` channel, returns threads of [type](#DOCS_RESOURCES_CHANNEL/channel-object-channel-types) `PUBLIC_THREAD`. When called on a `GUILD_ANNOUNCEMENT` channel returns threads of [type](#DOCS_RESOURCES_CHANNEL/channel-object-channel-types) `ANNOUNCEMENT_THREAD`. Threads are ordered by `archive_timestamp`, in descending order. Requires the `READ_MESSAGE_HISTORY` permission. From 1d4b74f3127f64d773ae8e1940c748bc6c7f3047 Mon Sep 17 00:00:00 2001 From: Shay Date: Mon, 9 Jan 2023 11:45:34 -0800 Subject: [PATCH 2/5] broken links --- docs/resources/Channel.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/resources/Channel.md b/docs/resources/Channel.md index a6a73d26e6..469522b024 100644 --- a/docs/resources/Channel.md +++ b/docs/resources/Channel.md @@ -569,7 +569,7 @@ A thread member object contains information about a user that has joined a threa | user_id? \* | snowflake | ID of the user | | join_timestamp | ISO8601 timestamp | Time the user last joined the thread | | flags | integer | Any user-thread settings, currently only used for notifications | -| member? \* | [guild member](#RESOURCES_GUILD/guild-member-object) object | Additional information about the user | +| member? \* | [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object | Additional information about the user | **\* These fields are omitted on the member sent within each thread in the [GUILD_CREATE](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) event** @@ -1303,13 +1303,13 @@ Removes another member from a thread. Requires the `MANAGE_THREADS` permission, Returns a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object for the specified user if they are a member of the thread, returns a 404 response otherwise. -When `with_member` is set to `true`, the thread member object will include a `member` field containing a [guild member](#RESOURCES_GUILD/guild-member-object) object. +When `with_member` is set to `true`, the thread member object will include a `member` field containing a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object. ###### Query String Params | Field | Type | Description | | ------------ | --------- | ------------------------------------------------------------------------------------------------------ | -| with_member? | boolean | Whether to include a [guild member](#RESOURCES_GUILD/guild-member-object) object for the thread member | +| with_member? | boolean | Whether to include a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object for the thread member | ## List Thread Members % GET /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/thread-members @@ -1318,7 +1318,7 @@ When `with_member` is set to `true`, the thread member object will include a `me Returns array of [thread members](#DOCS_RESOURCES_CHANNEL/thread-member-object) objects that are members of the thread. -When `with_member` is set to `true`, the results will be paginated and each thread member object will include a `member` field containing a [guild member](#RESOURCES_GUILD/guild-member-object) object. +When `with_member` is set to `true`, the results will be paginated and each thread member object will include a `member` field containing a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object. > warn > This endpoint is restricted according to whether the `GUILD_MEMBERS` [Privileged Intent](#DOCS_TOPICS_GATEWAY/privileged-intents) is enabled for your application. @@ -1327,7 +1327,7 @@ When `with_member` is set to `true`, the results will be paginated and each thre | Field | Type | Description | | ------------ | --------- | ------------------------------------------------------------------------------------------------------- | -| with_member? | boolean | Whether to include a [guild member](#RESOURCES_GUILD/guild-member-object) object for each thread member | +| with_member? | boolean | Whether to include a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object for each thread member | | after? | snowflake | Get thread members after this user ID | | limit? | integer | Max number of thread members to return (1-100). Defaults to 100. | From e82d13a555a0d4fe04128efe7d1cd2fe48595fa0 Mon Sep 17 00:00:00 2001 From: Shay Date: Mon, 9 Jan 2023 12:29:06 -0800 Subject: [PATCH 3/5] add note to table about member field --- docs/resources/Channel.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/resources/Channel.md b/docs/resources/Channel.md index 469522b024..f8f218136d 100644 --- a/docs/resources/Channel.md +++ b/docs/resources/Channel.md @@ -563,15 +563,17 @@ A thread member object contains information about a user that has joined a threa ###### Thread Member Structure -| Field | Type | Description | -| -------------- | ----------------------------------------------------------- | --------------------------------------------------------------- | -| id? \* | snowflake | ID of the thread | -| user_id? \* | snowflake | ID of the user | -| join_timestamp | ISO8601 timestamp | Time the user last joined the thread | -| flags | integer | Any user-thread settings, currently only used for notifications | -| member? \* | [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object | Additional information about the user | - -**\* These fields are omitted on the member sent within each thread in the [GUILD_CREATE](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) event** +| Field | Type | Description | +| --------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- | +| id? \* | snowflake | ID of the thread | +| user_id? \* | snowflake | ID of the user | +| join_timestamp | ISO8601 timestamp | Time the user last joined the thread | +| flags | integer | Any user-thread settings, currently only used for notifications | +| member? \* \*\* | [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object | Additional information about the user | + +\* These fields are omitted on the member sent within each thread in the [GUILD_CREATE](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) event. + +\*\* The `member` field is only present when `with_member` is set to `true` when calling [List Thread Members](#DOCS_RESOURCES_CHANNEL/list-thread-members) or [Get Thread Member](#DOCS_RESOURCES_CHANNEL/get-thread-member). ### Default Reaction Object From ab99a08a1e982ecd7468265c4a51f7aefb873d45 Mon Sep 17 00:00:00 2001 From: Shay Date: Mon, 9 Jan 2023 12:35:28 -0800 Subject: [PATCH 4/5] formatting --- docs/resources/Channel.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/resources/Channel.md b/docs/resources/Channel.md index f8f218136d..931ae0b923 100644 --- a/docs/resources/Channel.md +++ b/docs/resources/Channel.md @@ -1309,8 +1309,8 @@ When `with_member` is set to `true`, the thread member object will include a `me ###### Query String Params -| Field | Type | Description | -| ------------ | --------- | ------------------------------------------------------------------------------------------------------ | +| Field | Type | Description | +| ------------ | --------- | ----------------------------------------------------------------------------------------------------------- | | with_member? | boolean | Whether to include a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object for the thread member | ## List Thread Members % GET /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/thread-members @@ -1327,11 +1327,11 @@ When `with_member` is set to `true`, the results will be paginated and each thre ###### Query String Params -| Field | Type | Description | -| ------------ | --------- | ------------------------------------------------------------------------------------------------------- | +| Field | Type | Description | +| ------------ | --------- | ------------------------------------------------------------------------------------------------------------ | | with_member? | boolean | Whether to include a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object for each thread member | -| after? | snowflake | Get thread members after this user ID | -| limit? | integer | Max number of thread members to return (1-100). Defaults to 100. | +| after? | snowflake | Get thread members after this user ID | +| limit? | integer | Max number of thread members to return (1-100). Defaults to 100. | ## List Public Archived Threads % GET /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/threads/archived/public From 861b8bf772a9f51ba64473d54a8a8b3b3e9631f5 Mon Sep 17 00:00:00 2001 From: Shay Date: Mon, 9 Jan 2023 12:36:52 -0800 Subject: [PATCH 5/5] oops --- docs/Change_Log.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Change_Log.md b/docs/Change_Log.md index a9891a4331..ac40b3e57b 100644 --- a/docs/Change_Log.md +++ b/docs/Change_Log.md @@ -9,7 +9,7 @@ A new `member` field was added to the [thread member object](#DOCS_RESOURCES_CHANNEL/thread-member-object). `member` is a [guild member object](#DOCS_RESOURCES_GUILD/guild-member-object) that will be included within returned thread member objects when the new `with_member` field is set to `true` in the [List Thread Members](#DOCS_RESOURCES_CHANNEL/list-thread-members) (`GET /channels//thread-members`) and [Get Thread Member](#DOCS_RESOURCES_CHANNEL/get-thread-member) (`GET /channels//thread-members/`) endpoints. -Setting `with_member` to `true` will also make enable pagination for the [List Thread Members](#DOCS_RESOURCES_CHANNEL/list-thread-members) endpoint. When the results are paginated, you can use the new `after` and `limit` fields to fetch additional thread members and limit the number of thread members returned. By default, `limit` is 100. +Setting `with_member` to `true` will also enable pagination for the [List Thread Members](#DOCS_RESOURCES_CHANNEL/list-thread-members) endpoint. When the results are paginated, you can use the new `after` and `limit` fields to fetch additional thread members and limit the number of thread members returned. By default, `limit` is 100. #### Upcoming Changes