Update group DM docs #1639

FasterSpeeding · 2020-05-16T02:05:03Z

No description provided.

docs/resources/Channel.md

docs/resources/User.md

FasterSpeeding · 2020-05-24T16:00:03Z

Just as a note, I've added documentation for modifying and accessing group DM icons but there seems to be some funky behaviour around these; the group DM's icon hash seems to be defaulting to the application icon hash of the application that created it (with this being valid on the "app-icons" cdn endpoint but not the "channel-icons" endpoint) with any modifications to it changing it from an app-icon to a channel-icon.

I'm not entirely sure if this is intended behaviour or how to document this (as far as I can tell the only way to workout whether channel.icon is an app-icon or a channel-icon is through trial and error which seems like a bad way to deal with icons) and this seems to break the Windows desktop client (Canary 60661 (578c2e8)) as from what I've seen it always tries to get the icon of a managed group DM from the app-icons cdn endpoint regardless of whether it's been modified or not.

ghost · 2020-05-24T18:18:04Z

docs/resources/Channel.md

 | parent_id?             | ?snowflake                                                             | id of the parent category for a channel (each parent category can contain up to 50 channels)                                                                                    |
 | last_pin_timestamp?    | ISO8601 timestamp                                                      | when the last pinned message was pinned                                                                                                                                         |

+\* The `name` field is only nullable for group DM channels.


This isn't a complaint at this PR, but a question for the next employee who reads this, if it is read.

At this point, would it be more helpful to have separate tables for each type of channel? As a developer, this kind of merged information makes writing distinct entities for each type of channel incredibly awkward and a case of trial and error. Since general programming paradigms encourage separation of concerns, that would likely be of much more use. Especially since the majority of programming languages interfacing with this API for anything other than a trivial one-off request will likely want to make some form of struct or class to represent the entity they are dealing with.

That would remove the need to document stuff like this in this way as well, and remove questions such as "can you pin messages in a news channel? Is a news channel the same as a text channel, because I cant tell because I am not lucky enough to be the owner of a guild that has a news channel to try this on? Can voice channels really be marked as NSFW?".

I can agree that a separation could be beneficial towards having an easier to understand documentation.

Towards your questions;

News channels are - in most basic terms - just fancy Text Channels with the option that you can post news to following Guilds. Most libraries I know just treat News Channels as normal Text Channels as they, from what I know, don't offer any specific functions for bots that would be different to normal Text Channels. So yes, you could pin messages in that channel as it would be a normal Text Channel with some slight differences.

Voice Channels can't be marked nsfw. You probs can set the NSFW property (Since the docs suggest that it is a thing) but I believe that Discord just ignores that value for the Voice Channel type, so no matter what, it would remain false... I could be wrong here tho.

Cheers for the clarification :)

nsfw can be set/changed for any guild channel, if it's being ignored that's at a client level not the api level.

ghost · 2020-05-24T18:21:39Z

docs/resources/Channel.md

