13.19
대화 기록 찾기
/<guild_id>/api/transcripts/search서버에서 닫힌 모든 티켓을 메타데이터뿐 아니라 내용까지 검색합니다. 티켓 안에서 무슨 말이 오갔는지, 누가 말했는지, 누가 참여했는지, 언제 열리고 닫혔는지, 어느 패널인지, 평가가 몇 점인지, Discord 채널 ID가 무엇인지로 찾을 수 있습니다. 대시보드의 심층 검색과 같은 엔진입니다. `search_transcripts` 권한이 필요합니다(기본값은 꺼짐).
/<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 | 선택 | 유닉스 타임스탬프. 이 시각 이후에 열린 티켓만 찾습니다. |
| opened_to | number | 선택 | 유닉스 타임스탬프. 이 시각 이전에 열린 티켓만 찾습니다. |
| closed_from | number | 선택 | 유닉스 타임스탬프. 이 시각 이후에 닫힌 티켓만 찾습니다. |
| closed_to | number | 선택 | 유닉스 타임스탬프. 이 시각 이전에 닫힌 티켓만 찾습니다. |
| rating_min | number | 선택 | 최소 평가 점수, 1~5. |
| rating_max | number | 선택 | 최대 평가 점수, 1~5. |
| limit | number | 선택 | 한 페이지의 결과 수, 1~50(기본값 25). |
| offset | number | 선택 | 페이지를 넘기려고 건너뛸 결과 수. 최대 10000(기본값 0). |
검색은 다른 읽기와 별도로 토큰마다 1분에 10번으로 제한되며, 정해진 시간 안에서만 동작합니다. 제때 끝나지 못한 검색은 504를 돌려줍니다. 같은 질의를 다시 보내지 말고 기간이나 패널 같은 조건을 더해 범위를 좁힌 뒤 다시 시도하세요. 형식에 맞지 않는 값은 요청을 거절하는 대신 그냥 빠지므로, 실제로 어떤 조건이 적용되었는지는 응답에 함께 오는 filters 객체에서 확인하세요.
검색은 대화 기록 색인을 읽습니다. 색인은 서버에 프리미엄이 있는 동안 만들어지고, 처음 업그레이드할 때 기존 보관본까지 채워집니다. 모든 응답의 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"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 }
}