Pesquisa

A pesquisa de mensagens busca mensagens indexadas em relação a uma consulta de texto e um conjunto de filtros. Uma solicitação abrange um único canal, uma guilda, os canais privados do chamador ou vários destes ao mesmo tempo. O recurso Pesquisa de membros de guilda define a pesquisa de membros de guilda, e o recurso Descoberta define a pesquisa de guildas públicas.

O Decoding Chat resolve o escopo solicitado no conjunto de canais que o chamador pode pesquisar e, em seguida, executa a consulta sobre esse conjunto. Uma pesquisa de canal privado abrange apenas a conta autenticada, e o conjunto contém um canal de guilda apenas enquanto o chamador pode ler seu histórico.

A correspondência de termos e a tolerância a erros de digitação dependem do backend de pesquisa da instância, Elasticsearch ou Meilisearch. A correspondência de filtro é exata.

Message search result object

O corpo que uma pesquisa concluída retorna, contendo uma página de mensagens correspondentes.

Structure

Field	Type	Description
messages¹	array[objeto message]	As mensagens correspondentes na página solicitada
channels²	array[objeto channel]	Os canais aos quais as mensagens retornadas pertencem
total³	integer	O número de mensagens correspondentes à consulta
hits_per_page	integer	O tamanho da página que foi aplicado, ecoado da solicitação
page	integer	O número da página que foi aplicado, ecoado da solicitação
cursor?⁴	array[string]	O cursor opaco que o backend produziu, que nenhum backend aceita de volta

¹ Cada entrada é um objeto de mensagem comum com o campo referenced_message removido, de modo que uma resposta é retornada sem seu pai resolvido, mesmo que sua própria message_reference seja preservada

² Contém uma entrada para cada canal distinto representado em messages, e nunca contém um canal sem nenhuma mensagem retornada

³ Contado sobre todo o escopo resolvido. Em um contexto de canal único sem READ_MESSAGE_HISTORY, total é o número de mensagens em messages

⁴ Presente apenas quando o backend produziu um cursor. Um contexto de canal único, uma instância Meilisearch e uma página que o Decoding Chat reconstruiu depois de encontrar mensagens excluídas nos resultados do backend não retornam nenhum

Search messages nunca honra um cursor fornecido, então faça a paginação por um conjunto de resultados apenas com page.

Mensagens excluídas são omitidas. Ao usar page, o total conta apenas as mensagens existentes. Fornecer um cursor pode deixar páginas mais curtas mesmo quando mais resultados existem.

Example

{
  "messages": [],
  "channels": [],
  "total": 0,
  "hits_per_page": 25,
  "page": 1
}

Search indexing object

O outro corpo 200. O Decoding Chat o retorna quando um canal que a pesquisa precisa nunca foi indexado, ou quando esse canal foi indexado pela última vez antes de 2026-05-23 17:30:00 UTC, uma data fixa embutida no Decoding Chat.

Structure

Field	Type	Description
indexing	boolean	Se um índice que a pesquisa precisava ainda não é consultável, sempre verdadeiro neste corpo

Diferencie os corpos pela presença de indexing, que o objeto de resultado nunca tem. A solicitação enfileira o trabalho de indexação ausente, e uma solicitação idêntica posterior retorna resultados comuns assim que esse trabalho for concluído.

Example

{
  "indexing": true
}

Search scopes

Value	Description
current	A única guilda nomeada por context_guild_id, ou o único canal nomeado por context_channel_id quando nenhum contexto de guilda é fornecido
open_dms¹	Todas as mensagens diretas e canais de mensagens diretas em grupo que o chamador tem abertos
all_dms	Todas as mensagens diretas e canais de mensagens diretas em grupo dos quais o chamador já foi destinatário
all_guilds	Todas as guildas das quais o chamador é membro
all	Todas as guildas das quais o chamador é membro junto com o conjunto de canais all_dms
open_dms_and_all_guilds	Todas as guildas das quais o chamador é membro junto com o conjunto de canais open_dms

¹ Um canal privado está aberto quando o chamador não o fechou, e um canal nomeado por context_channel_id é adicionado ao conjunto aberto para esta solicitação mesmo quando está fechado

