13.19
Tìm kiếm bản ghi
/<guild_id>/api/transcripts/searchTìm trong mọi ticket đã đóng của máy chủ, chứ không chỉ trong dữ liệu mô tả: bên trong nói những gì, ai nói, ai tham gia, mở lúc nào đóng lúc nào, thuộc bảng nào, được đánh giá ra sao hay dùng mã kênh Discord nào. Đây chính là bộ máy của tìm kiếm sâu trong bảng điều khiển. Cần quyền `search_transcripts` (mặc định tắt).
/<guild_id>/api/transcripts/searchVẫn vậy, chỉ khác là bộ lọc gửi trong thân JSON thay cho tham số truy vấn. Tiện hơn với những truy vấn dài và danh sách người tham gia. Nếu gửi cả hai, phần thân được tính.
Mỗi kết quả mang theo dữ liệu mô tả của ticket, tối đa 8 người tham gia, và nếu bạn tìm theo nội dung thì có thêm tối đa 3 đoạn tin nhắn khớp, để bạn thấy *vì sao* ticket đó lọt vào. Lấy TicketId ở bất kỳ kết quả nào rồi đưa thẳng sang Lấy một bản ghi để có danh sách tin nhắn đầy đủ, hoặc sang Lấy bản ghi dạng HTML để có kho lưu dựng sẵn.
Bộ lọc (đều tùy chọn; muốn ghép bao nhiêu cũng được)
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| q | string | tùy chọn | Tìm tự do trong nội dung tin nhắn, tối đa 200 ký tự. Từ ngắn dưới 3 ký tự bị chỉ mục bỏ qua. |
| said_by | string | tùy chọn | Chỉ tính phần nội dung do mã người dùng Discord này viết. Hãy dùng kèm q. |
| participants | string[] | tùy chọn | Tối đa 5 người dùng từng nhắn trong ticket, mỗi người là một mã người dùng Discord hoặc một phần tên người dùng. Ở GET thì cách nhau bằng dấu phẩy, ở POST thì là một mảng. |
| participants_mode | string | tùy chọn | all (mặc định) đòi hỏi mọi người tham gia bạn nêu đều từng nhắn trong cùng một ticket; any tìm những ticket có ít nhất một người trong số đó nhắn tin. |
| include_bots | boolean | tùy chọn | Tính cả tin nhắn và người tham gia là bot. Mặc định là false. |
| opened_by | string | tùy chọn | Người mở ticket, dạng mã người dùng Discord hoặc một phần tên người dùng. |
| closed_by | string | tùy chọn | Mã người dùng Discord của người đã đóng ticket. |
| channel_id | string | tùy chọn | Mã kênh hoặc mã luồng Discord mà ticket đã dùng. |
| panel_id | number | tùy chọn | Chỉ những ticket mở từ bảng này. |
| opened_from | number | tùy chọn | Dấu thời gian Unix: chỉ những ticket mở vào lúc đó trở đi. |
| opened_to | number | tùy chọn | Dấu thời gian Unix: chỉ những ticket mở vào lúc đó trở về trước. |
| closed_from | number | tùy chọn | Dấu thời gian Unix: chỉ những ticket đóng vào lúc đó trở đi. |
| closed_to | number | tùy chọn | Dấu thời gian Unix: chỉ những ticket đóng vào lúc đó trở về trước. |
| rating_min | number | tùy chọn | Mức đánh giá thấp nhất, 1-5. |
| rating_max | number | tùy chọn | Mức đánh giá cao nhất, 1-5. |
| limit | number | tùy chọn | Số kết quả mỗi trang, 1-50 (mặc định 25). |
| offset | number | tùy chọn | Số kết quả bỏ qua khi phân trang, tối đa 10000 (mặc định 0). |
Việc tìm kiếm bị giới hạn 10 yêu cầu mỗi phút cho mỗi khóa, tính riêng với các lần đọc khác, và chạy trong khoảng thời gian eo hẹp. Lần tìm nào không kịp xong sẽ trả về 504. Hãy thu hẹp bộ lọc (thêm khoảng thời gian hoặc một bảng) rồi thử lại, đừng lặp lại y nguyên truy vấn cũ. Những giá trị không qua được khâu kiểm tra sẽ bị bỏ đi chứ không làm hỏng cả yêu cầu, nên hãy xem đối tượng filters trả về trong phản hồi để biết thực sự đã áp dụng những gì.
Việc tìm kiếm đọc chỉ mục bản ghi, vốn được dựng trong lúc máy chủ có Premium và được bổ sung cho cả kho cũ của bạn ở lần nâng cấp đầu tiên. Đối tượng coverage trong mỗi phản hồi cho biết bao nhiêu bản ghi của bạn đã vào chỉ mục (indexed) trên tổng số đang lưu (total). Nếu việc bổ sung chỉ mục còn đang chạy thì hai con số này chưa khớp nhau.
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"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 }
}