Como Usar a Leitura do Registro de Auditoria do Discord Bot para Ferramentas de Moderação Personalizadas

O registro de auditoria do Discord registra cada ação de moderação, alteração de permissão e atualização de configuração do servidor. Por padrão, apenas administradores e membros com a permissão Ver Registro de Auditoria podem ver esses logs nas configurações do servidor. Se você quer construir uma ferramenta de moderação personalizada que monitore, filtre ou alerte sobre eventos específicos do registro de auditoria sem conceder acesso total às configurações do servidor, seu bot precisa usar a intenção de leitura do registro de auditoria. Este artigo explica como habilitar a intenção, escrever código para buscar entradas do registro de auditoria e construir um painel de moderação personalizado simples usando Discord.js.

O que a Intenção de Leitura do Registro de Auditoria Faz e Por Que Você Precisa Dela

O registro de auditoria do Discord é um recurso integrado que registra ações como expulsões, banimentos, alterações de cargos, edições de canais e atualizações de permissão. Por padrão, usuários com a permissão Ver Registro de Auditoria podem ver essas entradas em Configurações do Servidor > Registro de Auditoria. Ao construir um bot de moderação personalizado, você frequentemente precisa ler esses logs automaticamente — por exemplo, para enviar um alerta em tempo real quando um membro é banido ou para gerar um relatório semanal das ações de moderação.

Para acessar entradas do registro de auditoria do seu bot, você deve habilitar a Intenção de Membros do Servidor no Portal do Desenvolvedor Discord. Esta intenção privilegiada informa ao Discord que seu bot solicitará dados do registro de auditoria. Sem ela, o método fetchAuditLogs() retornará um array vazio ou lançará um erro. Uma vez habilitada, seu bot pode ler qualquer entrada do registro de auditoria que o usuário do bot tenha permissão para ver — normalmente, o bot precisa da permissão Ver Registro de Auditoria.

O registro de auditoria fornece informações detalhadas para cada entrada: o tipo de ação (como MEMBER_KICK), o usuário que executou a ação, o usuário ou objeto alvo, o horário da ação e o texto opcional do motivo. Ao filtrar por tipos de ação, você pode criar alertas direcionados — por exemplo, registrar apenas banimentos e expulsões, ou apenas alterações de permissão.

Passos para Habilitar a Leitura do Registro de Auditoria para Seu Bot Discord

Siga estes passos para configurar seu bot para ler entradas do registro de auditoria. Você precisa de um bot já criado no Portal do Desenvolvedor Discord e um projeto básico de bot Discord.js rodando em Node.js.

1. Habilite a Intenção de Membros do Servidor no Portal do Desenvolvedor
   Acesse o Portal do Desenvolvedor Discord e selecione sua aplicação de bot. No menu à esquerda, clique em Bot. Role para baixo até Intenções de Gateway Privilegiadas. Ative a Intenção de Membros do Servidor. Clique em Salvar Alterações no final da página. Esta intenção é necessária para buscar entradas do registro de auditoria.
2. Convide o Bot com a Permissão Ver Registro de Auditoria
   Use o Gerador de URL OAuth2 no Portal do Desenvolvedor. Em Escopos, selecione bot. Em Permissões do Bot, selecione Ver Registro de Auditoria. Copie a URL gerada e abra-a em um navegador para convidar o bot para seu servidor. Sem esta permissão, o bot não pode ler entradas do registro de auditoria mesmo com a intenção habilitada.
3. Instale o Discord.js v14 ou Superior
   Na pasta do seu projeto de bot, execute npm install discord.js@14. O Discord.js v14 inclui suporte completo para busca de registro de auditoria com a classe GuildAuditLogs. Se você usa uma versão mais antiga, atualize seu package.json e reinstale.
4. Escreva Código para Buscar Entradas do Registro de Auditoria
   No arquivo principal do seu bot, adicione um comando ou manipulador de evento que chame guild.fetchAuditLogs(). Por exemplo, para buscar as últimas 10 entradas e registrar seus tipos de ação:
   const auditLogs = await guild.fetchAuditLogs({ limit: 10 });
auditLogs.entries.forEach(entry => console.log(entry.action));
   Este código recupera as 10 entradas mais recentes do registro de auditoria e imprime suas constantes de tipo de ação como MEMBER_KICK ou CHANNEL_CREATE.
5. Filtre por Tipos de Ação Específicos para Ferramentas de Moderação Personalizadas
   Para construir um painel de moderação personalizado, filtre entradas por tipo de ação. Por exemplo, para processar apenas expulsões e banimentos:
   const filteredEntries = auditLogs.entries.filter(entry =>
entry.action === 'MEMBER_KICK' || entry.action === 'MEMBER_BAN'
);
   Você pode então enviar essas entradas para um canal específico, armazená-las em um banco de dados ou acionar um webhook.
6. Lide com Erros e Limites de Taxa
   Envolva sua chamada de busca em um bloco try-catch. Se o bot não tiver a permissão Ver Registro de Auditoria, a busca lançará um DiscordAPIError com código 50013 (Permissões Ausentes). Além disso, a busca do registro de auditoria tem limite de taxa de 5 requisições a cada 5 segundos por servidor. Use uma fila ou atraso se precisar buscar logs com frequência.

Problemas Comuns ao Construir Ferramentas de Moderação Personalizadas com Registros de Auditoria

