In Transkripten suchen

GET/<guild_id>/api/transcripts/search

Durchsucht jedes geschlossene Ticket des Servers, nicht nur dessen Metadaten: was darin gesagt wurde, wer es gesagt hat, wer beteiligt war, wann es geöffnet oder geschlossen wurde, sowie Panel, Bewertung oder Discord-Kanal-ID. Dahinter steckt dieselbe Technik wie hinter der Tiefensuche im Dashboard. Erfordert die Berechtigung `search_transcripts` (standardmäßig aus).

POST/<guild_id>/api/transcripts/search

Identisch, nur werden die Filter als JSON-Körper statt als Abfrageparameter geschickt. Praktischer für lange Abfragen und Listen von Beteiligten. Schickst du beides, gewinnt der Körper.

Jedes Ergebnis bringt die Metadaten des Tickets mit, bis zu 8 Beteiligte und, wenn du nach Inhalt gesucht hast, bis zu 3 passende Nachrichtenausschnitte, damit du siehst, *warum* es passt. Nimm die TicketId aus einem Ergebnis direkt für Transkript abrufen, um die vollständige Nachrichtenliste zu bekommen, oder für Transkript-HTML abrufen, um das fertige Archiv zu holen.

Filter (alle optional, beliebig kombinierbar)

Name	Typ	Pflichtfeld	Beschreibung
q	string	optional	Freitextsuche im Nachrichteninhalt, höchstens 200 Zeichen. Wörter mit weniger als 3 Zeichen ignoriert der Index.
said_by	string	optional	Findet nur Inhalte, die diese Discord-Nutzer-ID geschrieben hat. Kombinierbar mit `q`.
participants	string[]	optional	Bis zu 5 Nutzer, die im Ticket geschrieben haben, je als Discord-Nutzer-ID oder als Teil eines Benutzernamens. Bei GET durch Komma getrennt, bei POST als Array.
participants_mode	string	optional	`all` (Standard) verlangt, dass alle genannten Beteiligten im selben Ticket geschrieben haben, `any` findet Tickets, in denen mindestens einer geschrieben hat.
include_bots	boolean	optional	Bezieht Bot-Nachrichten und Bots als Beteiligte in die Suche ein. Standard ist false.
opened_by	string	optional	Ersteller des Tickets, als Discord-Nutzer-ID oder Teil eines Benutzernamens.
closed_by	string	optional	Discord-Nutzer-ID der Person, die das Ticket geschlossen hat.
channel_id	string	optional	Die Discord-Kanal- oder Thread-ID, die das Ticket genutzt hat.
panel_id	number	optional	Nur Tickets, die aus diesem Panel stammen.
opened_from	number	optional	Unix-Zeitstempel: nur Tickets, die zu diesem Zeitpunkt oder danach geöffnet wurden.
opened_to	number	optional	Unix-Zeitstempel: nur Tickets, die zu diesem Zeitpunkt oder davor geöffnet wurden.
closed_from	number	optional	Unix-Zeitstempel: nur Tickets, die zu diesem Zeitpunkt oder danach geschlossen wurden.
closed_to	number	optional	Unix-Zeitstempel: nur Tickets, die zu diesem Zeitpunkt oder davor geschlossen wurden.
rating_min	number	optional	Mindestbewertung, 1-5.
rating_max	number	optional	Höchstbewertung, 1-5.
limit	number	optional	Ergebnisse pro Seite, 1-50 (Standard 25).
offset	number	optional	Zu überspringende Ergebnisse für die Seitennavigation, höchstens 10000 (Standard 0).

Die Suche ist auf 10 Anfragen pro Minute und Token begrenzt, getrennt von anderen Leseabfragen, und läuft mit einem festen Zeitbudget. Eine Suche, die es nicht rechtzeitig schafft, liefert 504. Grenz die Filter enger ein (etwa mit einem Zeitraum oder einem Panel) statt dieselbe Abfrage zu wiederholen. Werte, die die Prüfung nicht bestehen, werden verworfen statt abgelehnt. Sieh deshalb im Objekt filters der Antwort nach, was tatsächlich angewendet wurde.

Die Suche liest den Transkriptindex, der aufgebaut wird, solange der Server Premium hat, und beim ersten Upgrade für dein vorhandenes Archiv nachgetragen wird. Das Objekt coverage in jeder Antwort sagt dir, wie viele deiner Transkripte indexiert sind (indexed), gemessen an der Gesamtzahl der gespeicherten (total). Läuft ein Nachtrag noch, stimmen die Werte noch nicht überein.

Beispielanfrage: was ein Nutzer gesagt hat, in Tickets, an denen auch ein Teammitglied gearbeitet hat

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"

Beispielanfrage: dieselbe Suche als JSON-Körper

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

Beispielantwort

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