Skip to content

Commit df5b82e

Browse files
RedDaedalusanthonydiscord
authored and
mazylol
committed
Document new pin endpoints (discord#7585)
* document new pin endpoints * fix errors * fix tables * Update links --------- Co-authored-by: Anthony Tesija <anthony.tesija@discordapp.com>
1 parent 9de6577 commit df5b82e

File tree

2 files changed

+72
-30
lines changed

2 files changed

+72
-30
lines changed

‎docs/resources/channel.mdx‎

Lines changed: 0 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -510,33 +510,6 @@ Post a typing indicator for the specified channel, which expires after 10 second
510510

511511
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.
512512

513-
## Get Pinned Messages
514-
<Route method="GET">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins</Route>
515-
516-
Returns all pinned messages in the channel as an array of [message](/docs/resources/message#message-object) objects.
517-
518-
## Pin Message
519-
<Route method="PUT">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>
520-
521-
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.
522-
523-
:::warn
524-
The max pinned messages is 50.
525-
:::
526-
527-
:::info
528-
This endpoint supports the `X-Audit-Log-Reason` header.
529-
:::
530-
531-
## Unpin Message
532-
<Route method="DELETE">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>
533-
534-
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.
535-
536-
:::info
537-
This endpoint supports the `X-Audit-Log-Reason` header.
538-
:::
539-
540513
## Group DM Add Recipient
541514
<Route method="PUT">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/recipients/[\{user.id\}](/docs/resources/user#user-object)</Route>
542515

‎docs/resources/message.mdx‎

Lines changed: 72 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -267,8 +267,8 @@ One of [Application Command Interaction Metadata](/docs/resources/message#messag
267267
| original_response_message_id? | snowflake | ID of the original response message, present only on [follow-up messages](/docs/interactions/receiving-and-responding) |
268268
| 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 |
269269
| 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. |
270-
271-
270+
271+
272272
###### Message Component Interaction Metadata Structure
273273

274274
| Field | Type | Description |
@@ -566,7 +566,7 @@ Embeds are deduplicated by URL. If a message contains multiple embeds with the
566566

567567
#### Embed Fields by Embed Type
568568

569-
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.
569+
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.
570570

571571
###### Poll Result Embed Fields
572572

@@ -737,6 +737,15 @@ user 125 in the content.
737737
| total_months_subscribed | integer | the cumulative number of months that the user has been subscribed for |
738738
| is_renewal | boolean | whether this notification is for a renewal rather than a new purchase |
739739

740+
### Message Pin Object
741+
742+
###### Message Pin Object Struture
743+
744+
| Field | Type | Description |
745+
|-----------|----------------------------------------------------------|---------------------------------|
746+
| pinned_at | ISO8601 timestamp | the time the message was pinned |
747+
| message | [message](/docs/resources/message#message-object) object | the pinned message |
748+
740749
## Get Channel Messages
741750
<Route method="GET">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages</Route>
742751

@@ -952,3 +961,63 @@ This endpoint supports the `X-Audit-Log-Reason` header.
952961
| Field | Type | Description |
953962
|----------|---------------------|-------------------------------------------|
954963
| messages | array of snowflakes | an array of message ids to delete (2-100) |
964+
965+
## Get Channel Pins
966+
<Route method="GET">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins</Route>
967+
968+
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.
969+
970+
###### Query String Params
971+
972+
| Field | Type | Description | Default |
973+
|---------|-------------------|-------------------------------------------|---------|
974+
| before? | ISO8601 timestamp | Get messages pinned before this timestamp | absent |
975+
| after? | ISO8601 timestamp | Get messages pinned after this timestamp | absent |
976+
| limit? | integer | Max number of pins to return (1-50) | 50 |
977+
978+
###### Response Structure
979+
980+
| Field | Type |
981+
|----------|----------------------------------------------------------------------------|
982+
| items | array of [message pin](/docs/resources/message#message-pin-object) objects |
983+
| has_more | boolean |
984+
985+
###### Example
986+
987+
If you want to get 100 pins you'd send these two requests:
988+
`GET /channels/:id/messages/pins?limit=50`
989+
`GET /channels/:id/messages/pins?limit=50&after={pins[pins.len() - 1].pinned_at}`
990+
991+
## Pin Message
992+
<Route method="PUT">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>
993+
994+
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.
995+
996+
:::info
997+
This endpoint supports the `X-Audit-Log-Reason` header.
998+
:::
999+
1000+
## Unpin Message
1001+
<Route method="DELETE">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>
1002+
1003+
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.
1004+
1005+
:::info
1006+
This endpoint supports the `X-Audit-Log-Reason` header.
1007+
:::
1008+
1009+
## Get Pinned Messages (deprecated)
1010+
<Route method="GET">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins</Route>
1011+
1012+
Gets the first 50 pinned messages in a channel, returning an array of [message](/docs/resources/message#message-object) objects on success.
1013+
This endpoint is deprecated. Use [Get Channel Pins](/docs/resources/message#get-channel-pins) instead.
1014+
1015+
## Pin Message (deprecated)
1016+
<Route method="PUT">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>
1017+
1018+
This endpoint is deprecated. Use [Pin Message](/docs/resources/message#pin-message) instead.
1019+
1020+
## Unpin Message (deprecated)
1021+
<Route method="DELETE">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/pins/[\{message.id\}](/docs/resources/message#message-object)</Route>
1022+
1023+
This endpoint is deprecated. Use [Unpin Message](/docs/resources/message#unpin-message) instead.

0 commit comments

Comments
 (0)