Bot Retorna Array Vazio ou Nenhuma Entrada

Se seu bot busca registros de auditoria mas recebe um array vazio, verifique duas coisas. Primeiro, confirme que o bot tem a permissão Ver Registro de Auditoria no servidor. Segundo, verifique se a Intenção de Membros do Servidor está habilitada no Portal do Desenvolvedor. Além disso, note que registros de auditoria com mais de 90 dias são automaticamente excluídos pelo Discord, então se o servidor não tiver ações recentes, o array estará vazio.

Erro de Permissões Ausentes (50013)

Este erro ocorre quando o bot tenta buscar registros de auditoria sem a permissão Ver Registro de Auditoria. Reconvide o bot com a permissão correta usando o gerador de URL OAuth2. Você também pode verificar o cargo do bot em Configurações do Servidor > Cargos — certifique-se de que o cargo tem a permissão Ver Registro de Auditoria marcada.

Limite de Taxa ao Buscar Logs com Frequência

O Discord impõe um limite de taxa de 5 requisições de busca de registro de auditoria a cada 5 segundos por servidor. Se seu bot precisar consultar logs continuamente, implemente um atraso entre as requisições ou use um sistema de fila. Para alertas em tempo real, considere usar eventos do Gateway do Discord como GUILD_AUDIT_LOG_ENTRY_CREATE (disponível com a intenção de evento de registro de auditoria) em vez de consultas.

Tipos de Ação do Registro de Auditoria: Eventos Comuns para Ferramentas de Moderação Personalizadas

Tipo de Ação	O Que Registra	Caso de Uso para Ferramentas de Moderação
MEMBER_KICK	Quando um membro é expulso do servidor	Alertar moderadores em um canal privado com nome do membro e motivo
MEMBER_BAN	Quando um membro é banido	Registrar detalhes do banimento incluindo moderador e duração
MEMBER_UNBAN	Quando um membro é desbanido	Rastrear ações de desbanimento para revisão de apelação
MEMBER_ROLE_UPDATE	Quando os cargos de um membro são alterados	Monitorar atribuições e remoções de cargos
CHANNEL_CREATE	Quando um canal ou categoria é criado	Alertar sobre criação de novo canal para revisão
CHANNEL_DELETE	Quando um canal é excluído	Registrar exclusões para trilha de auditoria
CHANNEL_OVERWRITE_CREATE	Quando substituições de permissão são adicionadas a um canal	Rastrear alterações de permissão que afetam o acesso de moderação
GUILD_UPDATE	Quando configurações do servidor como nome ou nível de verificação mudam	Monitorar alterações críticas na configuração do servidor

Você pode usar o enum AuditLogEvent do Discord.js para referenciar esses tipos de ação em seu código. Para uma lista completa, veja a documentação do Discord.js.

Construindo um Comando de Alerta de Moderação Simples

Aqui está um exemplo completo de um comando de barra do Discord.js que busca as últimas 5 entradas do registro de auditoria e as envia para um canal específico. Este comando filtra apenas expulsões e banimentos de membros.

const { SlashCommandBuilder, EmbedBuilder } = require('discord.js');

module.exports = {
  data: new SlashCommandBuilder()
    .setName('modlog')
    .setDescription('Mostrar ações de moderação recentes'),
  async execute(interaction) {
    try {
      const auditLogs = await interaction.guild.fetchAuditLogs({
        limit: 5,
        type: ['MEMBER_KICK', 'MEMBER_BAN']
      });
      if (auditLogs.entries.size === 0) {
        return interaction.reply('Nenhuma ação de moderação recente encontrada.');
      }
      const embed = new EmbedBuilder()
        .setTitle('Ações de Moderação Recentes')
        .setColor(0xFF0000)
        .setTimestamp();
      auditLogs.entries.forEach(entry => {
        const moderator = entry.executor.username;
        const target = entry.target?.username || 'Desconhecido';
        const reason = entry.reason || 'Nenhum motivo fornecido';
        embed.addFields({
          name: `${entry.action} - ${target}`,
          value: `Moderador: ${moderator}\nMotivo: ${reason}`
        });
      });
      await interaction.reply({ embeds:  });
    } catch (error) {
      console.error(error);
      await interaction.reply('Falha ao buscar registros de auditoria. Verifique as permissões do bot.');
    }
  }
};

Este comando usa o parâmetro type para filtrar apenas expulsões e banimentos. Você pode estendê-lo para incluir outros tipos de ação adicionando-os ao array. O bot deve ter a permissão Ver Registro de Auditoria e a Intenção de Membros do Servidor habilitada.

Conclusão

Agora você pode construir uma ferramenta de moderação personalizada que lê registros de auditoria do Discord programaticamente usando a Intenção de Membros do Servidor e o método fetchAuditLogs() no Discord.js. Comece habilitando a intenção no Portal do Desenvolvedor e convidando o bot com a permissão Ver Registro de Auditoria. Em seguida, use a filtragem por tipo de ação para criar alertas direcionados para expulsões, banimentos, alterações de cargo ou edições de canal. Para monitoramento em tempo real, considere mudar para o evento de gateway GUILD_AUDIT_LOG_ENTRY_CREATE em vez de consultas. Esta abordagem mantém seus dados de moderação privados e personalizáveis sem expor as configurações completas do servidor a todos os moderadores.