+| bitrate               | ?integer                                                                | the bitrate (in bits) of the voice channel; 8000 to 96000 (128000 for VIP servers)                                                                                              | Voice                                        |
+| user_limit            | ?integer                                                                | the user limit of the voice channel; 0 refers to no limit, 1 to 99 refers to a user limit                                                                                       | Voice                                        |
+| permission_overwrites | ?array of [overwrite](#DOCS_RESOURCES_CHANNEL/overwrite-object) objects | channel or category-specific permissions                                                                                                                                        | Text, News, Store, Voice, Category           |
+| parent_id             | ?snowflake                                                              | id of the new parent category for a channel                                                                                                                                     | Text, News, Store, Voice                     |


should ID be capitalised, since it is an abbreviation?

ghost · 2020-05-24T18:22:24Z

docs/resources/Channel.md

+| nsfw                  | ?boolean                                                                | whether the channel is nsfw                                                                                                                                                     | Text, News, Store                            |
+| rate_limit_per_user   | ?integer                                                                | amount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission `manage_messages` or `manage_channel`, are unaffected | Text                                         |
+| bitrate               | ?integer                                                                | the bitrate (in bits) of the voice channel; 8000 to 96000 (128000 for VIP servers)                                                                                              | Voice                                        |
+| user_limit            | ?integer                                                                | the user limit of the voice channel; 0 refers to no limit, 1 to 99 refers to a user limit                                                                                       | Voice                                        |


what does not specifying this imply?

I can guess the answer, assuming a sane implementation; someone else might not be familiar with the default.

ghost · 2020-05-24T18:23:03Z

docs/resources/Channel.md

+| type                  | integer                                                                 | the [type of channel](#DOCS_RESOURCES_CHANNEL/channel-object-channel-types); only conversion between text and news is supported and only in guilds with the "NEWS" feature      | Text, News                                   |
+| position              | ?integer                                                                | the position of the channel in the left-hand listing                                                                                                                            | Text, News, Store, Voice, Category           |
+| topic                 | ?string                                                                 | 0-1024 character channel topic                                                                                                                                                  | Text, News                                   |
+| nsfw                  | ?boolean                                                                | whether the channel is nsfw                                                                                                                                                     | Text, News, Store                            |


don't voice channels have a NSFW attribute on them, even if the client doesn't show this? Might be mistaken here.

Yes they do according to the Guild Voice Channel example

perhaps it is time for staff to determine if this is a feature or a missed bug, and we can then document it properly/perhaps request the client also shows this on their trello, or consider it an undocumented artifact that can be removed everywhere?

ghost · 2020-05-24T18:24:02Z

docs/resources/User.md

 ## Create Group DM % POST /users/@me/channels

-Create a new group DM channel with multiple users. Returns a [DM channel](#DOCS_RESOURCES_CHANNEL/channel-object) object. This endpoint was intended to be used with the now-deprecated GameBridge SDK. DMs created with this endpoint will not be shown in the Discord client
+Create a new group DM channel with multiple users. Returns a [DM channel](#DOCS_RESOURCES_CHANNEL/channel-object) object. This endpoint was intended to be used with the now-deprecated GameBridge SDK.


Should we be documenting deprecated stuff at all? Deprecation usually implies we don't want the user to use them because they might go away eventually, or are not fit for purpose.

Is there a valid use case for this, or is it a feature destined to be purged randomly? (Question for someone who is an employee!)

Night has made a statement regarding it previously: #1640 (comment)

ghost

Other than the stuff I left for Discord to answer ~~hopefully~~, LGTM.

vladfrangu · 2020-06-07T19:01:13Z

docs/resources/Channel.md

+| id    | snowflake | the user's nickname                            |
+| nick  | string    | the id of the user this nickname is applied to |


Androz2091 · 2020-06-08T06:38:15Z

docs/Reference.md


 | Type                   | Path                                                                                                                                                                                                                                    | Supports             |
 | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Channel Icons          | channel-icons/[chanel_id](#DOCS_RESOURCES_CHANNEL/channel-object)/[channel_icon](#DOCS_RESOURCES_CHANNEL/channel-object).png                                                                                                            | PNG, JPEG, WebP      |


I'm not sure, shouldn't chanel_id be channel_id?

Suggested change

| Channel Icons | channel-icons/[chanel_id](#DOCS_RESOURCES_CHANNEL/channel-object)/[channel_icon](#DOCS_RESOURCES_CHANNEL/channel-object).png | PNG, JPEG, WebP |

| Channel Icons | channel-icons/[channel_id](#DOCS_RESOURCES_CHANNEL/channel-object)/[channel_icon](#DOCS_RESOURCES_CHANNEL/channel-object).png | PNG, JPEG, WebP |

advaith1 · 2020-06-12T00:46:15Z

For the Modify Channel params table, it seems inconsistent to list all guild channel types for nsfw but only list voice for bitrate; iirc bitrate can be technically set for all channel types but they only affect voice channels, and nsfw can also technically be set for all channel types but only affect text and news channels. It would probably be better to only list the channel types which the param actually has an effect on.

advaith1 · 2020-06-13T20:10:30Z

docs/resources/Channel.md

-| parent_id             | ?snowflake                                                              | id of the new parent category for a channel                                                                                                                                     | Text, News, Store, Voice  |
+| Field                 | Type                                                                    | Description                                                                                                                                                                     | Channel Type                                 |
+| --------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| name                  | ?string                                                                 | 2-100 character channel name                                                                                                                                                    | Group DM, Text, News, Store, Voice, Category |


why was this changed?

night · 2021-04-06T01:41:02Z

There's numerous code review comments which have not been addressed, and given managed group dms are somewhat deprecated and not really used I don't imagine there's much use to documenting these changes anyhow.

Update group DM docs

5c961ef

Andre601 reviewed May 16, 2020

View reviewed changes

docs/resources/Channel.md Outdated Show resolved Hide resolved

bool -> boolean

568d7f2

z64 reviewed May 16, 2020

View reviewed changes

docs/resources/User.md Show resolved Hide resolved

Andre601 approved these changes May 17, 2020

View reviewed changes

Document modifying a group DM's icon.

352e389

FasterSpeeding force-pushed the update-group-dm-documentation branch from 8bc634d to a0b0f38 Compare May 24, 2020 17:53

name is nullable for group DM channels.

ee5fd57

FasterSpeeding force-pushed the update-group-dm-documentation branch from a0b0f38 to ee5fd57 Compare May 24, 2020 18:05

ghost reviewed May 24, 2020

View reviewed changes

nsfw is a valid field for every guild text type

4302a75

ghost approved these changes May 24, 2020

View reviewed changes

FasterSpeeding force-pushed the update-group-dm-documentation branch 2 times, most recently from d6d980e to 4302a75 Compare May 31, 2020 03:00

Document group channel "nicks" attribute

13f5494

vladfrangu suggested changes Jun 7, 2020

View reviewed changes

Androz2091 reviewed Jun 8, 2020

View reviewed changes

advaith1 reviewed Jun 13, 2020

View reviewed changes

night closed this Apr 6, 2021

advaith1 mentioned this pull request Sep 29, 2021

Document Channel-Icon CDN Endpoint #3882

Closed

SinisterRectus mentioned this pull request Mar 4, 2022

fix: mark channel name as nullable #4571

Merged

advaith1 mentioned this pull request Jan 20, 2023

Document error code 30011 & managed field for channels #5867

Merged

		\| id \| snowflake \| the user's nickname \|
		\| nick \| string \| the id of the user this nickname is applied to \|

	\| Channel Icons \| channel-icons/[chanel_id](#DOCS_RESOURCES_CHANNEL/channel-object)/[channel_icon](#DOCS_RESOURCES_CHANNEL/channel-object).png \| PNG, JPEG, WebP \|
	\| Channel Icons \| channel-icons/[channel_id](#DOCS_RESOURCES_CHANNEL/channel-object)/[channel_icon](#DOCS_RESOURCES_CHANNEL/channel-object).png \| PNG, JPEG, WebP \|

Update group DM docs #1639

Update group DM docs #1639

Uh oh!

Conversation

FasterSpeeding commented May 16, 2020

Uh oh!

Uh oh!

Uh oh!

FasterSpeeding commented May 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ghost May 24, 2020 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FasterSpeeding May 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ghost May 24, 2020 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ghost left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

advaith1 commented Jun 12, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

night commented Apr 6, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

FasterSpeeding commented May 24, 2020 •

edited

Loading

ghost May 24, 2020 •

edited by ghost

Loading

FasterSpeeding May 24, 2020 •

edited

Loading

ghost May 24, 2020 •

edited by ghost

Loading