查詢與匯出訊息

從你的服務端讀取訊息。

要做什麼	介面
歸檔、資料分析：匯出全應用的訊息，之後增量匯出	匯出應用的訊息
按訊息 ID 查一條訊息	查詢單條訊息
處理投訴、刷屏：查某個使用者發過的訊息	查詢使用者發出的訊息
查一個會話的歷史訊息（可按時間段）	會話與歷史訊息

返回的都是訊息物件，以服務端的視角：

訊息	是否返回
被使用者刪除、清空了聊天記錄的	返回，不受影響
已撤回、已擦除的	返回，但沒有內容（`body`、`ext` 等為 `null`）
超過保留期的	不返回
只推線上的訊息	不儲存，查不到

一頁的訊息合計不超過 1 MB，超出時這一頁提前結束，照常按翻頁欄位繼續即可。

匯出應用的訊息

按訊息 ID 從小到大匯出應用內全部會話的訊息，包括單聊、群聊和群提示。

GET/{org_name}/{app_name}/messages

第一次不傳 after_message_id，從最早的訊息開始；之後每次傳上一頁的 next_after_message_id，直到 has_more 為 false。儲存最後的 next_after_message_id，下次從它繼續，就只匯出新訊息：

bash

AFTER=$(cat last_message_id 2>/dev/null)   # 上次导出到哪里；第一次为空
while :; do
  PAGE=$(curl -s "$IM_API/$ORG/$APP/messages?limit=1000${AFTER:+&after_message_id=$AFTER}" \
    -H "Authorization: Bearer $APP_TOKEN")
  echo "$PAGE" | jq -c '.items[]' >> messages.jsonl
  NEXT=$(echo "$PAGE" | jq -r '.next_after_message_id // empty')
  [ -n "$NEXT" ] && AFTER=$NEXT
  [ "$(echo "$PAGE" | jq -r '.has_more')" = true ] || break
done
echo "$AFTER" > last_message_id

只匯出 30 秒之前的訊息：為了按 ID 翻頁不漏訊息，剛傳送的訊息要 30 秒後才能匯出。
已匯出的不會更新：之後才撤回或編輯的訊息，已匯出的內容不會變。需要儲存撤回前的原內容，請在撤回前匯出。
補齊訊息抄送：用事件回撥的 message.sent 接收訊息抄送時，回撥地址暫停、停用或積壓期間可能漏掉訊息。從缺口之前的某個訊息 ID 開始匯出補齊，按 message_id 去重，見用好訊息抄送。

路徑引數

org_name、app_name 見接入概述。

查詢引數

引數	型別	必填	說明
`after_message_id`	String	否	從這個訊息 ID 之後開始匯出（不含它本身），傳上一頁的 `next_after_message_id`。不傳時從最早的訊息開始
`limit`	Number	否	每頁條數，預設 100，取值 1 到 1000

請求示例

bash

curl "$IM_API/$ORG/$APP/messages?after_message_id=99582642738954240&limit=2" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
`items`	Array<Object>	本頁的訊息物件，按訊息 ID 從小到大排列
`next_after_message_id`	String	下一頁的起點，傳給下一次請求的 `after_message_id`。本頁沒有訊息時與請求中的 `after_message_id` 相同
`has_more`	Boolean	是否可能還有下一頁。為 `true` 時請繼續請求，下一頁可能為空

json

