Skip to content
Developers
Menu

API reference

Messages

Messages in text channels, threads and DMs. Creating, editing and deleting a message also sends a gateway event to every member who can view the channel (in a DM, to both participants). Mentions (<@USER_ID>, <@&ROLE_ID>, @everyone, @here) are parsed by the server when a message is created or edited. Each user has a read state per channel (the last message read and the number of unread pings), cleared with the ack operations.

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 messages

GET /channels/{id}/messages Bot token: Call it with a bot token (people can call it too).

A page of messages in a text channel. Requires View Channel.

Without Read Message History the page is always empty: the member only sees messages that arrive over the gateway while connected.

Use at most one cursor:

  • none: the newest messages, newest first.
  • before: messages older than that ID, newest first. Use the last ID of the page to go further back.
  • after: messages newer than that ID, oldest first. Use the last ID of the page to go forward. This is how clients catch up after reconnecting to the gateway.
  • around: up to limit messages centered on that ID (the message itself, if it still exists, and the ones after it fill the newer half), newest first.

A page shorter than limit means there is nothing more in that direction.

Required permissions

Requires View Channel.

Parameters

Parameters of List messages
Name In Type Description
id Required path string

Channel ID.
before query ID

A ULID. Sorts lexically in creation order.

pattern ^[0-9A-HJKMNP-TV-Z]{26}$
after query ID

A ULID. Sorts lexically in creation order.

pattern ^[0-9A-HJKMNP-TV-Z]{26}$
around query ID

A ULID. Sorts lexically in creation order.

pattern ^[0-9A-HJKMNP-TV-Z]{26}$
limit query integer

at least 1; at most 100; default 50

Responses

200

One page of messages.

Body: MessageList

Example response (200)
{
  "messages": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "author": {
        "id": {},
        "username": "string",
        "display_name": "string",
        "kind": "user",
        "avatar": {},
        "avatar_dark": {}
      },
      "webhook_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "content": "string",
      "attachments": [
        {
          "id": {},
          "filename": "string",
          "description": "string",
          "content_type": "string",
          "size": 1,
          "url": "string",
          "thumbnail_url": "string",
          "width": 0,
          "height": 0,
          "placeholder": "string",
          "spoiler": false,
          "risk": {},
          "sensitive": {},
          "quarantined": false
        }
      ],
      "sticker_items": [
        {
          "id": "string",
          "name": "string",
          "format": "string",
          "animated": false,
          "community_id": "string",
          "pack_id": "string",
          "hash": "string",
          "available": false
        }
      ],
      "gif_url": "string",
      "created_at": "2026-10-15T09:00:00Z",
      "edited_at": "2026-10-15T09:00:00Z",
      "mentions": [
        {
          "id": {},
          "username": "string",
          "display_name": "string",
          "kind": {},
          "avatar": {},
          "avatar_dark": {}
        }
      ],
      "mention_roles": [
        "01J9ZQ3V5K8M2N4P6R8T0W2Y4A"
      ],
      "mention_everyone": false,
      "mention_here": false,
      "interaction": {
        "id": {},
        "name": "string",
        "user": {}
      },
      "ephemeral": false,
      "nonce": "string",
      "kind": "default",
      "pinned": false,
      "reactions": [
        {
          "emoji": {},
          "count": 1,
          "me": false
        }
      ],
      "message_reference": {
        "message_id": {},
        "channel_id": {}
      },
      "thread": {
        "id": {},
        "community_id": {},
        "name": "string",
        "kind": {},
        "position": 0,
        "parent_id": "string",
        "topic": {},
        "created_at": "2026-10-15T09:00:00Z",
        "overwrites": [],
        "owner_id": {},
        "message_count": 0,
        "member_count": 0,
        "thread_metadata": {},
        "user_limit": 0,
        "bitrate": 8000,
        "age_restricted": false
      },
      "referenced_message": {},
      "auto_moderation": {
        "rule_id": {},
        "rule_name": "string",
        "trigger_type": {},
        "channel_id": {},
        "message_id": "string",
        "blocked": false,
        "edit": false,
        "matched_keyword": "string",
        "matched_content": "string",
        "content": "string",
        "content_hidden": false,
        "content_removed": false,
        "attachments": [],
        "timeout_seconds": 0,
        "timeout_until": "2026-10-15T09:00:00Z"
      }
    }
  ]
}
400

invalid_query: more than one cursor, a cursor that is not a message ID, or limit not an integer from 1 to 100.

Body: Error

401

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

Body: Error

WWW-Authenticate header.

404

channel_not_found: no such channel, or the caller is not a member of its community or cannot view the channel.

