TagMangoTagMango Docs
Community

Pin or unpin a message in one of your community chat rooms

PATCH
/api/v1/external/community/chatrooms/{roomId}/messages/{messageId}/pin

Pin or unpin a root message in one of your community chat rooms — a root message only, never a reply. isPinned: true pins it — pinning an already-pinned message moves it to the top of the pin order (most-recently-pinned first), rather than failing. isPinned: false unpins it — unpinning an already-unpinned message is a no-op, not an error. Unlike pinning, unpinning works on a reply too, in case one was pinned before this restriction existed.

A room can have at most 5 pinned messages at once — pinning a 6th fails with a 400 (errorCode: CHAT_MESSAGE_SEND_MAX_PINNED_MESSAGES_REACHED); unpin one first to make room. Pinning a reply fails with a 400 (errorCode: CHAT_MESSAGE_SEND_CANNOT_PIN_REPLY).

Always acts as the creator: there is no concept of an individual acting fan/UAM user for this endpoint. Pinning already requires the same creator-level access on the dashboard — no plain member can pin there either. This endpoint is deliberately stricter specifically for unpinning in a direct-message room, where the dashboard's own pinned-messages banner lets either participant unpin without any creator-access check at all — only the creator (the API key holder) can do so here, in every room type.

The response contains the full updated message, in the same shape returned by the send/reply/edit endpoints, plus isPinned reflecting the state that was just applied.

Fails with a 400 if the Community feature is not enabled for this creator. Fails with a 404 (errorCode: CHAT_MESSAGE_SEND_ROOM_NOT_FOUND) if roomId does not exist or is not yours, or (errorCode: CHAT_MESSAGE_SEND_MESSAGE_NOT_FOUND) if messageId doesn't exist or belongs to a different room.

External access policy

An API key and an authorized white-label host are required. Both tier and plan requirements are enforced.

These requirements apply to the white-label creator for backend-to-backend access. TagMango platform access is not supported.

  • Plans: Unrestricted.

  • Tiers: Unrestricted.

AuthorizationBearer <token>

In: header

Path Parameters

roomId*string

Id of the community chat room the message belongs to

messageId*string

Id of the message to pin or unpin

Header Parameters

x-whitelabel-host*string

Host name of the dashboard, ex: mydomain.tagmango.com

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://api-prod-new.tagmango.com/api/v1/external/community/chatrooms/61e97c146cf2b4d8c68f3a40/messages/61e97c146cf2b4d8c68f3a4a/pin" \  -H "x-whitelabel-host: string" \  -H "Content-Type: application/json" \  -d '{    "isPinned": true  }'
{
  "message": {
    "_id": "6659ca9e5f2acb7abfdcd8fd",
    "room": "6659ca9e5f2acb7abfdcd8fd",
    "message": "Hello, how are you?",
    "edited": true,
    "isDeleted": true,
    "lastEditedAt": "2021-08-01T00:00:00.000Z",
    "isThreadRoot": true,
    "threadRoot": "6659ca9e5f2acb7abfdcd8fd",
    "threadRootMetadata": {
      "firstFiveRepliers": [
        "6659ca9e5f2acb7abfdcd8fd"
      ],
      "totalReplies": 5,
      "lastRepliedAt": "2021-08-01T00:00:00.000Z",
      "lastReply": "6659ca9e5f2acb7abfdcd8fd"
    },
    "reactions": {
      "😄": 5,
      "🚀": 2,
      "❤️": 10
    },
    "createdAt": "2021-08-01T00:00:00.000Z",
    "updatedAt": "2021-08-01T00:00:00.000Z",
    "poll": "6659ca9e5f2acb7abfdcd8fd",
    "pollMetadata": {
      "creator": "6659ca9e5f2acb7abfdcd8fd",
      "question": "What is your favorite color?",
      "description": "Choose your favorite color",
      "pollOptions": [
        {
          "optionContent": "string",
          "optionNumber": 0,
          "optionId": "string"
        }
      ],
      "pollEndAt": "2021-08-01T00:00:00.000Z",
      "pollVotesPerOption": {
        "id1": 5,
        "id2": 2,
        "id3": 10
      },
      "isResultVisibleToMembers": true,
      "allowVoteChange": true,
      "pollStartAt": "2021-08-01T00:00:00.000Z"
    },
    "sender": {
      "name": "John Doe",
      "profilePicUrl": "https://linktoprofilepic.com/pic.jpg",
      "_id": "6659ca9e5f2acb7abfdcd8fd",
      "isModerator": false
    },
    "assets": [
      {
        "asset": "6659ca9e5f2acb7abfdcd8fd",
        "type": "image",
        "contentUrl": "https://example.com/image.jpg",
        "fileName": "filename.jpg",
        "fileSize": 1024,
        "fileType": "jpg"
      }
    ],
    "isPinned": true
  }
}
{
  "code": 400,
  "type": "Bad Request",
  "statusMessage": "BAD_REQUEST",
  "success": false,
  "message": "Invalid request",
  "result": "Invalid request"
}
{
  "code": 401,
  "type": "Unauthorized",
  "statusMessage": "UNAUTHORIZED",
  "message": "Invalid token",
  "result": "Invalid token",
  "success": false
}
{
  "code": 403,
  "type": "Forbidden",
  "statusMessage": "FORBIDDEN",
  "errorCode": "WORKSHOP_MANGO_FORBIDDEN",
  "message": "You can not access this api with a TagMango account, only available for whitelabel hosts",
  "result": "You can not access this api with a TagMango account, only available for whitelabel hosts",
  "success": false
}
{
  "code": 429,
  "type": "Too Many Requests",
  "statusMessage": "TOO_MANY_REQUESTS",
  "message": "Request limit exceeded. try after 10 seconds",
  "result": "Request limit exceeded. try after 10 seconds",
  "success": false
}