检索聊天记录

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 }
}