Body: Error

409

channel_not_text: messages only exist in text channels.

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

Send message

POST /channels/{id}/messages Bot token: Call it with a bot token (people can call it too).

Send a message to a text channel or DM. Requires Send Messages in it; bots included.

In a DM the caller must be a participant, must not have blocked the other participant, and the other participant must allow DMs from the caller; this is checked on every send.

Required permissions

Requires Send Messages in it; bots included.

Parameters

Parameters of Send message
Name In Type Description
id Required path string

Channel ID.

Request body

application/json: CreateMessageRequest (required)

Fields of the application/json request body
FieldTypeDescription
content string

Trailing whitespace is removed and line breaks are normalized to \n; then 1 to 4000 characters, or empty when the message has attachments. Newlines, tabs and bidirectional formatting characters are allowed (right-to-left scripts need them); other control characters are not.
nonce string

Optional, up to 64 printable ASCII characters (no spaces), echoed back in the response and in the message_create event. Every member of the community sees it in the event. An empty string is the same as leaving it out.

at most 64 characters
attachments array of AttachmentRef

Finalized uploads to attach. Needs Attach Files as well as Send Messages.

at most 10 items
message_reference ReplyReference
allowed_mentions AllowedMentions
sticker_ids array of string

At most one sticker, as on Discord, with optional content: a built-in sticker (such as pip_hello) anywhere, or a sticker of this channel's own server. Another server's sticker is refused with 403 sticker_not_usable, and every sticker while the stickers flag is off with 403 stickers_disabled.

at most 1 items
gif_url string

Set by the GIF picker only: the media URL of the chosen GIF, which content must also contain. It must be an https URL on the provider's media hosts ending in .gif, .webp or .mp4, and the gifs flag must be on for the sender; otherwise 400 invalid_gif. The message then carries gif_url and clients embed it; a provider URL pasted without this stays a plain link.

at most 2048 characters
Example request body
{
  "content": "string",
  "nonce": "string",
  "attachments": [
    {
      "upload_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "filename": "string",
      "description": "string",
      "spoiler": false
    }
  ],
  "message_reference": {
    "message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "fail_if_not_exists": true
  },
  "allowed_mentions": {
    "replied_user": false
  },
  "sticker_ids": [
    "string"
  ],
  "gif_url": "string"
}

Responses

201

Sent. The response carries nonce when the request did.

Body: Message

Example response (201)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "author": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "username": "string",
    "display_name": "string",
    "kind": "user",
    "avatar": "string",
    "avatar_dark": "string"
  },
  "webhook_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "content": "string",
  "attachments": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "filename": "string",
      "description": "string",
      "content_type": "string",
      "size": 1,
      "url": "string",
      "thumbnail_url": "string",
      "width": 0,
      "height": 0,
      "placeholder": "string",
      "spoiler": false,
      "risk": "none",
      "sensitive": "none",
      "quarantined": false
    }
  ],
  "sticker_items": [
    {
      "id": "string",
      "name": "string",
      "format": "string",
      "animated": false,
      "community_id": "string",
      "pack_id": "string",
      "hash": "string",
      "available": false
    }
  ],
  "gif_url": "string",
  "created_at": "2026-10-15T09:00:00Z",
  "edited_at": "2026-10-15T09:00:00Z",
  "mentions": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "username": "string",
      "display_name": "string",
      "kind": "user",
      "avatar": "string",
      "avatar_dark": "string"
    }
  ],
  "mention_roles": [
    "01J9ZQ3V5K8M2N4P6R8T0W2Y4A"
  ],
  "mention_everyone": false,
  "mention_here": false,
  "interaction": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "name": "string",
    "user": {
      "id": {},
      "username": "string",
      "display_name": "string",
      "kind": {},
      "avatar": {},
      "avatar_dark": {}
    }
  },
  "ephemeral": false,
  "nonce": "string",
  "kind": "default",
  "pinned": false,
  "reactions": [
    {
      "emoji": {
        "id": "string",
        "name": "string"
      },
      "count": 1,
      "me": false
    }
  ],
  "message_reference": {
    "message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A"
  },
  "thread": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "name": "string",
    "kind": "text",
    "position": 0,
    "parent_id": "string",
    "topic": "string",
    "created_at": "2026-10-15T09:00:00Z",
    "overwrites": [
      {
        "type": "role",
        "id": {},
        "allow": {},
        "deny": {}
      }
    ],
    "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "message_count": 0,
    "member_count": 0,
    "thread_metadata": {
      "archived": false,
      "auto_archive_duration": 60,
      "archive_timestamp": "2026-10-15T09:00:00Z",
      "locked": false,
      "invitable": false,
      "create_timestamp": "2026-10-15T09:00:00Z"
    },
    "user_limit": 0,
    "bitrate": 8000,
    "age_restricted": false
  },
  "referenced_message": {},
  "auto_moderation": {
    "rule_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "rule_name": "string",
    "trigger_type": "keyword",
    "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "message_id": "string",
    "blocked": false,
    "edit": false,
    "matched_keyword": "string",
    "matched_content": "string",
    "content": "string",
    "content_hidden": false,
    "content_removed": false,
    "attachments": [
      "string"
    ],
    "timeout_seconds": 0,
    "timeout_until": "2026-10-15T09:00:00Z"
  }
}
400

