Document APIv9. #2855

ajpalkovic · 2021-04-28T19:01:18Z

To make migration easier, there is a guide in docs/topics/Threads.md that aggregates all the information about threads in one place for you!

We wanted to give app developers at least 2 months heads up so you all can update your bots and be ready to go whenever we do ship threads. Please keep in mind that bots on older API versions will receive NO gateway events for threads, or messages in threads, so updating is important!

I'll be around for questions today, and I plan to keep this open for ~24 hours and then merge tomorrow afternoon and update the docs website.

docs/topics/Threads.md

docs/topics/Permissions.md

docs/Change_Log.md

xSke · 2021-04-28T19:19:38Z

Will there be a way to test out threads before this officially ships? A lot of these changes seem fairly complex (especially with the new layer of channel nesting and complexities there) and at the moment it's not trivial to conceptualize how threads even work (much less bug-hunt with them) without being able to play with it in action.

docs/topics/Gateway.md

devsnek · 2021-04-28T19:21:55Z

Locking for a bit... will unlock when things cool off.

FedorLap2006 · 2021-04-28T19:51:54Z

Will there be a way to test out threads before this officially ships? A lot of these changes seem fairly complex (especially with the new layer of channel nesting and complexities there) and at the moment it's not trivial to conceptualize how threads even work (much less bug-hunt with them) without being able to play with it in action.

As far as I understood there will be, they're having some sort of allowlist for that. Hoping to get there :)

A5rocks

Just a couple questions on my part...

docs/Change_Log.md

docs/Reference.md

A5rocks · 2021-04-28T19:07:21Z

docs/resources/Channel.md


 ###### Channel Types

+> warn
+> Type 10, 11 and 12 are only available in API v9.


Does this mean you cannot preform actions on them with REST API v8, or is it just that you don't get events for them. (also, 10, 11, and 12 instead of 10, 11 and 12 for oxford comma)

The REST API will work fine, I didn't really think there were any backwards compatibility issues there, it's mostly for gateway events that the issues happen.

A5rocks · 2021-04-28T19:11:13Z

docs/resources/Channel.md

+| message_count?         | integer                                                                    | an approximate count of messages in a thread, caps at 50                                                                                                                        |
+| member_count?          | integer                                                                    | an approximate count of users in a thread, caps at 50                                                                                                                           |


Is there any reason this isn't in the metadata too? (given other important information like archived is there too...)

I figured these were things that were potentially valuable for other types of channels in the future, but the thread_metadata things are basically never going to be valuable outside of threads.

A5rocks · 2021-04-28T19:13:43Z

docs/resources/Channel.md

+    "archived": false,
+    "archiver_id": "41771983423143937",


... an archiver for a channel that isn't archived? (Just a confusing attribute name imo, my bad)

Yeah, in this case it would be the person that unarchived the thread then.

A5rocks · 2021-04-28T19:18:59Z

docs/resources/Channel.md

@@ -422,6 +452,37 @@ Since message references are a generic attribution to a previous message, there

 \* `channel_id` is optional when creating a reply, but will always be present when receiving an event/response that includes this data model.

+#### Message Types
+
+There are multiple message types that have a message_reference object.  Since message references are generic attribution to a previous message, there will be more types of messages which have this information in the future.


Maybe use a different word than "type" for this? (as a message has a type attribute...)

Multiple variations / multiple kinds, perhaps?

docs/resources/Channel.md

docs/topics/Gateway.md

A5rocks · 2021-04-28T20:00:20Z

docs/topics/Gateway.md

+
+#### Thread List Sync
+
+Sent when the current user _gains_ access to a channel.


Does this have no payload? Perhaps saying which channel was joined would be more useful?

It's listed below :)

Lulalaby · 2021-04-28T20:20:03Z

Good work!

docs/resources/Channel.md

docs/topics/Permissions.md

DV8FromTheWorld · 2021-04-29T03:11:59Z

docs/resources/Channel.md