Um bot usa current. Fornecer qualquer outro valor com um token de bot retorna 400 INVALID_FORM_BODY no caminho scope com o código de campo BOT_SEARCH_SCOPE_UNAVAILABLE.

Search author types

Value	Description
user	De autoria de uma conta de usuário comum
bot	De autoria de uma conta de bot
webhook¹	De autoria de um webhook

¹ Uma mensagem de webhook é indexada como webhook mesmo quando o aplicativo que executa é um bot

Search content types

Value	Description
image	Tem um anexo enviado cujo tipo de mídia começa com `image/`
sound	Tem um anexo enviado cujo tipo de mídia começa com `audio/`
video	Tem um anexo enviado cujo tipo de mídia começa com `video/`
file	Tem pelo menos um anexo enviado de qualquer tipo de mídia
sticker	Tem pelo menos um sticker
embed¹	Tem pelo menos uma prévia gerada ou embed rico fornecido
link²	Tem uma URL HTTP ou HTTPS em seu próprio texto
poll³	Tem uma enquete
snapshot⁴	É um encaminhamento e, portanto, tem pelo menos um snapshot de mensagem

¹ Derivado da lista de embeds da própria mensagem, portanto, um anexo enviado nunca o satisfaz

² Derivado apenas do texto da mensagem, portanto, uma mensagem que tem apenas um link dentro de um embed não corresponde

³ has nunca corresponde a este valor, e exclude_has com este valor exclui nada

⁴ Um encaminhamento também mescla o conteúdo, embeds, anexos, stickers e menções de seus snapshots em seu próprio documento indexado, então os outros atributos podem ser satisfeitos por conteúdo encaminhado

Search embed types

Value	Description
image¹	Um embed de prévia de imagem
video¹	Um embed de prévia de vídeo
sound²	Um valor que o filtro aceita que não corresponde a nenhum documento
article¹	Um embed de prévia de artigo ou página da web

¹ Comparado em relação à própria string de tipo do embed, que é uma de rich, link, article, image, video, audio, gifv ou bluesky

² Uma prévia de áudio é indexada como audio. Use o tipo de conteúdo sound para encontrar anexos de áudio enviados

Os valores acima são os únicos que este filtro aceita, portanto, um embed rico, link, gifv ou bluesky não pode ser selecionado ou excluído por tipo de embed.

Search sort fields

Value	Description
timestamp	Ordenar por tempo de criação, desempatado por ID de mensagem decrescente
relevance¹	Ordenar pelo que o backend de pesquisa configurado produz quando nenhum campo de ordenação explícito é enviado

¹ sort_order não é aplicado a este valor

Uma instância Meilisearch ordena relevance por suas próprias regras de classificação. Uma instância Elasticsearch aplica seu desempate de ID de mensagem decrescente como a única chave de ordenação, então relevance lá é equivalente a timestamp com um sort_order de desc.

Search sort orders

Value	Description
asc	Mais antigos primeiro
desc	Mais novos primeiro

Search messages

POST/v1/search/messages

Bot

Pesquisa mensagens indexadas no escopo resolvido. Retorna um objeto de resultado da pesquisa de mensagens em caso de sucesso, ou um objeto de indexação de pesquisa quando um índice necessário não é consultável ainda.

Limitations

Um bot é restrito ao escopo current.
O chamador deve ser um destinatário de todos os canais privados que contribuem para a pesquisa.
Um escopo de guilda inclui um canal de guilda apenas quando o chamador possui VIEW_CHANNEL e READ_MESSAGE_HISTORY nele.
Um contexto de canal único exige associação à guilda e apenas VIEW_CHANNEL. Sem READ_MESSAGE_HISTORY o limite de histórico de mensagens da guilda se aplica a cada mensagem retornada.
Uma guilda com restrição de idade ou contexto de canal único exige uma conta com idade suficiente para conteúdo com restrição de idade e, de outra forma, retorna 403 NSFW_CONTENT_AGE_RESTRICTED.
Uma instância sem um backend de pesquisa configurado retorna 403 FEATURE_TEMPORARILY_DISABLED.

Todo escopo que pode incluir um canal de guilda chama o Gateway principal. Uma chamada ao Gateway que atinge o tempo limite retorna 504 GATEWAY_TIMEOUT, uma resposta que não pode ser interpretada retorna 502 BAD_GATEWAY, e um Gateway que está sobrecarregado ou inacessível retorna 503 SERVICE_UNAVAILABLE.

