message_pin

message_pin marks a message as pinned so it shows up in messages_pinned. The server also posts a short announcement in the conversation. To remove a pin, use message_unpin.

Request

{
  "cmd": "message_pin",
  "channel": "general",
  "id": "7d0e4c1a-5b8f-4b0e-8f55-2d3c9a61e7b4"
}

Field	Type	Required	Description
`channel`	string	One of `channel` or `thread_id`	Channel name.
`thread_id`	string	One of `channel` or `thread_id`	Thread ID. If you also send `channel`, it must be the thread’s parent.
`id`	string	Yes	ID of the message to pin.

Response

The server sends two events, in this order, to you and to every other connection that can view the channel. First the pin itself:

{
  "cmd": "message_pin",
  "channel": "general",
  "id": "7d0e4c1a-5b8f-4b0e-8f55-2d3c9a61e7b4",
  "pinned": true
}

Then a message_new with the announcement, a system message that replies to the pinned message:

{
  "cmd": "message_new",
  "channel": "general",
  "message": {
    "id": "b5a0f1f2-8c47-4e0b-a1b9-2f6f3d0c9e11",
    "user": "originChats",
    "author_id": "originChats",
    "timestamp": 1788940100.02,
    "content": "originChats:<message>//chat.example/general/7d0e4c1a-5b8f-4b0e-8f55-2d3c9a61e7b4 pinned by @alice",
    "reply_to": {
      "user": "alice",
      "id": "7d0e4c1a-5b8f-4b0e-8f55-2d3c9a61e7b4",
      "preview": "Release notes are up: https://example.co"
    },
    "ping": true,
    "pings": { "users": ["alice"], "replies": ["alice"] }
  }
}

The announcement’s content is a link to the pinned message followed by pinned by @<username>. For a thread message the link is originChats:<message>//<host>/<channel>/<thread_id>/<id>.
Thread events have thread_id, and channel is the thread’s parent.
Only your copies carry your request’s listener. Users severed from you don’t receive the events.
Pinning a message that is already pinned succeeds and posts another announcement.

Permissions

You must be able to view the channel, and your roles need the channel’s pin permission. For a thread, the parent channel’s permissions apply. By default pin is granted to owner, admin, and moderator. A user in a timeout can’t pin.

Errors

`val`	When
`Channel or thread_id is required`	You sent neither `channel` nor `thread_id`.
`Channel not found`	The channel doesn’t exist.
`Thread not found`	No thread has this ID.
`Thread does not belong to this channel`	`channel` is not the thread’s parent.
`You do not have permission to view this thread`	You can’t view the thread’s parent channel.
`Messages must be sent inside a thread in forum channels`	`channel` is a forum and you sent no `thread_id`.
`This channel does not support chat`	`channel` is a separator.
`Access denied to this channel`	You can’t view the channel.
`You do not have permission to pin messages in this channel`	Your roles lack `pin`.
`Message not found`	No message with this ID is in the channel or thread, or the change could not be saved.
`Unable to save message`	The pin was saved but the announcement was not. No events are sent.

A validation message is returned when id is missing or empty. A user in a timeout gets a rate_limit frame; see the protocol model.

See also