invalid_body, invalid_content, invalid_nonce, or auto_moderation_blocked: an AutoMod rule refused the message. That error carries auto_moderation with the trigger type and the community's custom message, and a message to show as the notice under the composer. For replies: invalid_reference (the reference names another channel), reference_not_found (no such message in this channel and fail_if_not_exists is not false) or system_message (the message replied to is a system message).

Body: Error

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission: no Send Messages in the channel (or, for a reply, no Read Message History), with missing_permissions naming the bits the caller lacks, timed_out: the caller is timed out in this community, with timeout_until, dm_not_allowed: the other participant of the DM does not accept messages from the caller (a block looks the same), or replies_disabled: the request has message_reference and the replies flag is off for this server (in a DM, for the caller).

Body: Error

404

channel_not_found: no such channel, or the caller is not a member of its community or cannot view the channel.

Body: Error

409

channel_not_text: a voice channel, or blocking_user: the caller blocked the other participant of the DM.

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

Ack message

POST /channels/{id}/messages/{messageID}/ack Bot token: Call it with a bot token (people can call it too).

Mark a channel read up to a message. Requires View Channel.

Sets the caller's last_read_message_id for the channel to the message, unless it already points at a newer one (the read position never moves backward), and sets mention_count to 0 either way. The caller's other gateway sessions receive message_ack. Clients should send at most about one ack per channel per second.

Required permissions

Requires View Channel.

Parameters

Parameters of Ack message
Name In Type Description
id Required path string

Channel ID.
messageID Required path string

Message ID. The message must be in the channel.

Responses

200

The read state after the ack.

Body: ReadState

Example response (200)
{
  "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "last_read_message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "mention_count": 0
}
401

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

Body: Error

WWW-Authenticate header.

403

terms_acceptance_required: the instance's terms of service changed (or were never accepted) and this account has not accepted the current version. Show the terms and call POST /users/@me/terms, then retry.

Body: Error

404

channel_not_found: no such channel, or the caller cannot view it. message_not_found: the message does not exist in this channel.

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

List pins

GET /channels/{id}/pins Bot token: Call it with a bot token (people can call it too).

The pinned messages of a text channel or DM, newest pin first. Requires View Channel.

At most 50. Without Read Message History the list is always empty, as on Discord. Categories and voice channels have no messages (409 channel_not_text).

Required permissions

Requires View Channel.

Parameters

Parameters of List pins
Name In Type Description
id Required path string

Channel ID.

Responses

200

The pins.

Body: PinList

Example response (200)
{
  "pins": [
    {
      "pinned_at": "2026-10-15T09:00:00Z",
      "message": {
        "id": {},
        "channel_id": {},
        "community_id": {},
        "author": {},
        "webhook_id": {},
        "content": "string",
        "attachments": [],
        "sticker_items": [],
        "gif_url": "string",
        "created_at": "2026-10-15T09:00:00Z",
        "edited_at": "2026-10-15T09:00:00Z",
        "mentions": [],
        "mention_roles": [],
        "mention_everyone": false,
        "mention_here": false,
        "interaction": {},
        "ephemeral": false,
        "nonce": "string",
        "kind": "default",
        "pinned": false,
        "reactions": [],
        "message_reference": {},
        "thread": {},
        "referenced_message": {},
        "auto_moderation": {}
      }
    }
  ]
}
401

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

Body: Error

WWW-Authenticate header.

404

channel_not_found: no such channel, or the caller is not a member of its community or cannot view the channel.

Body: Error

409

channel_not_text: messages only exist in text channels.

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

Pin message

PUT /channels/{id}/pins/{messageID} Bot token: Call it with a bot token (people can call it too).

Pin a message of this channel. Requires View Channel, Read Message History and Manage Messages; in a DM, either participant can pin while they can still send there.