JSON body

Todo campo é opcional, embora o escopo current padrão exija context_guild_id ou context_channel_id. Um filtro omitido não é aplicado.

Field	Type	Description
scope?¹	string	Search scope a resolver (padrão `current`)
context_channel_id?²	snowflake	O ID do canal que fornece o contexto do canal
context_guild_id?²	snowflake	O ID da guilda que fornece o contexto da guilda
channel_ids?³	array[snowflake]	Os IDs de canal para estreitar o escopo resolvido (no máximo 500)
channel_id?⁴	array[snowflake]	Um alias de `channel_ids` (no máximo 500)
hits_per_page?	integer	O número de mensagens em cada página (1-25, padrão 25)
page?⁵	integer	O número da página (1-9007199254740991, padrão 1)
cursor?⁶	array[string]	O cursor opaco retornado por uma página anterior, aceito e depois descartado
min_id?⁷	snowflake	O menor ID de mensagem a ser correspondido, aplicado exclusivamente
max_id?⁷	snowflake	O maior ID de mensagem a ser correspondido, aplicado exclusivamente
content?⁸	string	A consulta de texto livre (1-1024 caracteres)
contents?⁹	array[string]	As consultas de texto livre alternativas (no máximo 100, 1-1024 caracteres cada)
exact_phrases?¹⁰	array[string]	As frases que devem corresponder todas (no máximo 10, 1-1024 caracteres cada)
exclude_channel_id?	array[snowflake]	Os IDs de canal, qualquer um dos quais exclui uma mensagem (no máximo 500)
author_id?¹¹	array[snowflake]	Os IDs de usuário do autor, qualquer um dos quais pode corresponder (no máximo 100)
exclude_author_id?	array[snowflake]	Os IDs de usuário do autor, qualquer um dos quais exclui uma mensagem (no máximo 100)
author_type?¹¹	array[string]	Author types, qualquer um dos quais pode corresponder (no máximo 20)
exclude_author_type?	array[string]	Author types, qualquer um dos quais exclui uma mensagem (no máximo 20)
mentions?¹²	array[snowflake]	Os IDs de usuário, todos os quais devem ser mencionados (no máximo 100)
exclude_mentions?	array[snowflake]	Os IDs de usuário, qualquer um dos quais exclui uma mensagem (no máximo 100)
mention_everyone?	boolean	Se uma mensagem correspondente tem uma menção everyone
pinned?	boolean	Se uma mensagem correspondente está fixada
has?¹²	array[string]	Content types, todos os quais devem estar presentes (no máximo 20)
exclude_has?	array[string]	Content types, nenhum dos quais pode estar presente (no máximo 20)
embed_type?¹²	array[string]	Embed types, todos os quais devem estar presentes (no máximo 20)
exclude_embed_type?	array[string]	Embed types, qualquer um dos quais exclui uma mensagem (no máximo 20)
embed_provider?¹² ¹³	array[string]	Os nomes de provedor de embed, todos os quais devem estar presentes (no máximo 50, 1-256 caracteres cada)
exclude_embed_provider?¹³	array[string]	Os nomes de provedor de embed, qualquer um dos quais exclui uma mensagem (no máximo 50, 1-256 caracteres cada)
link_hostname?¹² ¹³	array[string]	Os hostnames, todos os quais devem estar presentes (no máximo 100, 1-255 caracteres cada)
exclude_link_hostname?¹³	array[string]	Os hostnames, qualquer um dos quais exclui uma mensagem (no máximo 100, 1-255 caracteres cada)
attachment_filename?¹² ¹³	array[string]	Os nomes de arquivo, todos os quais devem estar presentes (no máximo 100, 1-1024 caracteres cada)
exclude_attachment_filename?¹³	array[string]	Os nomes de arquivo, qualquer um dos quais exclui uma mensagem (no máximo 100, 1-1024 caracteres cada)
attachment_extension?¹² ¹⁴	array[string]	As extensões, todas as quais devem estar presentes (no máximo 50, 1-32 caracteres cada)
exclude_attachment_extension?¹⁴	array[string]	As extensões, qualquer uma das quais exclui uma mensagem (no máximo 50, 1-32 caracteres cada)
sort_by?	string	Search sort field (padrão `timestamp`)
sort_order?	string	Search sort order (padrão `desc`)
include_nsfw?¹⁵	boolean	Se canais com restrição de idade podem contribuir com resultados (padrão false)