@@ -40,6 +47,9 @@ Represents a guild or DM channel within Discord.
 | GUILD_CATEGORY    | 4   | an [organizational category](https://support.discord.com/hc/en-us/articles/115001580171-Channel-Categories-101) that contains up to 50 channels      |
 | GUILD_NEWS        | 5   | a channel that [users can follow and crosspost into their own server](https://support.discord.com/hc/en-us/articles/360032008192)                    |
 | GUILD_STORE       | 6   | a channel in which game developers can [sell their game on Discord](https://discord.com/developers/docs/game-and-server-management/special-channels) |
+| NEWS_THREAD       | 10  | a temporary sub-channel within a GUILD_NEWS channel                                                                                                  |
+| PUBLIC_THREAD     | 11  | a temporary sub-channel within a GUILD_TEXT channel                                                                                                  |
+| PRIVATE_THREAD    | 12  | a temporary sub-channel within a GUILD_TEXT channel that is only viewable by those invited and those with the MANAGE_THREADS permission              |


Is it expected that threads will only ever be supported in Guilds? Not Groups or DMs?

Correct, only in Guilds

docs/resources/Channel.md

DV8FromTheWorld · 2021-04-29T04:04:04Z

docs/topics/Threads.md

+- Clients use _their own_ [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) to calculate read states and notification settings. This is largely irrelevant for bots though, but is the reason for some of the syncing complexity detailed here.
+- Knowing everyone that is in a thread.
+
+Membership is tracked in an array of [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) objects. These have four fields, `id` (the thread id), `user_id`, `join_timestamp`, and `flags`. Currently the only `flags` are for notification settings, but others may be added in future updates.


If a thread member loses "access" by way of the removal of SEND_MESSAGES, or USE_PUBLIC/PRIVATE_THREADS are they removed from this array?

If not, are they removed if READ_MESSAGES is removed?

No, we don't remove people when losing access to a channel.
One reason is a moderator may make a mistake or temporarily want to hide a channel, and it would be a bad experience to kick everyone out of a thread then!

DV8FromTheWorld · 2021-04-29T04:12:06Z

docs/topics/Gateway.md

+| Field        | Type                                                                           | Description                                                                                                                               |
+|--------------|--------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
+| guild_id     | snowflake                                                                      | the id of the guild                                                                                                                       |
+| channel_ids? | array of snowflakes                                                            | the parent channel ids whose threads are being synced.  If omitted, then threads were synced for the entire guild                         |


When would thread lists be synced for the entire guild? On joining a guild?

Hmm. So for non-bots, we send this message when you first click on a guild, effectively lazy loading threads. But for bots, we hide this and send you all that data in guild_create. So, yeah, in practice for bots, it's probably always provided.

Oh, actually there is one other case, when someone becomes owner of a guild we re-sync everything, but that's hopefully not an issue for bots too

DV8FromTheWorld · 2021-04-29T04:14:18Z

docs/topics/Gateway.md

+| guild_id     | snowflake                                                                      | the id of the guild                                                                                                                       |
+| channel_ids? | array of snowflakes                                                            | the parent channel ids whose threads are being synced.  If omitted, then threads were synced for the entire guild                         |
+| threads      | array of [channel](#DOCS_RESOURCES_CHANNEL/channel-object) objects             | all active threads in the given channels that the current user can access                                                                 |
+| members      | array of [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) objects | all thread member objects from the synced threads for the current user, indicating which threads the current user has been added to       |


To be clear, the channel_ids and members information is available in a nested format inside of the threads array, correct? (threads[*].parentId and threads[*].member)

Are these root-level properties just for making certain access patterns easier or is there a specific reason for them?

Check out the Thread Membership section and if you still have questions or concerns about it, let me know, but it talks about this

Also channel_ids can't be inferred from the returned threads.
I expect the algorithm bots should use here is:

Remove all threads that have a parent_id that is in the channel_ids set

Add all threads from the threads array
Because a channel might not have any active threads in it, so we're signaling that to you here as well!

docs/topics/Opcodes_and_Status_Codes.md

DV8FromTheWorld · 2021-04-29T04:20:38Z

docs/topics/Threads.md

+
+### Syncing for the current user
+
+- A [Thread Members Update](#DOCS_TOPICS_GATEWAY/thread-members-update) Gateway Event is always sent when the current user is added to or removed from a thread.


Is this only fired if a user is explicitly removed? (Self removal or removed by an Admin)
Or is this also triggered by implicit access lost via the revocation of READ_MESSAGES on the parent channel?

It's sent when someone is added or removed.
Permission changes will not remove you from a thread

sayantan300

Nice work discord team 👏

docs/Change_Log.md

ajpalkovic · 2021-04-30T23:22:58Z

Hey all, I'm going to merge and deploy this, if you have other concerns though, feel free to open Issues or PRs as you would normally.

This reverts commit 478af37.

Aericio · 2021-05-01T10:38:48Z

@ajpalkovic hope it's okay to comment here, just found an inconsistency.

Start Public Thread
Start a private thread

Probably Start Private Thread instead?

benkaday3218

Leave the user

docs/resources/Channel.md

See discord/discord-api-docs#2855.

Assassin-1234

hyped 🔥

ghost · 2021-05-14T05:09:33Z

hyped 🔥

yup

This PR implements the models for threads, including gateway payloads and cache updating (first time working with the Twilight's gateway + cache, so scrutinise my code). Still todo / caveats: - Make the NumericEnumVisitor work with multiple types. There's a lot of commented code in `model/src/visitor.rs`. - Update intents comments - I left ThreadMember's `flags` field as a u64. Discord's documentation only says `any user-thread settings, currently only used for notifications`, so we'll have to leave it as in integer for now. - Might've missed some tests? Not sure - HTTP (obviously) Docs PR: discord/discord-api-docs#2855 Address part of #799.

This PR implements the models for threads, including gateway payloads and cache updating (first time working with the Twilight's gateway + cache, so scrutinise my code). Still todo / caveats: - Make the NumericEnumVisitor work with multiple types. There's a lot of commented code in `model/src/visitor.rs`. - Update intents comments - I left ThreadMember's `flags` field as a u64. Discord's documentation only says `any user-thread settings, currently only used for notifications`, so we'll have to leave it as in integer for now. - Might've missed some tests? Not sure - HTTP (obviously) Docs PR: discord/discord-api-docs#2855 Address part of twilight-rs#799.

This PR implements the models for threads, including gateway payloads and cache updating (first time working with the Twilight's gateway + cache, so scrutinise my code). Still todo / caveats: - Make the NumericEnumVisitor work with multiple types. There's a lot of commented code in `model/src/visitor.rs`. - Update intents comments - I left ThreadMember's `flags` field as a u64. Discord's documentation only says `any user-thread settings, currently only used for notifications`, so we'll have to leave it as in integer for now. - Might've missed some tests? Not sure - HTTP (obviously) Docs PR: discord/discord-api-docs#2855 Address part of #799.

This commit adds support to guild threads channels, see discord/discord-api-docs#2855. It also bumps the Discord API version and gateway to v9.

This PR implements the models for threads, including gateway payloads and cache updating (first time working with the Twilight's gateway + cache, so scrutinise my code). Still todo / caveats: - Make the NumericEnumVisitor work with multiple types. There's a lot of commented code in `model/src/visitor.rs`. - Update intents comments - I left ThreadMember's `flags` field as a u64. Discord's documentation only says `any user-thread settings, currently only used for notifications`, so we'll have to leave it as in integer for now. - Might've missed some tests? Not sure - HTTP (obviously) Docs PR: discord/discord-api-docs#2855 Address part of #799.

This commit adds support to guild threads channels, see discord/discord-api-docs#2855. It also bumps the Discord API version and gateway to v9.

This PR implements the models for threads, including gateway payloads and cache updating (first time working with the Twilight's gateway + cache, so scrutinise my code). Still todo / caveats: - Make the NumericEnumVisitor work with multiple types. There's a lot of commented code in `model/src/visitor.rs`. - Update intents comments - I left ThreadMember's `flags` field as a u64. Discord's documentation only says `any user-thread settings, currently only used for notifications`, so we'll have to leave it as in integer for now. - Might've missed some tests? Not sure - HTTP (obviously) Docs PR: discord/discord-api-docs#2855 Address part of #799.

queer mentioned this pull request Apr 28, 2021

Support APIv9 mewna/catnip#538

Closed

This comment has been minimized.

Sign in to view

AEnterprise reviewed Apr 28, 2021

View reviewed changes

docs/topics/Threads.md Outdated Show resolved Hide resolved

discord deleted a comment from flav-code Apr 28, 2021

discord deleted a comment from Zet0x0 Apr 28, 2021

discord deleted a comment from joseywoermann Apr 28, 2021

xSke reviewed Apr 28, 2021

View reviewed changes

docs/topics/Permissions.md Outdated Show resolved Hide resolved

devsnek reviewed Apr 28, 2021

View reviewed changes

docs/Change_Log.md Show resolved Hide resolved

davfsa reviewed Apr 28, 2021

View reviewed changes

docs/topics/Gateway.md Outdated Show resolved Hide resolved

discord locked as too heated and limited conversation to collaborators Apr 28, 2021

FedorLap2006 mentioned this pull request Apr 28, 2021

Upgrade the API version and implement threads bwmarrin/discordgo#917

Closed

DRSchlaubi mentioned this pull request Apr 28, 2021

Track open Discord PR's to implement kordlib/kord#121

Open

1 task

discord unlocked this conversation Apr 28, 2021

Taucher2003 mentioned this pull request Apr 28, 2021

Implement support for the upcoming Threads discord-jda/JDA#1611

Closed

3 tasks

A5rocks reviewed Apr 28, 2021

View reviewed changes

Erk- mentioned this pull request Apr 28, 2021

Tracking issue: Threads twilight-rs/twilight#799

Closed

34 tasks

This was referenced Apr 28, 2021

API v9 (Threads Edition) shardlab/discordcr#14

Closed

Update to v8 shardlab/discordcr#9

Closed

Lulalaby mentioned this pull request Apr 28, 2021

Implement missing features DSharpPlus/DSharpPlus#825

Closed

37 tasks

ckohen reviewed Apr 28, 2021

View reviewed changes

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

ckohen reviewed Apr 29, 2021

View reviewed changes

docs/topics/Permissions.md Outdated Show resolved Hide resolved

DV8FromTheWorld reviewed Apr 29, 2021

View reviewed changes

cheesycod mentioned this pull request Apr 29, 2021

API v9 Rapptz/discord.py#6817

Closed

sayantan300 approved these changes Apr 29, 2021

View reviewed changes

FasterSpeeding reviewed Apr 29, 2021

View reviewed changes

docs/Change_Log.md Show resolved Hide resolved

ajpalkovic added 3 commits April 30, 2021 16:15

address some PR comments

62ec775

PUBLIC_THREAD -> GUILD_PUBLIC_THREAD & such

b57aa7d

undo use_guild_public_threads

71f9dda

ajpalkovic force-pushed the threads branch from 6db72e3 to 71f9dda Compare April 30, 2021 23:15

ajpalkovic merged commit 478af37 into master Apr 30, 2021

ajpalkovic deleted the threads branch April 30, 2021 23:23

Cryptex-github added a commit to Cryptex-github/discord-api-docs that referenced this pull request May 1, 2021

Revert "Document APIv9. (discord#2855)"

bb35a4c

This reverts commit 478af37.

benkaday3218 reviewed May 2, 2021

View reviewed changes

Nihlus reviewed May 3, 2021

View reviewed changes

docs/resources/Channel.md Show resolved Hide resolved

Nihlus added a commit to Remora/Remora.Discord that referenced this pull request May 3, 2021

Implement the v9 Discord API.

c26aec4

See discord/discord-api-docs#2855.

boehs mentioned this pull request May 4, 2021

Support for Public/Private Thread Channels serenity-rs/serenity#1270

Closed

HarmoGlace mentioned this pull request May 4, 2021

API v9 and threads serenity-rs/serenity#1319

Merged

Assassin-1234 reviewed May 5, 2021

View reviewed changes

james7132 mentioned this pull request May 9, 2021

Threads: Implement model twilight-rs/twilight#805

Merged

ckohen mentioned this pull request May 21, 2021

feat: api v9 and threads discordjs/discord-api-types#133

Merged

SiroTM mentioned this pull request Jun 6, 2021

feat(Threads): API v9, add rest support for Threads libraryofcode/dis.ts#31

Open

		\| message_count? \| integer \| an approximate count of messages in a thread, caps at 50 \|
		\| member_count? \| integer \| an approximate count of users in a thread, caps at 50 \|


		#### Thread List Sync

		Sent when the current user _gains_ access to a channel.


		### Syncing for the current user

		- A [Thread Members Update](#DOCS_TOPICS_GATEWAY/thread-members-update) Gateway Event is always sent when the current user is added to or removed from a thread.

Document APIv9. #2855

Document APIv9. #2855

Conversation

ajpalkovic commented Apr 28, 2021

This comment has been minimized.

This comment has been minimized.

xSke commented Apr 28, 2021 • edited Loading

devsnek commented Apr 28, 2021

FedorLap2006 commented Apr 28, 2021

A5rocks left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

A5rocks Apr 28, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lulalaby commented Apr 28, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sayantan300 left a comment

Choose a reason for hiding this comment

ajpalkovic commented Apr 30, 2021

Aericio commented May 1, 2021

benkaday3218 left a comment

Choose a reason for hiding this comment

Assassin-1234 left a comment

Choose a reason for hiding this comment

ghost commented May 14, 2021

xSke commented Apr 28, 2021 •

edited

Loading

A5rocks Apr 28, 2021 •

edited

Loading