A channel holds at most 50 pins. Pinning posts a channel_pinned_message system message by the caller (who reads it as already read), and sends message_update with pinned: true, channel_pins_update and that message_create. In a community it is recorded in the moderation log as message.pin. Pinning a message that is already pinned changes nothing and answers 204. Shares the rate limit of sending messages.

Required permissions

Requires View Channel, Read Message History and Manage Messages; in a DM, either participant can pin while they can still send there.

Parameters

Parameters of Pin message
Name In Type Description
id Required path string

Channel ID.
messageID Required path string

Message ID. The message must be in the channel.

Responses

204

Pinned, or already pinned.

400

system_message: system messages cannot be pinned.

Body: Error

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission: no Manage Messages or Read Message History in the channel, timed_out, or dm_not_allowed: the other participant of the DM does not accept messages from the caller.

Body: Error

404

channel_not_found: no such channel, or the caller cannot view it. message_not_found: the message does not exist in this channel.

Body: Error

409

pin_limit_reached: the channel already has 50 pins, channel_not_text: a voice channel or category, or blocking_user: the caller blocked the other participant of the DM.

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

Unpin message

DELETE /channels/{id}/pins/{messageID} Bot token: Call it with a bot token (people can call it too).

Unpin a message of this channel. Same permissions as pinning.

Sends message_update with pinned: false and channel_pins_update, and in a community records message.unpin in the moderation log. Unpinning a message that is not pinned changes nothing and answers 204. No system message is posted. Shares the rate limit of sending messages.

Parameters

Parameters of Unpin message
Name In Type Description
id Required path string

Channel ID.
messageID Required path string

Message ID. The message must be in the channel.

Responses

204

Unpinned, or was not pinned.

400

system_message: system messages are never pinned.

Body: Error

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission: no Manage Messages or Read Message History in the channel, timed_out, or dm_not_allowed.

Body: Error

404

channel_not_found: no such channel, or the caller cannot view it. message_not_found: the message does not exist in this channel.

Body: Error

409

channel_not_text: a voice channel or category, or blocking_user.

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

Start typing

POST /channels/{id}/typing Bot token: Call it with a bot token (people can call it too).

Show that the caller is typing in a text channel or DM. Needs the same rights as sending a message.

Publishes the gateway event typing_start (TypingStart) to everyone who can view the channel (in a DM, to both participants), except the caller's own connections and users on either side of a block. Clients show the indicator for 8 seconds after receiving it and clear it when a message_create from the same user arrives in the channel; there is no event for stopping. Send it again while the user keeps typing, at most every 5 seconds: one typing_start per user and channel is published every 5 seconds, and calls inside that window answer 204 without publishing. Beyond that, a caller can make 10 calls at once, then 1 per second.

Parameters

Parameters of Start typing
Name In Type Description
id Required path string

Channel ID.

Responses

204

Published, or already published in the last 5 seconds.

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission: no Send Messages in the channel, timed_out: the caller is timed out in this community, or dm_not_allowed: the other participant of the DM does not accept messages from the caller (a block looks the same).

Body: Error

404

channel_not_found: no such channel, or the caller is not a member of its community or cannot view the channel.

Body: Error

409

channel_not_text: a voice channel, or blocking_user: the caller blocked the other participant of the DM.

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

Update message

PATCH /messages/{id} Bot token: Call it with a bot token (people can call it too).

Edit a message. Only its author can, and only while still a member (or DM participant). Nobody can edit a webhook's message.

In a DM, editing needs the same right as sending.

Parameters

Parameters of Update message
Name In Type Description
id Required path string

Message ID.

Request body

application/json: UpdateMessageRequest (required)

Fields of the application/json request body
FieldTypeDescription
content string

Same rules as when sending.
attachments array of object

The attachments to keep, by ID; the others are removed. Attachments cannot be added.
attachments[].idRequired ID
Example request body
{
  "content": "string",
  "attachments": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A"
    }
  ]
}

Responses

200

The edited message, with edited_at set.

Body: Message

