Skip to content

Document new pin endpoints #7585

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

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Document new pin endpoints #7585

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
27039f6
document new pin endpoints
RedDaedalus May 31, 2025
11728e6
fix errors
RedDaedalus May 31, 2025
69f48e6
fix tables
RedDaedalus May 31, 2025
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
27 changes: 0 additions & 27 deletions docs/resources/channel.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<Route method="GET">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins</Route>

Returns all pinned messages in the channel as an array of [message](/docs/resources/message#message-object) objects.

## Pin Message
<Route method="PUT">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>

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
<Route method="DELETE">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>

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
<Route method="PUT">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/recipients/[\{user.id\}](/docs/resources/user#user-object)</Route>

Expand Down
68 changes: 65 additions & 3 deletions docs/resources/message.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
<Route method="GET">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages</Route>

Expand Down Expand Up @@ -952,3 +961,56 @@ 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
<Route method="GET">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins</Route>

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

| 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 |
Copy link

Choose a reason for hiding this comment

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

Suggested change
| limit? | integer | Max number of pins to return (1-50) | 50 |
| limit? | integer | Max number of pins to return (2-50) | 50 |

Setting the limit to 1 throws the following:

400 Bad Request (error code: 50035): Invalid Form Body
In limit: int value should be greater than or equal to 2.

Copy link
Contributor

Choose a reason for hiding this comment

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

probably better to support limits of 1 for consistency


###### Response Structure

| Field | Type |
|----------|----------------------------------------------------------------------------|
| items | array of [message pin](/docs/resources/message#message-pin-object) objects |
| has_more | boolean |

## Pin Message
<Route method="PUT">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>

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.
:::

## Unpin Message
<Route method="DELETE">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>

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)
<Route method="GET">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins</Route>

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.
Copy link
Contributor

Choose a reason for hiding this comment

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

The "above" might be confusing since it's a bit far away. This is a website, so we can use hrefs to refer to another section.

Suggested change
This endpoint is deprecated. Use the one above instead.
This endpoint is deprecated. Use [Get Channel Pins](/docs/resources/message#get-channel-pins) instead.

I'd do the same for each deprecated endpoint.


## Pin Message (deprecated)
<Route method="PUT">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>

This endpoint is deprecated. It functions the same as its non-deprecated counterpart.

## Unpin Message (deprecated)
<Route method="DELETE">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>

This endpoint is deprecated. It functions the same as its non-deprecated counterpart.