¹ Um bot que fornece qualquer valor além de current é rejeitado com 400 INVALID_FORM_BODY no caminho scope

² Consultado apenas pelo escopo current, onde um contexto de guilda vence um contexto de canal, e pelos escopos de canal privado, onde adiciona de volta um canal fechado

³ Todo canal listado já deve estar no escopo resolvido. Um contexto de canal current o ignora completamente

⁴ Lido apenas quando channel_ids está ausente, e então estreita o escopo resolvido exatamente como channel_ids faz

⁵ Apenas page atinge uma página além da primeira

⁶ A rota nunca o honra. Fornecer um serve a primeira página novamente enquanto a resposta ainda ecoa a page solicitada

⁷ Ambos os limites são exclusivos, então min_id corresponde estritamente a mensagens mais novas que ele e max_id corresponde estritamente a mensagens mais antigas que ele

⁸ Correspondido ao texto da mensagem e ao texto do embed coletado. O valor é aparado e despojado de caracteres de formatação e controle antes que seu comprimento seja verificado

⁹ Forneça a consulta de texto em exatamente um entre content e contents

¹⁰ Cada frase deve corresponder, e uma frase corresponde apenas quando seus termos aparecem de forma adjacente e na ordem no texto da mensagem ou no texto de embed coletado

¹¹ Uma mensagem corresponde quando satisfaz qualquer um dos valores listados

¹² Uma mensagem corresponde apenas quando satisfaz todos os valores listados, então fornecer dois valores requer ambos

¹³ Comparado exatamente e diferenciando maiúsculas e minúsculas, portanto, um valor parcial nunca corresponde. Um hostname de link usa o host de URL de um link no texto da mensagem ou de uma URL de embed

¹⁴ Indexado em minúsculas, sem um ponto inicial, e apenas para o segmento final separado por pontos de um nome de arquivo quando esse segmento tem de 1 a 10 caracteres

¹⁵ Honrado apenas para uma conta cuja data de nascimento registrada a coloque em 18 anos ou mais e, de outra forma, tratado como falso. Um bot sempre passa

Um contexto de guilda current rejeita um canal solicitado fora daquela guilda com 400 e o código de campo ALL_CHANNELS_MUST_BELONG_TO_GUILD. Ele rejeita um canal dentro da guilda que o chamador não pode ler com 403 MISSING_PERMISSIONS. Todos os outros escopos rejeitam um canal solicitado que seu conjunto resolvido ainda não contém com 403 MISSING_PERMISSIONS. Use exclude_channel_id para remover um canal.

O Decoding Chat compara attachment_extension sem convertê-lo em minúsculas, então um valor em maiúsculas nunca corresponde. include_nsfw restringe quais canais um escopo resolvido mantém.

Os backends leem min_id e max_id de maneira diferente. Uma instância Elasticsearch compara o ID da mensagem. Uma instância Meilisearch compara todo o segundo da criação que o limite codifica, portanto, uma mensagem criada no mesmo segundo do limite é excluída lá. Uma instância Elasticsearch exige que pelo menos uma entrada contents corresponda e substitui content por esse grupo. Uma instância Meilisearch une o grupo, content e as frases citadas em uma única string de consulta e não requer nenhuma entrada em particular. Fornecer exact_phrases sem contents restringe content ao texto da mensagem sozinho no Elasticsearch.

O escopo current requer um de context_guild_id e context_channel_id. Omitir ambos retorna 400 com o código de campo CONTEXT_CHANNEL_OR_GUILD_ID_REQUIRED no caminho context.

O Decoding Chat resolve um context_guild_id fornecido antes de qualquer outra coisa. Uma guilda que não pode ser resolvida retorna 404 UNKNOWN_GUILD, e uma guilda da qual o chamador não é membro retorna 403 MISSING_PERMISSIONS. Um contexto de guilda pesquisa aquela guilda, restrito a channel_ids quando fornecido e a todos os canais da guilda, caso contrário, e todos os canais do conjunto resultante devem pertencer àquela guilda. Um canal que o chamador não pode visualizar e cujo histórico não pode ler é descartado quando o conjunto veio da guilda e rejeitado com 403 MISSING_PERMISSIONS quando o chamador o nomeou em channel_ids. Um canal restrito por idade que include_nsfw não admite é removido do conjunto antes que a verificação de permissões seja executada, para que nunca cause essa recusa.

