Thread members

A thread member records that a user joined a thread. A thread has at most 1,000 members. Requests from users need the channel_threads client capability and otherwise return 404 NOT_FOUND. Every endpoint returns 400 INVALID_CHANNEL_TYPE when the channel is not a thread and 403 MISSING_ACCESS when you cannot view it.

Thread member object

Structure

Field	Type	Description
id?1	snowflake	The ID of the thread
user_id?1	snowflake	The ID of the user
join_timestamp	ISO8601 timestamp	The time the user last joined the thread
flags	integer	The thread member flags
muted?2	boolean	Whether the user muted the thread
mute_config?2	?guild mute configuration object	The mute expiry of the thread
member?3	guild member object	The guild member of the user

¹ Omitted on the member of a thread in Ready, Guild Create and Guild Sync

² Present only on the caller's own membership

³ Present when the request sets with_member and the user is still in the guild. Each added_members entry of Thread Members Update also has it

Example

{
  "id": "1501320100000000000",
  "user_id": "1501314428688992222",
  "join_timestamp": "2026-05-05T20:30:05.018Z",
  "flags": 3,
  "muted": false,
  "mute_config": null
}

Thread member flags

At most one of ALL_MESSAGES, ONLY_MENTIONS and NO_MESSAGES is set. With none set, the thread follows the notification level of its parent.

Value	Name	Description
1 << 0	HAS_INTERACTED1	The user sent a message in the thread or created it
1 << 1	ALL_MESSAGES	Notify the user of every message in the thread
1 << 2	ONLY_MENTIONS	Notify the user only of mentions in the thread
1 << 3	NO_MESSAGES	Notify the user of nothing in the thread

¹ A bot that creates a thread doesn't get this flag until it sends a message there

Join thread

PUT/v1/channels/{channel_id}/thread-members/@meBot

Adds you to a thread and sends a Thread Members Update event. You need to be able to view the thread, and to be a thread moderator if it is locked. Joining a locked thread also needs an enrolled authenticator when the guild MFA level is elevated, unless you own the guild.

Response

Status	Body	Condition
204	empty	The caller is a member
400	error response	THREAD_ARCHIVED when the thread is archived
400	error response	THREAD_LOCKED when the thread is locked and the caller is not a thread moderator
400	error response	MAX_THREAD_MEMBERS when the thread has 1,000 members
400	error response	TWO_FACTOR_REQUIRED when the caller needs an authenticator
403	error response	MISSING_ACCESS when the caller cannot view the thread

The rate limit is 10 requests per 10 seconds, on the channel:thread:member:put::channel_id bucket.

Add thread member

PUT/v1/channels/{channel_id}/thread-members/{user_id}Bot

Adds a guild member to a thread and sends a Thread Members Update event. You need SEND_MESSAGES_IN_THREADS. In a private thread that is not invitable, you or the target must be a thread moderator. When the guild MFA level is elevated and you don't own the guild, you need an enrolled authenticator to add someone to a locked thread. The same applies to adding someone who is not a thread moderator to that kind of private thread. A user_id of @me works like Join thread.

Response

Status	Body	Condition
204	empty	The target is a member
400	error response	THREAD_ARCHIVED, THREAD_LOCKED, MAX_THREAD_MEMBERS or TWO_FACTOR_REQUIRED, as for Join thread
403	error response	MISSING_ACCESS when the caller cannot view the thread or the target cannot view the parent
403	error response	MISSING_PERMISSIONS when the caller lacks SEND_MESSAGES_IN_THREADS
403	error response	MISSING_PERMISSIONS in a private thread that is not invitable when neither user is a thread moderator
403	error response	COMMUNICATION_DISABLED when the caller is timed out
404	error response	UNKNOWN_MEMBER when the target is not a guild member

Adding another user posts a RECIPIENT_ADD message that mentions the target and sends Message Create for it. The rate limit is 10 requests per 10 seconds, on the channel:thread:member:put::channel_id bucket.

Leave thread

DELETE/v1/channels/{channel_id}/thread-members/@meBot

Removes you from a thread and sends a Thread Members Update event.

Response

Status	Body	Condition
204	empty	The caller left the thread
400	error response	THREAD_ARCHIVED when the thread is archived
404	error response	UNKNOWN_THREAD_MEMBER when the caller is not a member

The rate limit is 10 requests per 10 seconds, on the channel:thread:member:delete::channel_id bucket.

Remove thread member

DELETE/v1/channels/{channel_id}/thread-members/{user_id}Bot

Removes a member from a thread and sends a Thread Members Update event. You need to be a thread moderator or the owner of the private thread. When the guild MFA level is elevated, you also need an enrolled authenticator unless you own the guild or the private thread. A user_id of @me or of the caller works like Leave thread.

Response

Status	Body	Condition
204	empty	The member was removed
400	error response	THREAD_ARCHIVED or TWO_FACTOR_REQUIRED, as for Join thread
403	error response	MISSING_PERMISSIONS when the caller is neither a thread moderator nor the owner of the private thread
403	error response	COMMUNICATION_DISABLED when the caller is timed out
404	error response	UNKNOWN_THREAD_MEMBER when the target is not a member

Fluxer posts a RECIPIENT_REMOVE message that mentions the target and sends Message Create for it. The rate limit is 10 requests per 10 seconds, on the channel:thread:member:delete::channel_id bucket.

Get thread member

GET/v1/channels/{channel_id}/thread-members/{user_id}Bot

Returns the thread member object of a user. Only bots can call it, and users get 404 NOT_FOUND.

Query parameters

Field	Type	Description
with_member?	boolean	Whether to include the guild member of the user (default false)

Response

Status	Body	Condition
200	thread member object	The member was returned
404	error response	UNKNOWN_THREAD_MEMBER when the user is not a member

The rate limit is 40 requests per 10 seconds, on the channel:thread:member:get::channel_id bucket.

List thread members

GET/v1/channels/{channel_id}/thread-membersBot

Returns the thread member objects of a thread in ascending user ID order. Only bots can call it, and users get 404 NOT_FOUND. User clients use the thread_member_lists option of Lazy Request.

Query parameters

Field	Type	Description
with_member?	boolean	Whether to include the guild member of each thread member (default false)
after?	snowflake	Return members with a user ID above this one
limit?	integer	The maximum number of members to return (1-100, default 100)

Response

Status	Body	Condition
200	array[thread member object]	The members were returned

The rate limit is 20 requests per 10 seconds, on the channel:thread:members:list::channel_id bucket.

Modify thread member settings

PATCH/v1/channels/{channel_id}/thread-members/@me/settings

Changes your notification settings for a thread you joined and sends a Thread Member Update event. While muted is true, you get no push notifications from the thread, including for mentions.

JSON body

Field	Type	Description
flags?1	integer	The notification thread member flags
muted?	boolean	Whether the thread is muted
mute_config?	?guild mute configuration input object	The mute expiry of the thread, or null to clear it

¹ Replaces the three notification flags and keeps HAS_INTERACTED. A value of 0 clears them

Response

Status	Body	Condition
200	thread member object	The settings changed
204	empty	The body matched the stored settings
400	error response	INVALID_THREAD_NOTIFICATION_SETTINGS when flags sets more than one notification flag or any other bit
403	error response	ACCESS_DENIED when the caller is a bot
404	error response	UNKNOWN_THREAD_MEMBER when the caller is not a member

The rate limit is 10 requests per 10 seconds, on the channel:thread:member:settings::channel_id bucket.