Example response (200)
{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "author": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "username": "string",
    "display_name": "string",
    "kind": "user",
    "avatar": "string",
    "avatar_dark": "string"
  },
  "webhook_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "content": "string",
  "attachments": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "filename": "string",
      "description": "string",
      "content_type": "string",
      "size": 1,
      "url": "string",
      "thumbnail_url": "string",
      "width": 0,
      "height": 0,
      "placeholder": "string",
      "spoiler": false,
      "risk": "none",
      "sensitive": "none",
      "quarantined": false
    }
  ],
  "sticker_items": [
    {
      "id": "string",
      "name": "string",
      "format": "string",
      "animated": false,
      "community_id": "string",
      "pack_id": "string",
      "hash": "string",
      "available": false
    }
  ],
  "gif_url": "string",
  "created_at": "2026-10-15T09:00:00Z",
  "edited_at": "2026-10-15T09:00:00Z",
  "mentions": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "username": "string",
      "display_name": "string",
      "kind": "user",
      "avatar": "string",
      "avatar_dark": "string"
    }
  ],
  "mention_roles": [
    "01J9ZQ3V5K8M2N4P6R8T0W2Y4A"
  ],
  "mention_everyone": false,
  "mention_here": false,
  "interaction": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "name": "string",
    "user": {
      "id": {},
      "username": "string",
      "display_name": "string",
      "kind": {},
      "avatar": {},
      "avatar_dark": {}
    }
  },
  "ephemeral": false,
  "nonce": "string",
  "kind": "default",
  "pinned": false,
  "reactions": [
    {
      "emoji": {
        "id": "string",
        "name": "string"
      },
      "count": 1,
      "me": false
    }
  ],
  "message_reference": {
    "message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A"
  },
  "thread": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "name": "string",
    "kind": "text",
    "position": 0,
    "parent_id": "string",
    "topic": "string",
    "created_at": "2026-10-15T09:00:00Z",
    "overwrites": [
      {
        "type": "role",
        "id": {},
        "allow": {},
        "deny": {}
      }
    ],
    "owner_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "message_count": 0,
    "member_count": 0,
    "thread_metadata": {
      "archived": false,
      "auto_archive_duration": 60,
      "archive_timestamp": "2026-10-15T09:00:00Z",
      "locked": false,
      "invitable": false,
      "create_timestamp": "2026-10-15T09:00:00Z"
    },
    "user_limit": 0,
    "bitrate": 8000,
    "age_restricted": false
  },
  "referenced_message": {},
  "auto_moderation": {
    "rule_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "rule_name": "string",
    "trigger_type": "keyword",
    "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "message_id": "string",
    "blocked": false,
    "edit": false,
    "matched_keyword": "string",
    "matched_content": "string",
    "content": "string",
    "content_hidden": false,
    "content_removed": false,
    "attachments": [
      "string"
    ],
    "timeout_seconds": 0,
    "timeout_until": "2026-10-15T09:00:00Z"
  }
}
400

invalid_body, invalid_content, system_message (system messages cannot be edited) or auto_moderation_blocked (an AutoMod rule refused the new content; the message keeps its old content).

Body: Error

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission: only the author can edit a message, timed_out: the author is timed out in this community, or dm_not_allowed: the author can no longer send in this DM.

Body: Error

404

message_not_found: no such message, or the caller cannot view its channel.

Body: Error

409

blocking_user: the author blocked the other participant of this DM.

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

Delete message

DELETE /messages/{id} Bot token: Call it with a bot token (people can call it too).

Delete a message. Its author can, and so can anyone with Manage Messages in its channel (nobody else in a DM); webhook messages need Manage Messages.

Deleting someone else's message is recorded in the community's moderation log, with the optional reason.

Parameters

Parameters of Delete message
Name In Type Description
id Required path string

Message ID.
X-Audit-Log-Reason header string

A reason recorded in the community's moderation log, percent-encoded UTF-8. Trimmed, then at most 512 characters with no control or invisible formatting characters.

Responses

204

Deleted.

400

invalid_reason: the X-Audit-Log-Reason header is not valid.

Body: Error

401

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

Body: Error

WWW-Authenticate header.

403

missing_permission: not the author and no Manage Messages permission in the channel, or timed_out.

Body: Error

404

message_not_found: no such message, or the caller cannot view its channel.

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

Ack community

POST /communities/{id}/ack Bot token: Call it with a bot token (people can call it too).

Mark every text channel the caller can view in a community as read. Members only.

Each channel's read position moves to its newest message (never backward) and its mention_count becomes 0. Channels the caller cannot view are untouched and not listed. The caller's other gateway sessions receive community_ack.

Parameters

Parameters of Ack community
Name In Type Description
id Required path string

Community ID.

Responses

200

The read states after the ack, ordered by channel ID.

Body: CommunityAck

Example response (200)
{
  "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "read_states": [
    {
      "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "last_read_message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "mention_count": 0
    }
  ]
}
401

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

Body: Error

WWW-Authenticate header.

403

terms_acceptance_required: the instance's terms of service changed (or were never accepted) and this account has not accepted the current version. Show the terms and call POST /users/@me/terms, then retry.

Body: Error

404

community_not_found: no such community, or the caller is not a member. The two cases are indistinguishable on purpose.

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