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

Merged
merged 4 commits into from
Jun 21, 2025
Merged

Document new pin endpoints #7585

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 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
8c0dda7
Update links
anthonydiscord Jun 21, 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
75 changes: 72 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,63 @@ 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 |
| after? | ISO8601 timestamp | Get messages pinned after this timestamp | absent |
| limit? | integer | Max number of pins to return (1-50) | 50 |
Copy link

@Soheab Soheab Jun 14, 2025

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

@advaith1 advaith1 Jun 14, 2025

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

Copy link
Contributor

@anthonydiscord anthonydiscord Jun 21, 2025

Choose a reason for hiding this comment

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

For this I suggest submitting an issue since we would likely want the endpoint to be able to return one pin.

Copy link
Contributor

@Jiralite Jiralite Jun 21, 2025

Choose a reason for hiding this comment

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

So... this pull request has merged immaturely?

Copy link

@Soheab Soheab Jun 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Update: setting the limit to 1 works as it should now. I was calling a different endpoint, it still errors out when set to 1.

Copy link
Contributor

@anthonydiscord anthonydiscord Jun 23, 2025

Choose a reason for hiding this comment

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

I let the team know about the issue, thanks for digging into it!

Copy link
Contributor

@advaith1 advaith1 Jun 25, 2025

Choose a reason for hiding this comment

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

fixed, limit=1 works now


###### Response Structure

| Field | Type |
|----------|----------------------------------------------------------------------------|
| 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
<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 [Get Channel Pins](/docs/resources/message#get-channel-pins) instead.

## 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. Use [Pin Message](/docs/resources/message#pin-message) instead.

## 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. Use [Unpin Message](/docs/resources/message#unpin-message) instead.