檢索對話紀錄

GET/<guild_id>/api/transcripts/search

搜尋伺服器中每一張已關閉的工單，而不只是中繼資料：裡面說過什麼、是誰說的、誰參與過、何時開啟或關閉、屬於哪個面板、評分如何，或所在的 Discord 頻道 ID。它與控制台中的深度搜尋使用同一套引擎。需要 `search_transcripts` 權限（預設關閉）。

POST/<guild_id>/api/transcripts/search

功能相同，只是把篩選條件放在 JSON 請求本文中，而不是查詢參數。條件很長或參與者較多時更方便。如果兩邊都送，以請求本文為準。

每筆結果都會帶上工單的中繼資料、最多 8 位參與者；如果你是依內容搜尋，還會附上最多 3 段相符的訊息片段，讓你看清它*為什麼*相符。拿任一筆結果中的 TicketId，直接用於取得對話紀錄取回完整訊息清單，或用於取得對話紀錄 HTML 取回已算繪的封存。

篩選條件（全部選填，可任意組合）

名稱	型別	必填	說明
q	string	選填	對訊息內容做全文搜尋，最多 200 個字元。少於 3 個字元的詞會被索引略過。
said_by	string	選填	只比對該 Discord 使用者 ID 所寫的內容。搭配 `q` 使用。
participants	string[]	選填	在工單中發過言的使用者，最多 5 位，每位可填 Discord 使用者 ID 或使用者名稱的一部分。GET 時用逗號分隔，POST 時用陣列。
participants_mode	string	選填	`all`（預設）要求列出的參與者都在同一張工單中發過言；`any` 則比對其中至少一人發過言的工單。
include_bots	boolean	選填	把機器人訊息與機器人參與者納入比對範圍。預設為 false。
opened_by	string	選填	工單的開單者，可填 Discord 使用者 ID 或使用者名稱的一部分。
closed_by	string	選填	關閉該工單的人的 Discord 使用者 ID。
channel_id	string	選填	工單所使用的 Discord 頻道或討論串 ID。
panel_id	number	選填	只查該面板開出的工單。
opened_from	number	選填	Unix 時間戳記：只查在該時刻或之後開啟的工單。
opened_to	number	選填	Unix 時間戳記：只查在該時刻或之前開啟的工單。
closed_from	number	選填	Unix 時間戳記：只查在該時刻或之後關閉的工單。
closed_to	number	選填	Unix 時間戳記：只查在該時刻或之前關閉的工單。
rating_min	number	選填	最低評分，1-5。
rating_max	number	選填	最高評分，1-5。
limit	number	選填	每頁結果數，1-50（預設 25）。
offset	number	選填	分頁時略過的結果數，最多 10000（預設 0）。

搜尋的限流獨立於其他讀取操作，為每個權杖每分鐘 10 次，而且有嚴格的執行時間上限。來不及完成的搜尋會回傳 504。這時請縮小篩選範圍（加上時間區間或面板）再試，而不是重複送出同一個請求。未通過驗證的值會被略過而不是直接報錯，所以請查看回應中回傳的 filters 物件，確認實際生效的條件。

搜尋讀取的是對話紀錄索引。這份索引在伺服器擁有 Premium 期間建立，並會在你首次升級時針對既有封存補建。每次回應中的 coverage 物件會告訴你，在已保存的總數（total）中有多少筆對話紀錄已建立索引（indexed）。如果補建仍在進行，這兩個數字暫時還不會一致。

請求範例：在某位客服人員也處理過的工單中，尋找某位使用者說過的話

curl -X GET \
  -H "Authorization: Bearer <API_TOKEN>" \
  "https://api.ticketsx.xyz/<guild_id>/api/transcripts/search?q=refund&participants=123456789,987654321&participants_mode=all&closed_from=1730000000&limit=25"

請求範例：同樣的搜尋，改用 JSON 請求本文

curl -X POST \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"q":"refund","participants":["123456789","987654321"],"participants_mode":"all","closed_from":1730000000,"limit":25}' \
  https://api.ticketsx.xyz/<guild_id>/api/transcripts/search

回應範例

{
  "transcripts": [
    {
      "TicketId": 42,
      "AuthorId": "123456789",
      "AuthorUsername": "jane",
      "PanelId": 1,
      "PanelName": "Support",
      "Rating": 5,
      "RatingCount": 1,
      "CloseReason": "Resolved",
      "CreatedAt": 1732200000,
      "ClosedAt": 1732210000,
      "ChannelId": "1122334455",
      "ClosedBy": "987654321",
      "Participants": [
        { "UserId": "123456789", "Username": "jane", "MessageCount": 12, "IsBot": false }
      ],
      "Snippets": [
        { "AuthorId": "123456789", "AuthorUsername": "jane", "Content": "my refund never arrived", "CreatedAt": 1732200050 }
      ]
    }
  ],
  "pagination": { "total": 1, "limit": 25, "offset": 0, "returned": 1 },
  "coverage": { "indexed": 480, "total": 480 },
  "filters": { "q": "refund", "participants_mode": "all", "limit": 25 }
}