{
  "items": [
    {
      "conversation_id": "99582604130385920",
      "conversation_type": "single",
      "seq": 7,
      "message_id": "99582642919309312",
      "client_msg_id": "2ec322dc5f952fd2d05bc6df94a44d9a",
      "sender": "bob",
      "sender_type": "user",
      "recipient": "alice",
      "type": "custom",
      "body": { "card": "order_shipped", "order_id": "8812", "status": "delivered" },
      "ext": null,
      "mentions": null,
      "reply_to": null,
      "need_receipt": false,
      "exclude_from_unread": false,
      "reactions": null,
      "pinned": null,
      "edited": { "at": "2026-10-02T19:08:27.418Z", "count": 2 },
      "recalled": null,
      "erased": false,
      "via": "openapi",
      "created_at": "2026-10-02T19:05:52.228Z",
      "message_version": 2
    },
    {
      "conversation_id": "99582580415791104",
      "conversation_type": "group",
      "seq": 3,
      "message_id": "99582672556261376",
      "client_msg_id": "doc-grp-0001",
      "sender": "alice",
      "sender_type": "user",
      "recipient": null,
      "type": "text",
      "body": { "text": "@bob 请看一下需求文档" },
      "ext": null,
      "mentions": { "usernames": ["bob"], "all": false },
      "reply_to": null,
      "need_receipt": false,
      "exclude_from_unread": false,
      "reactions": null,
      "pinned": { "by": null, "at": "2026-10-02T19:08:36.382Z" },
      "edited": null,
      "recalled": null,
      "erased": false,
      "via": "openapi",
      "created_at": "2026-10-02T19:05:59.294Z",
      "message_version": 1
    }
  ],
  "next_after_message_id": "99582672556261376",
  "has_more": true
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`after_message_id` 不是非負整數，或 `limit` 不在 1 到 1000 之間

查詢單條訊息

按訊息 ID 查詢一條訊息。

GET/{org_name}/{app_name}/messages/{message_id}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`message_id`	String	訊息 ID

請求示例

bash

curl "$IM_API/$ORG/$APP/messages/99584445836689408" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，響應體為訊息物件：

json

{
  "conversation_id": "99582580415791104",
  "conversation_type": "group",
  "seq": 9,
  "message_id": "99584445836689408",
  "client_msg_id": "5f0c2a7e-91b4-4d2e-a0c3-6b1e8f2d4c19",
  "sender": "bob",
  "sender_type": "user",
  "recipient": null,
  "type": "text",
  "body": { "text": "@carol 文档已更新，请确认" },
  "ext": { "biz_id": "PRD-2041" },
  "mentions": { "usernames": ["carol"], "all": false },
  "reply_to": { "seq": 3, "sender": "alice" },
  "need_receipt": false,
  "exclude_from_unread": false,
  "reactions": null,
  "pinned": null,
  "edited": null,
  "recalled": null,
  "erased": false,
  "via": "openapi",
  "created_at": "2026-10-02T19:13:02.076Z",
  "message_version": 0
}

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	訊息不存在、已超過保留期，或 `message_id` 的格式不對

查詢使用者發出的訊息

從新到舊列出某個使用者發過的訊息（單聊和群聊，客戶端發的和服務端以他的身份發的都算），可以按時間段篩選。常用於處理投訴和刷屏：先查出某人一段時間內發的訊息，再批次撤回。

GET/{org_name}/{app_name}/users/{username}/sent-messages

按遊標分頁：

一頁可能少於 limit 條（超過保留期的被跳過），請看 next_cursor 是否為 null 判斷還有沒有下一頁；
翻頁時保持 start_time、end_time 不變。

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`username`	String	傳送者的使用者名稱

查詢引數

引數	型別	必填	說明
`start_time`	String	否	只返回傳送時間不早於這個時間的訊息，RFC 3339 格式，如 `2026-10-02T00:00:00Z`。帶時區偏移時，`+` 要編碼為 `%2B`，如 `2026-10-02T08:00:00%2B08:00`
`end_time`	String	否	只返回傳送時間早於這個時間的訊息（不含），格式同上
`cursor`	String	否	下一頁的遊標，第一頁不傳
`limit`	Number	否	每頁條數，預設 20，取值 1 到 100

請求示例

bash

curl "$IM_API/$ORG/$APP/users/bob/sent-messages?start_time=2026-10-02T00:00:00Z&limit=2" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，items 為訊息物件的列表，next_cursor 為下一頁的遊標：

json

{
  "items": [
    {
      "conversation_id": "99582580415791104",
      "conversation_type": "group",
      "seq": 9,
      "message_id": "99584445836689408",
      "client_msg_id": "5f0c2a7e-91b4-4d2e-a0c3-6b1e8f2d4c19",
      "sender": "bob",
      "sender_type": "user",
      "recipient": null,
      "type": "text",
      "body": { "text": "@carol 文档已更新，请确认" },
      "ext": { "biz_id": "PRD-2041" },
      "mentions": { "usernames": ["carol"], "all": false },
      "reply_to": { "seq": 3, "sender": "alice" },
      "need_receipt": false,
      "exclude_from_unread": false,
      "reactions": null,
      "pinned": null,
      "edited": null,
      "recalled": null,
      "erased": false,
      "via": "openapi",
      "created_at": "2026-10-02T19:13:02.076Z",
      "message_version": 0
    },
    {
      "conversation_id": "99582580415791104",
      "conversation_type": "group",
      "seq": 7,
      "message_id": "99582995840630784",
      "client_msg_id": "97250496646553a053befca0da838392",
      "sender": "bob",
      "sender_type": "user",
      "recipient": null,
      "type": "text",
      "body": { "text": "好的，我下午看" },
      "ext": null,
      "mentions": null,
      "reply_to": null,
      "need_receipt": false,
      "exclude_from_unread": false,
      "reactions": null,
      "pinned": null,
      "edited": null,
      "recalled": null,
      "erased": false,
      "via": "openapi",
      "created_at": "2026-10-02T19:07:16.371Z",
      "message_version": 0
    }
  ],
  "next_cursor": "99582995840630784"
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`start_time`、`end_time` 不是 RFC 3339 格式（帶時區偏移時 `+` 要寫成 `%2B`），`cursor` 無效，或 `limit` 不在 1 到 100 之間
404	`not_found`	使用者不存在或已被刪除

查詢與匯出訊息 ​

匯出應用的訊息 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢單條訊息 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢使用者發出的訊息 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢與匯出訊息

匯出應用的訊息

路徑引數

查詢引數

請求示例

響應

錯誤

查詢單條訊息

路徑引數

請求示例

響應

錯誤

查詢使用者發出的訊息

路徑引數

查詢引數

請求示例

響應

錯誤