Skip to content
Developers
Menu

API reference

Direct messages

One-to-one direct messages. A DM is a channel without a community; its messages, edits, deletes, history and acks use the message operations with the DM's ID, and anyone but its two participants gets 404.

Every path is relative to https://api.palloo.app/v1. Send a bot token as Authorization: Bearer palloo_bot_... unless the operation says otherwise; see Authentication.

On this page

List DM channels

GET /users/@me/channels Bot token: Call it with a bot token (people can call it too).

The caller's direct messages, newest activity first.

Ordered by the newest message, or by when the DM was opened for DMs without messages. Each carries the caller's read state.

Responses

200

The caller's DMs.

Body: DMChannelList

Example response (200)
{
  "channels": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "kind": "dm",
      "recipients": [
        {
          "id": {},
          "username": "string",
          "display_name": "string",
          "kind": {},
          "avatar": {},
          "avatar_dark": {}
        }
      ],
      "created_at": "2026-10-15T09:00:00Z",
      "last_message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "last_read_message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "mention_count": 0,
      "last_pin_timestamp": "2026-10-15T09:00:00Z"
    }
  ]
}
401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

Open DM channel

POST /users/@me/channels Bot token: Call it with a bot token (people can call it too).

Open the DM with a user, or get it if it exists.

There is exactly one DM per pair of users. An existing DM is returned (200) whatever the current settings, since both participants can always read it. A new one (201) needs what sending needs: the recipient has not blocked the caller and allows DMs from them (they are friends, or the recipient's direct_messages is server_members and they share a community), and the caller has not blocked the recipient. Bots can open DMs with users they share a community with, but not with other bots. Both participants' gateway sessions receive channel_create. Creating DMs is rate limited; getting existing ones is not.

Request body

application/json: OpenDMRequest (required)

Fields of the application/json request body
FieldTypeDescription
recipient_idRequired string
Example request body
{
  "recipient_id": "string"
}

Responses

200

The existing DM.

Body: DMChannelState

Example response (200)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "kind": "dm",
  "recipients": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "username": "string",
      "display_name": "string",
      "kind": "user",
      "avatar": "string",
      "avatar_dark": "string"
    }
  ],
  "created_at": "2026-10-15T09:00:00Z",
  "last_message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "last_read_message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "mention_count": 0,
  "last_pin_timestamp": "2026-10-15T09:00:00Z"
}
201

The new DM.

Body: DMChannelState

Example response (201)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "kind": "dm",
  "recipients": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "username": "string",
      "display_name": "string",
      "kind": "user",
      "avatar": "string",
      "avatar_dark": "string"
    }
  ],
  "created_at": "2026-10-15T09:00:00Z",
  "last_message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "last_read_message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "mention_count": 0,
  "last_pin_timestamp": "2026-10-15T09:00:00Z"
}
400

invalid_body: the body is not a single JSON object matching the schema.

Body: Error

401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

403

dm_not_allowed: the recipient does not accept DMs from the caller (a block looks the same), or bots_not_allowed: both are bots.

Body: Error

404

user_not_found.

Body: Error

409

cannot_target_self, or blocking_user: the caller blocked the recipient.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error