Você adicionou novos comandos de barra ao código do seu bot Discord, mas os comandos antigos ainda aparecem no servidor. Os novos comandos não são exibidos ou o bot não responde a eles. Isso acontece porque o Discord armazena em cache as definições dos comandos de barra e não sincroniza automaticamente as alterações com o código do bot. Este artigo explica a causa raiz das falhas de sincronização e fornece correções passo a passo para comandos globais e específicos de servidor.
Principais Conclusões: Corrigindo a Sincronização de Comandos de Barra em Bots Discord
- Sincronização global via código do bot: Execute a função de sincronização uma vez após alterações no código para enviar as novas definições para a API do Discord.
- Sincronização de servidor via ID do servidor: Use a sincronização específica do servidor para testar comandos instantaneamente sem esperar pelo cache global.
- Portal do Desenvolvedor Discord > Bot > Redefinir Token: Regere o token do bot se os comandos ainda falharem ao registrar após várias tentativas de sincronização.
Por que os Comandos de Barra Não Atualizam Automaticamente
Os comandos de barra do Discord são registrados através da API do Discord, não diretamente do código em execução do seu bot. Quando você edita as definições de comandos em seus arquivos de origem, o bot deve enviar uma solicitação de substituição em massa para os servidores do Discord. Se você não chamar a função de sincronização, o Discord mantém as definições antigas dos comandos em cache. Esse cache se aplica globalmente para comandos registrados sem um ID de servidor e pode levar até uma hora para atualizar automaticamente. Para comandos específicos de servidor, o cache atualiza mais rápido, mas ainda requer uma chamada de sincronização manual. A causa raiz mais comum é a lógica de sincronização ausente ou incorreta na sequência de inicialização do bot.
Registro de Comandos Global vs. de Servidor
Um comando de barra global está disponível em todos os servidores onde o bot está presente. O Discord armazena em cache comandos globais por até uma hora. Um comando de servidor tem escopo em um único servidor e é atualizado quase imediatamente após a sincronização. Os desenvolvedores geralmente usam comandos de servidor durante os testes para evitar a espera de uma hora. Ao implantar comandos finais, você deve mudar para o registro global e remover o parâmetro de ID do servidor.
Limites de Taxa no Registro de Comandos
O Discord aplica limites de taxa às solicitações de criação e atualização de comandos. Você pode enviar até 200 atualizações de comandos globais por dia por bot. Exceder esse limite faz com que a API rejeite novas solicitações. Se você executar seu bot várias vezes em um curto período, pode atingir o limite de taxa e ver comandos antigos persistirem. Verifique os cabeçalhos de resposta da API para valores retry-after para determinar se você está sendo limitado.
Passos para Forçar a Atualização dos Comandos de Barra
Os passos a seguir assumem que você usa discord.js v14 ou uma biblioteca similar. Ajuste os nomes dos métodos específicos da biblioteca conforme necessário.
- Adicione uma função de sincronização à inicialização do bot
No arquivo principal do bot, chame o método de substituição em massa da API REST após definir os comandos. No discord.js, userest.put(Routes.applicationCommands(clientId), { body: commands })para comandos globais ouRoutes.applicationGuildCommands(clientId, guildId)para comandos de servidor. Coloque essa chamada dentro de uma função assíncrona que é executada após o login do cliente. - Execute o bot uma vez para enviar os novos comandos
Pare o bot se estiver em execução. Inicie-o novamente. A função de sincronização enviará a lista completa de definições de comandos para o Discord. Aguarde até que o console mostre uma mensagem de sucesso ou verifique respostas HTTP 200. Após o bot estar online, teste os comandos em um servidor. - Limpe o cache de comandos manualmente no Discord
Se os comandos ainda mostrarem nomes antigos, force uma atualização do cache saindo e entrando novamente no canal de voz ou reiniciando o cliente Discord. Para problemas persistentes de cache, clique com o botão direito no ícone do servidor e selecione Configurações do Servidor > Integrações > Bots e Aplicativos. Remova o bot e adicione-o novamente usando o link de convite. - Exclua comandos individuais pelo Portal do Desenvolvedor
Acesse o Portal do Desenvolvedor Discord, selecione seu aplicativo e clique na guia Comandos de Barra em Informações Gerais. Exclua manualmente quaisquer comandos obsoletos. Em seguida, execute a sincronização do bot novamente para registrar apenas os comandos atuais. - Redefina o token do bot e faça um novo convite
No Portal do Desenvolvedor, vá em Bot > Redefinir Token. Copie o novo token e atualize o código do bot. Convide novamente o bot para o servidor usando o novo token. Isso limpa todos os registros de comandos em cache anteriores e força uma nova sincronização.
Se os Comandos de Barra Ainda Não Atualizarem Após a Correção Principal
O Bot Não Responde a Nenhum Comando de Barra
Se o bot exibe comandos no menu de comandos de barra, mas não responde, o problema provavelmente está no manipulador de interações. Certifique-se de que o código do bot inclua um ouvinte de eventos para interactionCreate. No discord.js, use client.on('interactionCreate', async interaction => { ... }). Verifique se o manipulador executa o arquivo de comando correto e não lança um erro não tratado. Adicione um console.log dentro do manipulador para verificar se o bot recebe a interação.
Comandos Aparecem em um Servidor, mas Não em Outro
Isso geralmente significa que você registrou comandos como específicos de servidor para o primeiro servidor, mas não os registrou globalmente. Para corrigir, altere o método de registro para global removendo o parâmetro de ID do servidor da rota REST. Em seguida, execute a função de sincronização novamente. Comandos globais se propagam para todos os servidores dentro de uma hora.
Erro de Limite de Taxa 429 Aparece no Console
O Discord retorna um código de status 429 quando você excede o limite de taxa de atualização de comandos. Aguarde o número de segundos especificado no cabeçalho de resposta Retry-After. Não reinicie o bot durante essa espera. Após o período de espera, execute a função de sincronização uma vez. Para evitar atingir o limite no futuro, chame a função de sincronização apenas quando as definições de comando mudarem, não em toda reinicialização do bot.
Métodos de Registro de Comandos do Bot Discord: Global vs. Servidor
| Item | Comandos Globais | Comandos de Servidor |
|---|---|---|
| Escopo | Todos os servidores onde o bot está presente | Apenas o servidor especificado |
| Tempo de atualização do cache | Até 1 hora | Instantâneo após sincronização |
| Limite de taxa | 200 atualizações por dia | Mesmo pool dos comandos globais |
| Melhor para | Implantação em produção | Testes durante o desenvolvimento |
| Rota da API | /applications/{id}/commands |
/applications/{id}/guilds/{guildId}/commands |
Após terminar os testes com comandos de servidor, remova o ID do servidor da rota e execute a função de sincronização novamente para registrar comandos globalmente. Não mantenha comandos de servidor em produção, pois eles não aparecerão em outros servidores.
Agora você pode forçar atualizações de comandos de barra adicionando uma função de sincronização, limpando o cache do Discord ou redefinindo o token do bot. Da próxima vez que editar um nome de comando ou opção, execute a função de sincronização uma vez e aguarde até uma hora para propagação global. Para controle avançado, use a rota específica de servidor durante o desenvolvimento e mude para global apenas quando implantar em todos os servidores.