訊息備份 API

存取備份的群組訊息與媒體檔案。

訂閱管理

訂閱備份

POST /api/channels/:channelId/backup/subscribe

開始備份該群組的訊息。

回應

{
  "success": true
}

取消訂閱

DELETE /api/channels/:channelId/backup/subscribe

停止備份該群組。已備份的資料會保留。

---

訊息

取得訊息列表

GET /api/channels/:channelId/backup/messages

Query 參數

參數	類型	必填	說明
date	string	否	日期 YYYY-MM-DD，預設今天
cursor	string	否	分頁游標
limit	number	否	每頁筆數，預設 50，最大 100

範例

GET /api/channels/C123/backup/messages?date=2025-01-15&limit=20

回應

{
  "messages": [
    {
      "id": "msg_17053128000001",
      "timestamp": "2025-01-15T08:30:00Z",
      "sender": {
        "id": "U1234567890",
        "name": "王小明"
      },
      "type": "text",
      "content": "大家早安！今天天氣真好"
    },
    {
      "id": "msg_17053128000002",
      "timestamp": "2025-01-15T08:31:00Z",
      "sender": {
        "id": "U0987654321",
        "name": "李小華"
      },
      "type": "image",
      "mediaKey": "media/C123/2025-01-15/msg_17053128000002.jpg",
      "fileSize": 102400
    },
    {
      "id": "msg_17053128000003",
      "timestamp": "2025-01-15T08:32:00Z",
      "sender": {
        "id": "U1234567890",
        "name": "王小明"
      },
      "type": "sticker",
      "stickerId": "12345",
      "packageId": "100"
    }
  ],
  "nextCursor": "msg_17053128000050"
}

訊息類型

type	說明	額外欄位
text	文字訊息	content
image	圖片	mediaKey, fileSize
video	影片	mediaKey, fileSize, duration
audio	音訊	mediaKey, fileSize, duration
file	檔案	mediaKey, fileSize, fileName
location	位置	latitude, longitude, address
sticker	貼圖	stickerId, packageId

取得單一訊息

GET /api/channels/:channelId/backup/messages/:messageId

Query 參數

參數	類型	必填	說明
date	string	是	訊息日期 YYYY-MM-DD

回應

{
  "id": "msg_17053128000001",
  "timestamp": "2025-01-15T08:30:00Z",
  "sender": {
    "id": "U1234567890",
    "name": "王小明"
  },
  "type": "text",
  "content": "大家早安！今天天氣真好"
}

---

媒體檔案

取得媒體列表

GET /api/channels/:channelId/backup/media

Query 參數

參數	類型	必填	說明
cursor	string	否	分頁游標
limit	number	否	每頁筆數，預設 50

回應

{
  "items": [
    {
      "id": "msg_17053128000002",
      "ts": "2025-01-15T08:31:00Z",
      "type": "image",
      "sender": "李小華",
      "size": 102400
    },
    {
      "id": "msg_17053128000010",
      "ts": "2025-01-15T09:00:00Z",
      "type": "video",
      "sender": "王小明",
      "size": 5242880
    }
  ],
  "nextCursor": "msg_17053128000100"
}

下載媒體檔案

GET /api/channels/:channelId/backup/media/:messageId

回應

• Content-Type: application/octet-stream
• Content-Length: 檔案大小
• Body: 二進位檔案內容

範例

curl -X GET https://api.gm.kamigo.tw/api/channels/C123/backup/media/msg_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o image.jpg

const response = await fetch(
  'https://api.gm.kamigo.tw/api/channels/C123/backup/media/msg_123',
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);
const blob = await response.blob();

---

分頁處理

游標分頁

使用 cursor 和 nextCursor 進行分頁：

async function getAllMessages(channelId, date) {
  const messages = [];
  let cursor = null;

  do {
    const url = new URL(`https://api.gm.kamigo.tw/api/channels/${channelId}/backup/messages`);
    url.searchParams.set('date', date);
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url, {
      headers: { Authorization: 'Bearer YOUR_API_KEY' }
    });
    const data = await response.json();

    messages.push(...data.messages);
    cursor = data.nextCursor;
  } while (cursor);

  return messages;
}

---

錯誤處理

403 Forbidden

{
  "error": "Not a subscriber"
}

原因：你沒有訂閱該群組的備份功能。

404 Not Found

{
  "error": "Message not found"
}

原因：訊息不存在或已過期。