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 は少なくとも 1 人が発言したチケットに一致します。 |
| include_bots | boolean | 任意 | ボットのメッセージとボットの参加を対象に含めます。既定値は false です。 |
| opened_by | string | 任意 | チケットの作成者。Discord のユーザー ID か、ユーザー名の一部で指定します。 |
| closed_by | string | 任意 | チケットをクローズした人の Discord ユーザー ID。 |
| channel_id | string | 任意 | そのチケットが使っていた Discord のチャンネル ID またはスレッド 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 ページあたりの件数、1-50(既定値 25)。 |
| offset | number | 任意 | ページ送りで読み飛ばす件数。最大 10000(既定値 0)。 |
検索はほかの読み取りとは別枠で、トークンあたり 1 分間に 10 回 に制限されており、実行時間にも厳しい上限があります。時間内に終わらない検索は 504 を返します。同じ条件で繰り返すのではなく、期間やパネルを足して条件を絞ってから試してください。検証を通らなかった値は拒否されずに無視されるため、実際に何が適用されたかは応答に含まれる filters オブジェクトで確認してください。
検索は履歴インデックスを参照します。このインデックスはサーバーに Premium がある間に作られ、初めてアップグレードしたときに既存のアーカイブが取り込まれます。各応答の coverage オブジェクトには、保存済みの総数(total)のうちインデックス化済みの件数(indexed)が示されます。取り込みが進行中の場合、この 2 つはまだ一致しません。
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 }
}