Skip to content
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.

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

Forum post (thread) message_count updates #5206

Merged
merged 5 commits into from
Jul 19, 2022

Conversation

Tin
Copy link
Contributor

@Tin Tin commented Jul 18, 2022

Document API fields updates around forum post (thread)'s new message counter capability.

@@ -28,13 +28,14 @@ Represents a guild or DM channel within Discord.
| last_pin_timestamp? | ?ISO8601 timestamp | when the last pinned message was pinned. This may be `null` in events such as `GUILD_CREATE` when a message is not pinned. |
| rtc_region? | ?string | [voice region](#DOCS_RESOURCES_VOICE/voice-region-object) id for the voice channel, automatic when set to null |
| video_quality_mode? | integer | the camera [video quality mode](#DOCS_RESOURCES_CHANNEL/channel-object-video-quality-modes) of the voice channel, 1 when not present |
| message_count? | integer | an approximate count of messages in a thread, stops counting at 50 |
| message_count? | integer | count of messages (not including starter message and deleted messsages) in a thread, stops counting at 100_000 (if the thread is created before July 1, 2022, it stops at 50) |
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
| message_count? | integer | count of messages (not including starter message and deleted messsages) in a thread, stops counting at 100_000 (if the thread is created before July 1, 2022, it stops at 50) |
| message_count? | integer | count of messages (not including starter message and deleted messages) in a thread, stops counting at 100000 (if the thread is created before July 1, 2022, it stops at 50) |

Copy link
Contributor

Choose a reason for hiding this comment

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

it's easier to read with the underscore

Copy link
Contributor

@splatterxl splatterxl Jul 18, 2022

Choose a reason for hiding this comment

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

Suggested change
| message_count? | integer | count of messages (not including starter message and deleted messsages) in a thread, stops counting at 100_000 (if the thread is created before July 1, 2022, it stops at 50) |
| message_count? | integer | total number of messages in the thread excluding starter message, stops counting at 100_000 (or if the thread was created before 1 July 2022, 50) |

| member_count? | integer | an approximate count of users in a thread, stops counting at 50 |
| thread_metadata? | a [thread metadata](#DOCS_RESOURCES_CHANNEL/thread-metadata-object) object | thread-specific fields not needed by other channels |
| member? | a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object | thread member object for the current user, if they have joined the thread, only included on certain API endpoints |
| default_auto_archive_duration? | integer | default duration that the clients (not the API) will use for newly created threads, in minutes, to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080 |
| permissions? | string | computed permissions for the invoking user in the channel, including overwrites, only included when part of the `resolved` data received on a slash command interaction |
| flags? | integer | [channel flags](#DOCS_RESOURCES_CHANNEL/channel-object-channel-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| total_message_sent? | integer | count of total messages ever sent in a thread, it's similar to `message_count` on message creation, but decrement on message deletion. |
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
| total_message_sent? | integer | count of total messages ever sent in a thread, it's similar to `message_count` on message creation, but decrement on message deletion. |
| total_message_sent? | integer | count of total messages ever sent in a thread, it's similar to `message_count` on message creation, but decrement on message deletion |

Comment on lines 38 to 39
- `message_count` and `total_message_sent` store messages count in a thread. The difference is that the `message_count` decrement when there's message deleted, but `total_message_count` will not change in this case. They stop
counting at 100_000. (The UI shows "100k+", and then it will stop counting) Thread before July 1, 2022 caps at 50.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
- `message_count` and `total_message_sent` store messages count in a thread. The difference is that the `message_count` decrement when there's message deleted, but `total_message_count` will not change in this case. They stop
counting at 100_000. (The UI shows "100k+", and then it will stop counting) Thread before July 1, 2022 caps at 50.
- `message_count` and `total_message_sent` store messages count in a thread. The difference is that the `message_count` decrement when there's message deleted, but `total_message_count` will not change in this case. They stop counting at 100000 (the UI shows "100k+", and then it will stop counting). Thread before July 1, 2022 caps at 50.

Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
- `message_count` and `total_message_sent` store messages count in a thread. The difference is that the `message_count` decrement when there's message deleted, but `total_message_count` will not change in this case. They stop
counting at 100_000. (The UI shows "100k+", and then it will stop counting) Thread before July 1, 2022 caps at 50.
- `message_count` and `total_message_sent` store the amount of messages in a thread. The difference is that when a message is deleted, `message_count` is decremented, but `total_message_sent` will not. Both of these properties stop counting at 100_000 (the UI shows 100k+), except in threads created before July 1, 2022, in which case it stops at 50.

@@ -28,13 +28,14 @@ Represents a guild or DM channel within Discord.
| last_pin_timestamp? | ?ISO8601 timestamp | when the last pinned message was pinned. This may be `null` in events such as `GUILD_CREATE` when a message is not pinned. |
| rtc_region? | ?string | [voice region](#DOCS_RESOURCES_VOICE/voice-region-object) id for the voice channel, automatic when set to null |
| video_quality_mode? | integer | the camera [video quality mode](#DOCS_RESOURCES_CHANNEL/channel-object-video-quality-modes) of the voice channel, 1 when not present |
| message_count? | integer | an approximate count of messages in a thread, stops counting at 50 |
| message_count? | integer | count of messages (not including starter message and deleted messsages) in a thread, stops counting at 100_000 (if the thread is created before July 1, 2022, it stops at 50) |
Copy link
Contributor

Choose a reason for hiding this comment

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

I don't think we should document the upper limit, it's something that can change in the future, you've even expressed desires to change it, and there's always push back when changing documented things. It's probably fine t say it'll always be a 32 bit integer though

| member_count? | integer | an approximate count of users in a thread, stops counting at 50 |
| thread_metadata? | a [thread metadata](#DOCS_RESOURCES_CHANNEL/thread-metadata-object) object | thread-specific fields not needed by other channels |
| member? | a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object | thread member object for the current user, if they have joined the thread, only included on certain API endpoints |
| default_auto_archive_duration? | integer | default duration that the clients (not the API) will use for newly created threads, in minutes, to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080 |
| permissions? | string | computed permissions for the invoking user in the channel, including overwrites, only included when part of the `resolved` data received on a slash command interaction |
| flags? | integer | [channel flags](#DOCS_RESOURCES_CHANNEL/channel-object-channel-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| total_message_sent? | integer | count of total messages ever sent in a thread, it's similar to `message_count` on message creation, but decrement on message deletion. |
Copy link
Contributor

Choose a reason for hiding this comment

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

Isn't this wrong, it's never decremented, right?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

missed the "will not" 🤦

@onerandomusername
Copy link
Contributor

What is the purpose of position, genuine question. I can't think of a usecase off the top of my head for bot devs.

@@ -266,6 +268,7 @@ Represents a message sent in a channel within Discord.
| components? | Array of [message components](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) | sent if the message contains components like buttons, action rows, or other interactive components |
| sticker_items? | array of [message sticker item objects](#DOCS_RESOURCES_STICKER/sticker-item-object) | sent if the message contains stickers |
| stickers? | array of [sticker](#DOCS_RESOURCES_STICKER/sticker-object) objects | **Deprecated** the stickers sent with the message |
| position? | integer | position of the message in a forum post when it was sent, it will not change upon any message deletion in the parent post |
Copy link
Contributor

Choose a reason for hiding this comment

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

I think this is for all threads, not just forum posts, right?
I'd suggest: "A generally increasing integer (there may be gaps or duplicates) that represents the approximate position of the message in a thread."

Copy link
Contributor

@onerandomusername onerandomusername left a comment

Choose a reason for hiding this comment

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

Should there be a note on the gateway reference for Thread Update which mentions that total_message_sent and message_count do not send THREAD_UPDATE events? This would be in line with the documentation surrounding last_message_id.

| member_count? | integer | an approximate count of users in a thread, stops counting at 50 |
| thread_metadata? | a [thread metadata](#DOCS_RESOURCES_CHANNEL/thread-metadata-object) object | thread-specific fields not needed by other channels |
| member? | a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object | thread member object for the current user, if they have joined the thread, only included on certain API endpoints |
| default_auto_archive_duration? | integer | default duration that the clients (not the API) will use for newly created threads, in minutes, to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080 |
| permissions? | string | computed permissions for the invoking user in the channel, including overwrites, only included when part of the `resolved` data received on a slash command interaction |
| flags? | integer | [channel flags](#DOCS_RESOURCES_CHANNEL/channel-object-channel-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| total_message_sent? | integer | count of total messages ever sent in a thread, it's similar to `message_count` on message creation, but decrement on message deletion. |
Copy link
Contributor

@splatterxl splatterxl Jul 18, 2022

Choose a reason for hiding this comment

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

Suggested change
| total_message_sent? | integer | count of total messages ever sent in a thread, it's similar to `message_count` on message creation, but decrement on message deletion. |
| total_message_sent? | integer | count of all messages ever sent in the thread, does not decrement on message deletion |

Also, shouldn't this be named total_messages_sent as a plural?

@@ -34,7 +34,8 @@ Since threads are a new [type of channel](#DOCS_RESOURCES_CHANNEL/channel-object

Additionally, there are a few new fields that are only available on threads:

- `message_count` and `member_count` store an approximate count, but they stop counting at 50 (these are only used in our UI, so likely are not valuable to bots)
- `member_count` store an approximate member count, but it stop counting at 50 (these are only used in our UI, so likely are not valuable to bots)
- `message_count` and `total_message_sent` store the amount of messages in a thread. The difference is that when a message is deleted, `message_count` is decremented, but `total_message_count` will not be. (threads created before July 1, 2022 stops counting both value at 50).
Copy link
Contributor

@advaith1 advaith1 Jul 18, 2022

Choose a reason for hiding this comment

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

Suggested change
- `message_count` and `total_message_sent` store the amount of messages in a thread. The difference is that when a message is deleted, `message_count` is decremented, but `total_message_count` will not be. (threads created before July 1, 2022 stops counting both value at 50).
- `message_count` and `total_message_sent` store the number of messages in a thread. The difference is that when a message is deleted, `message_count` is decremented, but `total_message_sent` will not be. (threads created before July 1, 2022 stop counting both values at 50).

Copy link
Contributor

@advaith1 advaith1 Jul 18, 2022

Choose a reason for hiding this comment

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

says total_message_count here too

Comment on lines 31 to 38
| message_count? | integer | amount of messages (not including the initial message or deleted messages) in a thread (if the thread was created before July 1, 2022, it stops counting at 50) |
| member_count? | integer | an approximate count of users in a thread, stops counting at 50 |
| thread_metadata? | a [thread metadata](#DOCS_RESOURCES_CHANNEL/thread-metadata-object) object | thread-specific fields not needed by other channels |
| member? | a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object | thread member object for the current user, if they have joined the thread, only included on certain API endpoints |
| default_auto_archive_duration? | integer | default duration that the clients (not the API) will use for newly created threads, in minutes, to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080 |
| permissions? | string | computed permissions for the invoking user in the channel, including overwrites, only included when part of the `resolved` data received on a slash command interaction |
| flags? | integer | [channel flags](#DOCS_RESOURCES_CHANNEL/channel-object-channel-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| total_message_sent? | integer | amount of messages ever sent in a thread, it's similar to `message_count` on message creation, but will not decrement the amount when a message is deleted |
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
| message_count? | integer | amount of messages (not including the initial message or deleted messages) in a thread (if the thread was created before July 1, 2022, it stops counting at 50) |
| member_count? | integer | an approximate count of users in a thread, stops counting at 50 |
| thread_metadata? | a [thread metadata](#DOCS_RESOURCES_CHANNEL/thread-metadata-object) object | thread-specific fields not needed by other channels |
| member? | a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object | thread member object for the current user, if they have joined the thread, only included on certain API endpoints |
| default_auto_archive_duration? | integer | default duration that the clients (not the API) will use for newly created threads, in minutes, to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080 |
| permissions? | string | computed permissions for the invoking user in the channel, including overwrites, only included when part of the `resolved` data received on a slash command interaction |
| flags? | integer | [channel flags](#DOCS_RESOURCES_CHANNEL/channel-object-channel-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| total_message_sent? | integer | amount of messages ever sent in a thread, it's similar to `message_count` on message creation, but will not decrement the amount when a message is deleted |
| message_count? | integer | amount of messages (not including the initial message or deleted messages) in a thread (if the thread was created before July 1, 2022, it stops counting at 50) |
| member_count? | integer | an approximate count of users in a thread, stops counting at 50 |
| thread_metadata? | a [thread metadata](#DOCS_RESOURCES_CHANNEL/thread-metadata-object) object | thread-specific fields not needed by other channels |
| member? | a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object | thread member object for the current user, if they have joined the thread, only included on certain API endpoints |
| default_auto_archive_duration? | integer | default duration that the clients (not the API) will use for newly created threads, in minutes, to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080 |
| permissions? | string | computed permissions for the invoking user in the channel, including overwrites, only included when part of the `resolved` data received on a slash command interaction |
| flags? | integer | [channel flags](#DOCS_RESOURCES_CHANNEL/channel-object-channel-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| total_message_sent? | integer | amount of messages ever sent in a thread, it's similar to `message_count` on message creation, but will not decrement the amount when a message is deleted |

table formatting

@Tin
Copy link
Contributor Author

Tin commented Jul 18, 2022

@splatterxl @advaith1 @onerandomusername @MidSpike @vvito7 @ajpalkovic Thanks for the reviews, let me know if this new version makes sense.

@Tin Tin requested a review from ajpalkovic July 18, 2022 23:27
@@ -34,7 +34,8 @@ Since threads are a new [type of channel](#DOCS_RESOURCES_CHANNEL/channel-object

Additionally, there are a few new fields that are only available on threads:

- `message_count` and `member_count` store an approximate count, but they stop counting at 50 (these are only used in our UI, so likely are not valuable to bots)
- `member_count` store an approximate member count, but it stop counting at 50 (these are only used in our UI, so likely are not valuable to bots)
Copy link
Contributor

Choose a reason for hiding this comment

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

store -> stores
stop -> stops

Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
- `member_count` store an approximate member count, but it stop counting at 50 (these are only used in our UI, so likely are not valuable to bots)
- `member_count` stores an approximate member count, but it stops counting at 50 (this is only used in our UI, so it is likely not valuable to bots)

edits the note too

@@ -183,6 +184,7 @@ Listed below are some of the important details of forum channels and are safe to
- The API to create a thread in a forum will create _both_ a thread and message in the same call, and as such requires passing in parameters for both the thread and message. The name and behavior of parameters is the same as they are for the existing create thread/message endpoints to simplify integrating with it.
- The message created by that API call will have the same id as the thread.
- The `last_message_id` field on the forum channel object tracks the id of the most recently created thread. It has the same behavior and requirements as it does for messages, namely that you will not receive a `CHANNEL_UPDATE` when it is changed. Instead clients should update the value when receiving [Thread Create](#DOCS_TOPICS_GATEWAY/thread-create).
- The `message_count` and `total_message_count` will increment on `MESSAGE_CREATE` and will decrement on `MESSAGE_DELETE`/`MESSAGE_DELETE_BULK`. There will be no `CHANNEL_UPDATE` event through gateway notifying those fields' changes (similar to `last_message_id` changes). Clients should update those values when receiving corresponding events.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
- The `message_count` and `total_message_count` will increment on `MESSAGE_CREATE` and will decrement on `MESSAGE_DELETE`/`MESSAGE_DELETE_BULK`. There will be no `CHANNEL_UPDATE` event through gateway notifying those fields' changes (similar to `last_message_id` changes). Clients should update those values when receiving corresponding events.
- The `message_count` and `total_message_sent` will increment on `MESSAGE_CREATE` and will decrement on `MESSAGE_DELETE`/`MESSAGE_DELETE_BULK`. There will be no `CHANNEL_UPDATE` event through gateway notifying those fields' changes (similar to `last_message_id` changes). Clients should update those values when receiving corresponding events.

mistake in field name

Copy link
Contributor Author

Choose a reason for hiding this comment

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

oops

@splatterxl
Copy link
Contributor

lgtm

@Tin Tin force-pushed the forum-channel/message-counter-update branch from 4c4f147 to ebeee7b Compare July 19, 2022 15:41
@Tin Tin merged commit cdeb372 into main Jul 19, 2022
@Tin Tin deleted the forum-channel/message-counter-update branch July 19, 2022 15:44
@7596ff 7596ff mentioned this pull request Jul 19, 2022
10 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants