Pesquisar transcrições

GET/<guild_id>/api/transcripts/search

Pesquisa em cada ticket fechado do servidor, não só nos metadados: o que foi dito dentro dele, quem disse, quem participou, quando foi aberto ou fechado, o painel, a avaliação ou o ID do canal no Discord. É o mesmo mecanismo da busca detalhada no painel. Exige a permissão `search_transcripts` (desativada por padrão).

POST/<guild_id>/api/transcripts/search

Idêntico, mas com os filtros enviados num corpo JSON em vez de parâmetros de consulta. Mais prático para consultas longas e listas de participantes. Se você enviar os dois, o corpo prevalece.

Cada resultado traz os metadados do ticket, até 8 participantes e, se você pesquisou por conteúdo, até 3 trechos de mensagens correspondentes para você ver *por que* ele combinou. Leve o TicketId de qualquer resultado direto para Obter uma transcrição e ver a lista completa de mensagens, ou para Obter o HTML de uma transcrição e pegar o arquivo renderizado.

Filtros (todos opcionais, combine quantos quiser)

Nome	Tipo	Obrigatório	Descrição
q	string	opcional	Busca livre no conteúdo das mensagens, máx. 200 caracteres. O índice ignora palavras com menos de 3 caracteres.
said_by	string	opcional	Só considera conteúdo escrito por este ID de usuário do Discord. Combine com `q`.
participants	string[]	opcional	Até 5 usuários que escreveram no ticket, cada um como ID do Discord ou parte de um nome de usuário. Separados por vírgula no GET, como array no POST.
participants_mode	string	opcional	`all` (padrão) exige que todos os participantes listados tenham escrito no mesmo ticket; `any` encontra tickets em que pelo menos um escreveu.
include_bots	boolean	opcional	Inclui mensagens de bots e os próprios bots como participantes na busca. Falso por padrão.
opened_by	string	opcional	Quem criou o ticket, como ID do Discord ou parte de um nome de usuário.
closed_by	string	opcional	ID do Discord de quem fechou o ticket.
channel_id	string	opcional	ID do canal ou tópico do Discord usado pelo ticket.
panel_id	number	opcional	Só os tickets abertos por este painel.
opened_from	number	opcional	Timestamp Unix: só os tickets abertos nesse momento ou depois.
opened_to	number	opcional	Timestamp Unix: só os tickets abertos nesse momento ou antes.
closed_from	number	opcional	Timestamp Unix: só os tickets fechados nesse momento ou depois.
closed_to	number	opcional	Timestamp Unix: só os tickets fechados nesse momento ou antes.
rating_min	number	opcional	Avaliação mínima, 1-5.
rating_max	number	opcional	Avaliação máxima, 1-5.
limit	number	opcional	Resultados por página, 1-50 (25 por padrão).
offset	number	opcional	Resultados a pular para a paginação, máx. 10000 (0 por padrão).

A busca é limitada a 10 requisições por minuto por token, separada das demais leituras, e roda com um tempo máximo rígido. Uma busca que não termina a tempo retorna 504. Estreite os filtros (acrescente um período ou um painel) e tente de novo, em vez de repetir a mesma consulta. Valores que não passam na validação são descartados em vez de recusados, então confira o objeto filters devolvido na resposta para ver o que realmente foi aplicado.

A busca lê o índice de transcrições, montado enquanto o servidor tem Premium e completado com seu arquivo existente na primeira vez que você assina. O objeto coverage de cada resposta informa quantas das suas transcrições estão indexadas (indexed) em relação ao total guardado (total). Se a incorporação ainda estiver rodando, os números ainda não vão bater.

Exemplo de requisição: o que um usuário disse, em tickets nos quais alguém da equipe também atuou

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"

Exemplo de requisição: a mesma busca como 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

Exemplo de resposta

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