Ao criar ferramentas automatizadas para o Discord, você tem duas formas principais de enviar mensagens e executar ações: um Bot User ou um Webhook. Muitos desenvolvedores confundem esses dois recursos ou usam o errado para uma determinada tarefa. Um Bot User é uma conta completa que pode ler mensagens, moderar servidores e responder a comandos. Um Webhook é uma ferramenta mais simples que apenas envia mensagens para um único canal. Este artigo explica as diferenças essenciais, quando escolher cada opção e como evitar erros comuns.
Principais Conclusões: Bot User vs Webhook
- Bot User (token OAuth2): Conta de bot completa que lê mensagens, modera e responde a comandos.
- URL do Webhook: Endpoint simples que apenas envia mensagens para um canal, sem capacidade de leitura ou moderação.
- Webhook com Nome e Avatar Personalizados: Cada mensagem pode usar um nome de usuário e foto de perfil diferentes sem uma conta de bot.
O Que é um Bot User do Discord e O Que é um Webhook?
Um Bot User é uma conta especial do Discord que você cria através do Portal do Desenvolvedor do Discord. Ela usa um token único para autenticar com a API do Discord. Um Bot User pode entrar em vários servidores, ler todas as mensagens que tem permissão para ver, moderar usuários, gerenciar cargos e responder a comandos de barra ou comandos com prefixo. Ele precisa estar online e conectado ao Gateway do Discord para receber eventos. Normalmente, você executa um Bot User em um servidor ou em um host na nuvem 24 horas por dia, 7 dias por semana.
Um Webhook é um endpoint HTTP mais simples que o Discord fornece para um único canal. Você cria uma URL de Webhook nas configurações de um canal. Qualquer aplicação pode enviar uma requisição POST para essa URL com um payload de mensagem. A mensagem aparece como se tivesse sido enviada pelo nome e avatar configurados no Webhook. Webhooks não leem mensagens, não processam comandos e não ficam conectados ao Discord. São ferramentas de entrega do tipo “disparar e esquecer”.
Principais Diferenças Técnicas
O Bot User usa a API Gateway para receber eventos em tempo real, como novas mensagens, entradas de membros ou mudanças de estado de voz. Ele pode enviar mensagens de acompanhamento e editar ou excluir suas próprias mensagens. Um Webhook usa apenas a API REST. Ele não pode receber eventos, não pode editar mensagens após enviá-las e não pode excluir mensagens. A própria URL do Webhook é um segredo — qualquer pessoa com a URL pode enviar mensagens para aquele canal.
Quando Usar um Bot User vs um Webhook
A escolha depende do que sua automação precisa fazer. Use um Bot User quando sua ferramenta precisar interagir com usuários, ler conteúdo ou realizar gerenciamento do servidor. Use um Webhook quando você só precisar enviar notificações ou logs para um canal e não precisar de nenhuma interação de volta.
Cenários para um Bot User
- Moderação e manipulação de comandos
Se o seu bot precisa responder a comandos de barra, expulsar ou banir usuários, ou remover mensagens, você deve usar um Bot User. Apenas um Bot User pode ler o conteúdo das mensagens e usar os endpoints da API de moderação. - Funcionalidades interativas como enquetes ou jogos
Bots que coletam entrada do usuário através de botões, menus de seleção ou modais exigem um Bot User. Webhooks não podem receber nenhuma interação do usuário. - Operações em vários canais ou servidores
Um Bot User pode enviar mensagens para qualquer canal ao qual tenha acesso em vários servidores. Um Webhook está restrito ao único canal onde foi criado.
Cenários para um Webhook
- Notificações de servidor de serviços externos
Alertas de commit do GitHub, alertas de sistemas de monitoramento ou atualizações de feeds RSS são perfeitos para Webhooks. Você só precisa enviar uma mensagem formatada para um canal. - Formatação personalizada de mensagens com nomes dinâmicos
Cada mensagem de Webhook pode usar um nome de usuário e URL de avatar diferentes. Isso permite simular diferentes remetentes sem várias contas de bot. - Scripts leves e ambientes com poucos recursos
Uma chamada de Webhook é uma única requisição HTTP. Você não precisa executar um processo persistente ou gerenciar um token. Qualquer script que possa fazer um HTTP POST pode usar um Webhook.
Erros Comuns e Limitações
Tratar um Webhook Como um Bot User
Alguns desenvolvedores tentam fazer um Webhook ler mensagens ou responder a comandos. Isso é impossível. Um Webhook não tem conexão com o Gateway e nenhuma permissão de leitura. Se você precisa de comunicação bidirecional, mude para um Bot User.
Expor a URL do Webhook Publicamente
Qualquer pessoa com uma URL de Webhook pode enviar mensagens para aquele canal. Não cole URLs de Webhook em logs de chat públicos, repositórios GitHub ou código JavaScript do lado do cliente. Se uma URL de Webhook for vazada, exclua-a das configurações do canal e crie uma nova.
Limites de Taxa e Limites de Mensagens
Tanto Bot Users quanto Webhooks têm limites de taxa. Bot Users são limitados por token e por servidor. Webhooks têm um limite de taxa separado de 30 requisições por 60 segundos por Webhook. Se você precisar de mensagens de alta frequência, use um Bot User com tratamento adequado de limite de taxa.
Bot User Exige Autorização OAuth2
Para adicionar um Bot User a um servidor, você deve usar o fluxo de autorização OAuth2 com o escopo bot. Isso requer permissões de administrador do servidor. Webhooks podem ser criados por qualquer usuário com a permissão Gerenciar Webhooks em um canal, que geralmente é concedida a moderadores ou cargos específicos.
Bot User vs Webhook: Tabela Comparativa
| Item | Bot User | Webhook |
|---|---|---|
| Ler mensagens | Sim | Não |
| Enviar mensagens | Sim, para qualquer canal acessível | Sim, apenas para o canal onde foi criado |
| Receber comandos | Sim, via eventos do Gateway | Não |
| Editar ou excluir mensagens | Sim | Não |
| Nome personalizado por mensagem | Não, usa o nome do bot | Sim, definido em cada requisição |
| Avatar personalizado por mensagem | Não, usa o avatar do bot | Sim, definido em cada requisição |
| Requer host persistente | Sim, deve ficar 24/7 online | Não, apenas um endpoint HTTP |
| Método de autenticação | Token do bot (secreto) | URL do Webhook (secreta) |
| Limite de taxa | Por token e por servidor | 30 requisições por 60 segundos por Webhook |
Agora você pode decidir qual ferramenta se encaixa no seu projeto. Para bots interativos que moderam, respondem ou coletam entradas, use sempre um Bot User. Para notificações unidirecionais simples com nomes flexíveis, use um Webhook. Se você precisar de ambos os recursos em um único sistema, combine um Bot User que ouve eventos e um Webhook que envia notificações formatadas para um canal de log. Essa abordagem híbrida oferece controle total sem complicar demais sua arquitetura.