釘選訊息

概述

此端點允許聊天室擁有者或管理員將指定訊息釘選至聊天室頂部，方便成員快速查閱重要訊息。每個聊天室同一時間只能有一則釘選訊息。

API 端點

釘選訊息

將指定訊息釘選至聊天室頂部。

POST /messages/:id/pin

Headers

參數	類型	必填	說明
`IM-CLIENT-KEY`	string	✅	用戶端金鑰
`IM-Authorization`	string	✅	用戶端權杖

Path Parameters

參數	類型	必填	說明
`:id`	string	✅	訊息唯一識別碼

此 API 無需請求內容（Request Body）。

範例請求

cURL 範例：

curl -X "POST" "https://your-app.imkit.io/messages/5f890cf37d980e06f6aaf349/pin" \
     -H 'IM-CLIENT-KEY: {IM-CLIENT-KEY}' \
     -H 'IM-Authorization: {IM-Authorization}'

JavaScript 範例：

const response = await axios.post(
  `https://your-app.imkit.io/messages/${messageID}/pin`,
  null,
  {
    headers: {
      "IM-CLIENT-KEY": `${IM_CLIENT_KEY}`,
      "IM-Authorization": `${TOKEN}`,
    },
  }
);

Response

成功回應（200 OK）

參數	類型	說明
`RC`	number	回應代碼（0 表示成功）
`RM`	string	回應訊息
`result._id`	string	訊息唯一識別碼
`result.message`	string	訊息內容
`result.room`	string	所屬聊天室 ID
`result.sender`	object	訊息發送者資訊
`result.messageType`	string	訊息類型
`result.pinned`	boolean	是否已釘選（釘選後為 `true`）
`result.messageTimeMS`	number	訊息發送時間戳（毫秒）
`result.updatedAtMS`	number	最後更新時間戳（毫秒）

範例回應

{
  "RC": 0,
  "RM": "OK",
  "result": {
    "_id": "5f890cf37d980e06f6aaf349",
    "message": "重要公告：明天下午兩點開會",
    "room": "demo-room",
    "sender": {
      "_id": "aaa",
      "nickname": "AAA",
      "avatarUrl": "http://loremflickr.com/240/240/style?1569804629",
      "isRobot": false,
      "id": "aaa",
      "lastLoginTimeMS": 1602817267900
    },
    "messageType": "text",
    "appID": "SampleApp",
    "pinned": true,
    "id": "5f890cf37d980e06f6aaf349",
    "messageTimeMS": 1602817267923,
    "updatedAtMS": 1602817290000,
    "createdAtMS": 1602817267925
  }
}

錯誤回應

當請求失敗時，您會收到包含錯誤詳細資訊的錯誤回應。常見的錯誤情況包括：

無效的用戶端金鑰或授權權杖
指定的訊息不存在
當前用戶不是聊天室擁有者或管理員
伺服器內部錯誤

使用場景

重要訊息管理

公告置頂：將重要公告釘選至聊天室頂部，確保所有成員都能看到
快速查閱：讓成員無需翻閱歷史訊息即可找到關鍵資訊

注意事項

權限限制：僅聊天室**擁有者（owner）或管理員（admin）**可以執行釘選操作
若要取消釘選，請使用取消釘選訊息 API

批次發送訊息取消釘選訊息