Private channels
A private channel is a direct message between two accounts or a group DM. Its fields are in the channel object. These routes take a user session or a bot token, not an OAuth2 token.
Preloaded messages object
Section titled “Preloaded messages object”Each property name is the snowflake of one requested channel.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| {channel_id}1 | ?message object | The latest message you can read, or null when there is none |
1 Channels that aren't direct messages or group DMs are left out
Group DM unaddable recipient object
Section titled “Group DM unaddable recipient object”Create private channel returns an array of these as unaddable_recipients in a GROUP_DM_RECIPIENTS_NOT_ADDABLE error response.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| user_id | snowflake | The recipient that could not be added |
| reason | string | The unaddable reason |
Group DM unaddable reasons
Section titled “Group DM unaddable reasons”| Value | Name | Description |
|---|---|---|
| unknown_user | Unknown user | The recipient does not exist |
| not_friends | Not friends | You are not friends with the recipient |
| blocked | Blocked | You are a bot and share no guild with the recipient |
| group_dm_add_disabled | Group DM add disabled | The recipient's group DM add permission flags don't let you add them |
List private channels
Section titled “List private channels”GET/v1/users/@me/channelsReturns your open direct message and group DM channel objects, unordered and unpaginated. Each channel's recipients leaves out the caller.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | array[channel object] | Open private channels were returned |
The rate limit is 40 requests per 10 seconds, on the user:channels bucket.
Create private channel
Section titled “Create private channel”POST/v1/users/@me/channelsOpens a direct message with one account, or creates a group DM.
Send recipient_id to open a direct message or recipients to create a group DM. Opening a direct message you already have returns the same channel.
An account that is not verified gets 403 UNCLAIMED_ACCOUNT_CANNOT_JOIN_GROUP_DMS, UNCLAIMED_ACCOUNT_CANNOT_SEND_DIRECT_MESSAGES, DIRECT_MESSAGE_EMAIL_VERIFICATION_REQUIRED or ACCOUNT_VERIFICATION_REQUIRED.
When the instance community policy sets direct_messages_disabled, every request gets 400 DIRECT_MESSAGES_DISABLED.
New conversation limit
Section titled “New conversation limit”When your account is limited from starting new conversations, opening a direct message with someone who is not your friend returns 403 NEW_CONVERSATIONS_LIMITED, unless they have already sent a message there. Bots, staff and trusted accounts are never limited.
Direct messages
Section titled “Direct messages”Your own ID returns 400 CANNOT_DM_YOURSELF on recipient_id, and an unknown user returns 404 UNKNOWN_USER. Blocks don't stop you from opening a direct message, but Create message returns 400 CANNOT_SEND_MESSAGES_TO_USER when either of you has blocked the other.
Group DMs
Section titled “Group DMs”A limited account gets 403 ACCOUNT_LIMITED.
A group DM has at most max_group_dm_recipients participants including you (default 50), or the request returns 400 MAX_GROUP_DM_RECIPIENTS with max_recipients. Each participant must be in fewer than max_group_dms_per_user group DMs (default 150), or it returns 400 MAX_GROUP_DMS with max_group_dms.
A repeated ID returns 400 DUPLICATE_RECIPIENTS_NOT_ALLOWED and your own ID returns 400 CANNOT_ADD_YOURSELF_TO_GROUP_DM, both as field errors on recipients. If any recipient can't be added, the request returns 400 GROUP_DM_RECIPIENTS_NOT_ADDABLE with unaddable_recipients and the IDs that could be added in addable_recipients.
Request headers
Section titled “Request headers”| Field | Type | Description |
|---|---|---|
| X-Captcha-Token?1 | string | The solved ALTCHA challenge, see CAPTCHA handling |
1 Needed with recipients when the instance has CAPTCHA turned on, otherwise 400 CAPTCHA_REQUIRED or INVALID_CAPTCHA
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| recipient_id?1 | snowflake | The only recipient of a direct message |
| recipients?1 | array[snowflake] | The other participants of a group DM, excluding the caller (max 49) |
1 Send exactly one of the two
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | channel object | The direct message was opened or the group DM was created |
| 400 | error response | The request failed a check described above |
| 403 | error response | The account is not verified, is limited, or may not start a new conversation |
| 404 | error response | UNKNOWN_USER when recipient_id does not exist |
Side effects
Section titled “Side effects”A new direct message opens only for you. The other side opens when a message is sent or a call rings in it, when they open it, or when you become friends. A new group DM makes you the owner, sends Channel Create to every participant and posts a RECIPIENT_ADD message, with its Message Create event, for each other recipient.
The rate limit is 40 requests per 10 seconds, on the user:channels bucket. A request with recipients also uses the user:group_dm:create bucket, at 10 requests per hour.
Preload private channel messages
Section titled “Preload private channel messages”POST/v1/users/@me/preload-messagesReturns the latest message you can read in each requested channel as a preloaded messages object.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| channels | array[snowflake] | The private channels to preload (max 100) |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | preloaded messages object | The requested channels were resolved |
The rate limit is 40 requests per 10 seconds, on the user:preload_messages bucket.
Preload private channel messages by alias
Section titled “Preload private channel messages by alias”POST/v1/users/@me/channels/messages/preloadWorks the same as Preload private channel messages.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| channels | array[snowflake] | The private channels to preload (max 100) |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | preloaded messages object | The requested channels were resolved |
The rate limit is 40 requests per 10 seconds, on the user:preload_messages bucket.
Pin private channel
Section titled “Pin private channel”PUT/v1/users/@me/channels/{channel_id}/pinAdds a direct message or group DM to the end of your pinned list and sends you a User Pinned DMs Update Gateway event.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The channel is pinned |
| 400 | error response | CHANNEL_MUST_BE_DM_OR_GROUP_DM when the channel is another type |
The rate limit is 40 requests per 10 seconds, on the user:channels bucket.
Unpin private channel
Section titled “Unpin private channel”DELETE/v1/users/@me/channels/{channel_id}/pinRemoves a direct message or group DM from your pinned list and sends you a User Pinned DMs Update Gateway event.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The channel is not pinned |
| 400 | error response | CHANNEL_MUST_BE_DM_OR_GROUP_DM when the channel is another type |
The rate limit is 40 requests per 10 seconds, on the user:channels bucket.