message_unpin

message_unpin removes a message’s pin, so it no longer shows up in messages_pinned. Like message_pin, it posts a short announcement in the conversation.

Request

{
  "cmd": "message_unpin",
  "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 unpin.

Response

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

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

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

{
  "cmd": "message_new",
  "channel": "general",
  "message": {
    "id": "e2d9c4b7-1f3a-4c6e-9b8d-7a5f0e1c2d34",
    "user": "originChats",
    "author_id": "originChats",
    "timestamp": 1788940200.47,
    "content": "originChats:<message>//chat.example/general/7d0e4c1a-5b8f-4b0e-8f55-2d3c9a61e7b4 unpinned 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 message followed by unpinned 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.
Unpinning a message that is not pinned succeeds and still posts an 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 unpin.

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`. Unpinning uses the same permission.
`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 change 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