Uma guilda cujo nível NSFW é restrito a idade recusa um chamador que não é velho o suficiente com 403 NSFW_CONTENT_AGE_RESTRICTED. Um chamador com idade suficiente pesquisa todos os canais de uma guilda assim, incluindo seus canais com restrição de idade, independentemente de include_nsfw estar definido ou não.

Um contexto de canal pesquisa apenas esse canal e ignora channel_ids, cursor e include_nsfw. Quando o chamador não consegue ler o histórico do canal e a guilda não define nenhum limite de histórico de mensagens, a pesquisa retorna um resultado vazio.

Os escopos all_guilds, all e open_dms_and_all_guilds incluem apenas canais da guilda que o chamador pode visualizar e ler o histórico. Os escopos open_dms e open_dms_and_all_guilds incluem os canais privados abertos do chamador. Os escopos all_dms e all incluem todos os canais privados disponíveis para o chamador, a menos que channel_ids restrinja o conjunto. Um escopo que não resolve nenhum canal retorna um resultado vazio com um total de 0.

Texto pesquisável é o conteúdo da mensagem mais o texto do embed coletado, que cobre títulos de embeds, descrições, URLs, nomes de autor, nomes de provedor, texto de rodapé e nomes e valores de campo, incluindo embeds aninhados.

A moderação de conteúdo verifica toda string no corpo cujo nome de campo não termina em _id ou _ids. Um valor lido de pelo menos três caracteres que corresponde à lista de bloqueio de frases da instância ou possui uma URL bloqueada retorna 403 CONTENT_BLOCKED.

Response

Status	Body	Condition
200	objeto resultado de pesquisa da mensagem \| objeto de indexação da pesquisa	Pesquisa concluída, ou um índice necessário ainda não é consultável
400	error response	Um bot forneceu um escopo diferente de `current`, o escopo `current` não possui contexto ou um canal solicitado não pertence à guilda de contexto, retornando `INVALID_FORM_BODY` em todos os casos
403	error response	Chamador apresenta uma credencial bearer OAuth2, ou a guilda do canal de contexto não pode ser resolvida enquanto um registro salvo da guilda ainda existir, retornando `ACCESS_DENIED` em ambos os casos
403	error response	A conta tem uma ação obrigatória pendente e a solicitação retorna `ACCOUNT_SUSPICIOUS_ACTIVITY`
403	error response	Uma string de corpo é bloqueada pela moderação de conteúdo e a solicitação retorna `CONTENT_BLOCKED`
403	error response	Nenhum backend de pesquisa está configurado para a instância e a solicitação retorna `FEATURE_TEMPORARILY_DISABLED`
403	error response	Um canal solicitado está fora do escopo resolvido, o chamador não é membro da guilda de contexto ou o chamador não consegue visualizar o canal de contexto, retornando `MISSING_PERMISSIONS` em todos os casos
403	error response	A guilda de contexto ou o canal de contexto é restrito por idade e o chamador não tem idade suficiente, e a solicitação retorna `NSFW_CONTENT_AGE_RESTRICTED`
404	error response	Guilda de contexto não pode ser resolvida, ou a guilda do canal de contexto não pode ser resolvida e nenhum registro salvo da guilda existe, retornando `UNKNOWN_GUILD` em ambos os casos
404	error response	O canal de contexto não existe ou é um canal privado do qual o chamador não é destinatário e a solicitação retorna `UNKNOWN_CHANNEL`
404	error response	O próprio registro da conta do chamador está ausente e a solicitação retorna `UNKNOWN_USER`

Side effects

Quando um canal no escopo resolvido nunca foi indexado ou seu índice está desatualizado, a operação coloca um trabalho de indexação em fila para ele e retorna o objeto de indexação de pesquisa.

Rate limit

20 solicitações por 10 segundos para cada usuário autenticado, no bucket search:messages.