Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
8.4 KB
Raw Blame
---
# 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 |
| --- | --- | --- |
| &#123;channel_id&#125;<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.