A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Private channels
description: List, create, preload and pin direct messages and group DMs.
---
import RouteHeader from '@/components/RouteHeader.astro';
A private channel is a direct message between two accounts or a group DM. Its fields are in the [channel object](/http-api/channels/#channel-object). These routes take a user session or a bot token, not an OAuth2 token.
## Preloaded messages object
Each property name is the [snowflake](/snowflakes/) of one requested channel.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| {channel_id}<sup>1</sup> | ?[message](/http-api/messages/#message-object) object | The latest message you can read, or null when there is none |
<sup>1</sup> Channels that aren't direct messages or group DMs are left out
## Group DM unaddable recipient object
[Create private channel](#create-private-channel) returns an array of these as `unaddable_recipients` in a `GROUP_DM_RECIPIENTS_NOT_ADDABLE` [error response](/http-api/#error-response).
### Structure
| Field | Type | Description |
| --- | --- | --- |
| user_id | snowflake | The recipient that could not be added |
| reason | string | The [unaddable reason](#group-dm-unaddable-reasons) |
## 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](/http-api/users/#group-dm-add-permission-flags) don't let you add them |
## List private channels
<RouteHeader method="GET" path="/v1/users/@me/channels" bot />
Returns your open direct message and group DM [channel](/http-api/channels/#channel-object) objects, unordered and unpaginated. Each channel's `recipients` leaves out the caller.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[channel](/http-api/channels/#channel-object) object] | Open private channels were returned |
The rate limit is 40 requests per 10 seconds, on the `user:channels` bucket.
## Create private channel
<RouteHeader method="POST" path="/v1/users/@me/channels" bot />
Opens 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](/http-api/users/#account-tiers) 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](/http-api/instance/#community-policy-object) sets `direct_messages_disabled`, every request gets 400 `DIRECT_MESSAGES_DISABLED`.
### 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
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](/http-api/messages/#create-message) returns 400 `CANNOT_SEND_MESSAGES_TO_USER` when either of you has blocked the other.
### Group DMs
A [limited](/http-api/users/#account-limitation) 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`](#group-dm-unaddable-recipient-object) and the IDs that could be added in `addable_recipients`.
### Request headers
| Field | Type | Description |
| --- | --- | --- |
| X-Captcha-Token?<sup>1</sup> | string | The solved ALTCHA challenge, see [CAPTCHA handling](/topics/captcha/) |
<sup>1</sup> Needed with `recipients` when the instance has CAPTCHA turned on, otherwise 400 `CAPTCHA_REQUIRED` or `INVALID_CAPTCHA`
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| recipient_id?<sup>1</sup> | snowflake | The only recipient of a direct message |
| recipients?<sup>1</sup> | array[snowflake] | The other participants of a group DM, excluding the caller (max 49) |
<sup>1</sup> Send exactly one of the two
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [channel](/http-api/channels/#channel-object) object | The direct message was opened or the group DM was created |
| 400 | [error response](/http-api/#error-response) | The request failed a check described above |
| 403 | [error response](/http-api/#error-response) | The account is not verified, is limited, or may not start a new conversation |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_USER` when `recipient_id` does not exist |
### 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](/gateway/events/#channel-create) to every participant and posts a [RECIPIENT_ADD](/http-api/messages/#message-types) message, with its [Message Create](/gateway/events/#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
<RouteHeader method="POST" path="/v1/users/@me/preload-messages" bot />
Returns the latest message you can read in each requested channel as a [preloaded messages](#preloaded-messages-object) object.
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| channels | array[snowflake] | The private channels to preload (max 100) |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [preloaded messages](#preloaded-messages-object) 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
<RouteHeader method="POST" path="/v1/users/@me/channels/messages/preload" bot />
Works the same as [Preload private channel messages](#preload-private-channel-messages).
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| channels | array[snowflake] | The private channels to preload (max 100) |
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [preloaded messages](#preloaded-messages-object) object | The requested channels were resolved |
The rate limit is 40 requests per 10 seconds, on the `user:preload_messages` bucket.
## Pin private channel
<RouteHeader method="PUT" path="/v1/users/@me/channels/{channel_id}/pin" bot />
Adds a direct message or group DM to the end of your pinned list and sends you a [User Pinned DMs Update](/gateway/events/#user-pinned-dms-update) Gateway event.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The channel is pinned |
| 400 | [error response](/http-api/#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
<RouteHeader method="DELETE" path="/v1/users/@me/channels/{channel_id}/pin" bot />
Removes a direct message or group DM from your pinned list and sends you a [User Pinned DMs Update](/gateway/events/#user-pinned-dms-update) Gateway event.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The channel is not pinned |
| 400 | [error response](/http-api/#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.