Cercare trascrizioni

GET/<guild_id>/api/transcripts/search

Cerca in tutti i ticket chiusi del server, non solo tra i metadati: cosa è stato detto dentro il ticket, chi lo ha detto, chi ha partecipato, quando è stato aperto o chiuso, da quale pannello arriva, che valutazione ha o in quale canale Discord si trovava. È lo stesso motore della ricerca approfondita nella dashboard. Richiede il permesso `search_transcripts` (disattivato per impostazione predefinita).

POST/<guild_id>/api/transcripts/search

Identico, ma con i filtri inviati in un corpo JSON invece che come parametri della query. Più comodo per ricerche lunghe ed elenchi di partecipanti. Se invii entrambi, vince il corpo.

Ogni risultato porta con sé i metadati del ticket, fino a 8 partecipanti e, se hai cercato per contenuto, fino a 3 estratti dei messaggi corrispondenti, così vedi *perché* il ticket è stato trovato. Prendi il TicketId di un risultato e passalo a Ottenere una trascrizione per l'elenco completo dei messaggi, oppure a Ottenere l'HTML di una trascrizione per l'archivio impaginato.

Filtri (tutti facoltativi: combinane quanti vuoi)

Nome	Tipo	Obbligatorio	Descrizione
q	string	facoltativo	Ricerca libera nel contenuto dei messaggi, massimo 200 caratteri. Le parole più corte di 3 caratteri vengono ignorate dall'indice.
said_by	string	facoltativo	Considera solo il contenuto scritto da questo ID utente Discord. Usalo insieme a `q`.
participants	string[]	facoltativo	Fino a 5 utenti che hanno scritto nel ticket, ognuno come ID utente Discord o parte di un nome utente. Separati da virgola con GET, come array con POST.
participants_mode	string	facoltativo	`all` (predefinito) richiede che tutti i partecipanti indicati abbiano scritto nello stesso ticket; `any` trova i ticket in cui ha scritto almeno uno di loro.
include_bots	boolean	facoltativo	Include nella ricerca i messaggi e i partecipanti bot. Predefinito false.
opened_by	string	facoltativo	Chi ha aperto il ticket, come ID utente Discord o parte di un nome utente.
closed_by	string	facoltativo	ID Discord di chi ha chiuso il ticket.
channel_id	string	facoltativo	L'ID del canale o del thread Discord usato dal ticket.
panel_id	number	facoltativo	Solo i ticket aperti da questo pannello.
opened_from	number	facoltativo	Timestamp Unix: solo i ticket aperti a partire da questo momento.
opened_to	number	facoltativo	Timestamp Unix: solo i ticket aperti fino a questo momento.
closed_from	number	facoltativo	Timestamp Unix: solo i ticket chiusi a partire da questo momento.
closed_to	number	facoltativo	Timestamp Unix: solo i ticket chiusi fino a questo momento.
rating_min	number	facoltativo	Valutazione minima, da 1 a 5.
rating_max	number	facoltativo	Valutazione massima, da 1 a 5.
limit	number	facoltativo	Risultati per pagina, da 1 a 50 (predefinito 25).
offset	number	facoltativo	Risultati da saltare per la paginazione, massimo 10000 (predefinito 0).

La ricerca è limitata a 10 richieste al minuto per token, separatamente dalle altre letture, e gira con un tempo massimo molto stretto. Una ricerca che non riesce a finire in tempo risponde 504. Restringi i filtri (aggiungi un intervallo di date o un pannello) e riprova, invece di ripetere la stessa query. I valori non validi vengono scartati anziché far fallire la richiesta, quindi controlla l'oggetto filters restituito nella risposta per vedere esattamente cosa è stato applicato.

La ricerca legge l'indice delle trascrizioni, che viene costruito mentre il server ha Premium e riempito a ritroso su tutto l'archivio esistente al primo passaggio a Premium. L'oggetto coverage presente in ogni risposta ti dice quante delle tue trascrizioni sono indicizzate (indexed) sul totale conservato (total). Se l'indicizzazione a ritroso è ancora in corso, i due numeri non coincidono.

Esempio di richiesta: cosa ha detto un utente, nei ticket seguiti anche da un certo membro dello staff

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"

Esempio di richiesta: la stessa ricerca in un corpo 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

Esempio di risposta

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