From 27039f6da122110676f32dfc51e7462a9f2555a9 Mon Sep 17 00:00:00 2001 From: Daedalus <16168171+RedDaedalus@users.noreply.github.com> Date: Fri, 30 May 2025 21:40:28 -0600 Subject: [PATCH 1/4] document new pin endpoints --- docs/resources/channel.mdx | 27 ----------------- docs/resources/message.mdx | 61 ++++++++++++++++++++++++++++++++++++-- 2 files changed, 58 insertions(+), 30 deletions(-) diff --git a/docs/resources/channel.mdx b/docs/resources/channel.mdx index e1df62ca54..54e164637f 100644 --- a/docs/resources/channel.mdx +++ b/docs/resources/channel.mdx @@ -510,33 +510,6 @@ Post a typing indicator for the specified channel, which expires after 10 second Generally bots should **not** use this route. However, if a bot is responding to a command and expects the computation to take a few seconds, this endpoint may be called to let the user know that the bot is processing their message. -## Get Pinned Messages -/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins - -Returns all pinned messages in the channel as an array of [message](/docs/resources/message#message-object) objects. - -## Pin Message -/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object) - -Pin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](/docs/events/gateway-events#channel-pins-update) Gateway event. - -:::warn -The max pinned messages is 50. -::: - -:::info -This endpoint supports the `X-Audit-Log-Reason` header. -::: - -## Unpin Message -/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object) - -Unpin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](/docs/events/gateway-events#channel-pins-update) Gateway event. - -:::info -This endpoint supports the `X-Audit-Log-Reason` header. -::: - ## Group DM Add Recipient /channels/[\{channel.id\}](/docs/resources/channel#channel-object)/recipients/[\{user.id\}](/docs/resources/user#user-object) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index 3eb76109f6..498c5a0872 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -267,8 +267,8 @@ One of [Application Command Interaction Metadata](/docs/resources/message#messag | original_response_message_id? | snowflake | ID of the original response message, present only on [follow-up messages](/docs/interactions/receiving-and-responding) | | target_user? | [user](/docs/resources/user#user-object) object | The user the command was run on, present only on [user command](/docs/interactions/application-commands#user-commands) interactions | | target_message_id? | snowflake | The ID of the message the command was run on, present only on [message command](/docs/interactions/application-commands#message-commands) interactions. The original response message will also have `message_reference` and `referenced_message` pointing to this message. | - - + + ###### Message Component Interaction Metadata Structure | Field | Type | Description | @@ -566,7 +566,7 @@ Embeds are deduplicated by URL. If a message contains multiple embeds with the #### Embed Fields by Embed Type -Certain embed types are used to power special UIs. These embeds use [fields](/docs/resources/message#embed-object-embed-field-structure) to include additional data in key-value pairs. Below is a reference of possible embed fields for each of the following embed types. +Certain embed types are used to power special UIs. These embeds use [fields](/docs/resources/message#embed-object-embed-field-structure) to include additional data in key-value pairs. Below is a reference of possible embed fields for each of the following embed types. ###### Poll Result Embed Fields @@ -737,6 +737,15 @@ user 125 in the content. | total_months_subscribed | integer | the cumulative number of months that the user has been subscribed for | | is_renewal | boolean | whether this notification is for a renewal rather than a new purchase | +### Message Pin Object + +###### Message Pin Object Struture + +| Field | Type | Description | +| --------- | -------------------------------------------------------- | ------------------------------- | +| pinned_at | ISO8601 timestamp | the time the message was pinned | +| message | [message](/docs/resources/message#message-object) object | the pinned message | + ## Get Channel Messages /channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages @@ -952,3 +961,49 @@ This endpoint supports the `X-Audit-Log-Reason` header. | Field | Type | Description | |----------|---------------------|-------------------------------------------| | messages | array of snowflakes | an array of message ids to delete (2-100) | + +## Get Channel Pins +/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins + +Retrieves a list of pins in a channel. Returns an array of [message pin](/docs/resources/message#message-pin-object)s. + +###### Query String Params + +| Field | Type | Description | Default | +| ------- | ----------------- | ----------------------------------------- | ------- | +| before? | ISO8601 timestamp | Get messages pinned before this timestamp | absent | +| limit? | integer | Max number of pins to return (1-50) | 50 | + +## Pin Message +/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins/[\{message.id\}](/docs/resources/message#message-object) + +Pin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](/docs/events/gateway-events#channel-pins-update) Gateway event. + +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: + +## Unpin Message +/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins/[\{message.id\}](/docs/resources/message#message-object) + +Unpin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](/docs/events/gateway-events#channel-pins-update) Gateway event. + +:::info +This endpoint supports the `X-Audit-Log-Reason` header. +::: + +## Get Pinned Messages (deprecated) +/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins + +Gets the first 50 pinned messages in a channel, returning an array of [message](/docs/resources/message#message-object) objects on success. +This endpoint is deprecated. Use the one above instead. + +## Pin Message (deprecated) +/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object) + +This endpoint is deprecated. It functions the same as its non-deprecated counterpart. + +## Unpin Message (deprecated) +/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object) + +This endpoint is deprecated. It functions the same as its non-deprecated counterpart. From 11728e6b6adccda9aad14d0c65102127888e3d58 Mon Sep 17 00:00:00 2001 From: Daedalus <16168171+RedDaedalus@users.noreply.github.com> Date: Fri, 30 May 2025 21:50:20 -0600 Subject: [PATCH 2/4] fix errors --- docs/resources/message.mdx | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index 498c5a0872..1c185c86f1 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -965,7 +965,7 @@ This endpoint supports the `X-Audit-Log-Reason` header. ## Get Channel Pins /channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins -Retrieves a list of pins in a channel. Returns an array of [message pin](/docs/resources/message#message-pin-object)s. +Retrieves the list of pins in a channel. Requires the `VIEW_CHANNEL` permission. If the user is missing the `READ_MESSAGE_HISTORY` permission in the channel, then no pins will be returned. ###### Query String Params @@ -974,10 +974,17 @@ Retrieves a list of pins in a channel. Returns an array of [message pin](/docs/r | before? | ISO8601 timestamp | Get messages pinned before this timestamp | absent | | limit? | integer | Max number of pins to return (1-50) | 50 | +###### Response Structure + +| Field | Type | +| -------- | -------------------------------------------------------------------------- | +| items | array of [message pin](/docs/resources/message#message-pin-object) objects | +| has_more | boolean | + ## Pin Message /channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins/[\{message.id\}](/docs/resources/message#message-object) -Pin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](/docs/events/gateway-events#channel-pins-update) Gateway event. +Pin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Fires a [Channel Pins Update](/docs/events/gateway-events#channel-pins-update) Gateway event. :::info This endpoint supports the `X-Audit-Log-Reason` header. From 69f48e6ed097573fe684588e9aff6dc22a083c04 Mon Sep 17 00:00:00 2001 From: Daedalus <16168171+RedDaedalus@users.noreply.github.com> Date: Fri, 30 May 2025 22:46:32 -0600 Subject: [PATCH 3/4] fix tables --- docs/resources/message.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index 1c185c86f1..1d2c063979 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -742,7 +742,7 @@ user 125 in the content. ###### Message Pin Object Struture | Field | Type | Description | -| --------- | -------------------------------------------------------- | ------------------------------- | +|-----------|----------------------------------------------------------|---------------------------------| | pinned_at | ISO8601 timestamp | the time the message was pinned | | message | [message](/docs/resources/message#message-object) object | the pinned message | @@ -970,14 +970,14 @@ Retrieves the list of pins in a channel. Requires the `VIEW_CHANNEL` permission. ###### Query String Params | Field | Type | Description | Default | -| ------- | ----------------- | ----------------------------------------- | ------- | +|---------|-------------------|-------------------------------------------|---------| | before? | ISO8601 timestamp | Get messages pinned before this timestamp | absent | | limit? | integer | Max number of pins to return (1-50) | 50 | ###### Response Structure | Field | Type | -| -------- | -------------------------------------------------------------------------- | +|----------|----------------------------------------------------------------------------| | items | array of [message pin](/docs/resources/message#message-pin-object) objects | | has_more | boolean | From 8c0dda785a90c1fa32cc59d21eca7d7e5861ef2d Mon Sep 17 00:00:00 2001 From: Anthony Tesija Date: Sat, 21 Jun 2025 01:24:01 +0000 Subject: [PATCH 4/4] Update links --- docs/resources/message.mdx | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index 1d2c063979..c14c9351a6 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -972,6 +972,7 @@ Retrieves the list of pins in a channel. Requires the `VIEW_CHANNEL` permission. | Field | Type | Description | Default | |---------|-------------------|-------------------------------------------|---------| | before? | ISO8601 timestamp | Get messages pinned before this timestamp | absent | +| after? | ISO8601 timestamp | Get messages pinned after this timestamp | absent | | limit? | integer | Max number of pins to return (1-50) | 50 | ###### Response Structure @@ -981,6 +982,12 @@ Retrieves the list of pins in a channel. Requires the `VIEW_CHANNEL` permission. | items | array of [message pin](/docs/resources/message#message-pin-object) objects | | has_more | boolean | +###### Example + +If you want to get 100 pins you'd send these two requests: +`GET /channels/:id/messages/pins?limit=50` +`GET /channels/:id/messages/pins?limit=50&after={pins[pins.len() - 1].pinned_at}` + ## Pin Message /channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins/[\{message.id\}](/docs/resources/message#message-object) @@ -1003,14 +1010,14 @@ This endpoint supports the `X-Audit-Log-Reason` header. /channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins Gets the first 50 pinned messages in a channel, returning an array of [message](/docs/resources/message#message-object) objects on success. -This endpoint is deprecated. Use the one above instead. +This endpoint is deprecated. Use [Get Channel Pins](/docs/resources/message#get-channel-pins) instead. ## Pin Message (deprecated) /channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object) -This endpoint is deprecated. It functions the same as its non-deprecated counterpart. +This endpoint is deprecated. Use [Pin Message](/docs/resources/message#pin-message) instead. ## Unpin Message (deprecated) /channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object) -This endpoint is deprecated. It functions the same as its non-deprecated counterpart. +This endpoint is deprecated. Use [Unpin Message](/docs/resources/message#unpin-message) instead.