Bots personalizados

Seu bot, sua marca. Os membros veem seu nome e avatar, não o nosso. Entenda como os bots personalizados funcionam nos bastidores, quais permissões eles precisam, limites de planos e segurança.

Visão geral

Cada implementação do Restore Hub é alimentada por um bot personalizado que você cria e possui. Ao contrário dos bots de verificação compartilhados, em que todos os servidores exibem a mesma marca, seu bot personalizado exibe o nome escolhido, o avatar e (no Premium+) um status personalizado na lista de membros.

Essa abordagem lhe dá controle total da marca e elimina a preocupação com a confiança "este bot está em 50.000 servidores" que os membros geralmente têm com bots compartilhados. Seu bot é exclusivo para você.

O que você precisa

Para adicionar um bot personalizado, você precisa de cinco informações do Discord Developer Portal (https://discord.com/developers/applications):

• ID do cliente - Encontrado na página Informações gerais. Esse é o identificador exclusivo do aplicativo/bot.
• Segredo do cliente - Encontrado em OAuth2 → Geral. Clique em "Reset Secret" (Redefinir segredo) para gerar um novo. Você só pode vê-lo uma vez.
• Token de bot - Encontrado em Bot → Reset Token. Essa é a credencial que autoriza todas as chamadas de API.
• Chave pública - Encontrado em Informações gerais. Usado para verificar cargas úteis de interação do Discord.
• URI de redirecionamento - O URL de retorno de chamada do OAuth2 (por exemplo, https://restorehub.net/api/callback). Deve ser adicionado à lista de Redirecionamentos do OAuth2 no Portal do desenvolvedor.

Aviso: O segredo do cliente e o token do bot são exibidos apenas uma vez quando gerados. Se você os perder, deverá redefinir e gerar novos. O Restore Hub os criptografa com AES-256 em repouso e nunca os exibe no painel após a criação.

Como funcionam as interações HTTP

O Restore Hub usa o Endpoint de Interações do Discord em vez do tradicional Gateway WebSocket. Quando você configura um bot, o Restore Hub fornece a você um URL de endpoint exclusivo, como:

https://restorehub.net/api/interactions/{botId}

Interações HTTP vs. Gateway - Principais diferenças

Você cola essa URL no Discord Developer Portal em General Information → Interactions Endpoint URL. O Discord o verifica com um ping e, uma vez confirmado, encaminha todas as invocações de comandos de barra e cliques em botões para esse ponto de extremidade como solicitações HTTP POST.

Como não há conexão com o gateway, o bot não mantém um WebSocket persistente. Isso tem várias implicações:

• Nenhum ponto de status - O bot aparece na lista de membros sem o círculo verde/amarelo/vermelho. Isso é intencional e tem uma aparência mais limpa.
• Nenhum evento de gateway em tempo real do próprio bot - O bot não recebe eventos brutos como MESSAGE_CREATE ou GUILD_MEMBER_ADD por meio de seu próprio gateway. Os eventos anti-nuke e anti-raid são recebidos por meio de uma conexão de gateway separada em nível de sistema.
• Menor uso de recursos - Sem batimentos cardíacos de WebSocket, sem lógica de retomada/reconexão. Uma solicitação HTTP por interação.
• Melhor dimensionamento - O Restore Hub pode atender a milhares de bots sem manter milhares de conexões de gateway.
• Todas as operações da API REST ainda funcionam - A atribuição de funções, o chute de membros, a criação de canais, a busca de backups e a extração usam a API REST do Discord, que não exige uma conexão de gateway.

Dica: Nos planos Premium+, você pode configurar uma presença de bot personalizada (status e texto de atividade como "Playing Verification" ou "Watching 5,000 members") mesmo sem uma conexão com o Gateway. O Restore Hub gerencia isso por meio de chamadas periódicas à API REST.

Permissões necessárias do Discord

Ao convidar seu bot para um servidor Discord, o link de convite inclui um número inteiro de permissões OAuth2. O Restore Hub solicita as seguintes permissões:

| Permissão | Necessário? | Usado para |
|---|---|---|
| Atribuir e remover a função verificada (e outras funções durante pulls com mapeamento de funções)
| Kick Members (Chutar membros) | Recomendado | Ações de resposta anti-nuke/anti-raid, comando /delunauthed, chutes de segurança
| Banir membros | Opcional | Ações de resposta anti-nuke, aplicação de /blacklist
| View Channels (Exibir canais) | Obrigatório | Leitura da estrutura do canal para backups
| Ler histórico de mensagens | Obrigatório | Fazer backup de mensagens em canais de texto
| Manage Channels | Opcional | Restaurar canais a partir de backups (criar/excluir canais)
gerenciar Guild | Opcional | Restaurar configurações do servidor a partir de backups | Gerenciar Guild | Opcional | Restaurar configurações do servidor a partir de backups
| Manage Guild Expressions | Opcional | Restauração de emojis e adesivos a partir de backups
| Enviar mensagens | Opcional | Enviar mensagens de registro para o canal de registro configurado
| Criar convite instantâneo Gerar links de convite para extração automática de alertas

Aviso: A função mais alta do bot deve estar posicionada acima da função verificada na hierarquia de funções do servidor. O Discord impede que os bots atribuam funções superiores à sua própria função mais alta.

Vários bots e limites de planos

Você pode criar vários bots personalizados em uma única conta do Restore Hub. Cada bot pode ser atribuído a servidores diferentes. Isso é útil se você administra várias comunidades com marcas diferentes.

| Plano | Máximo de bots | Máximo de servidores |
|---|---|---|
| Grátis | 1 | 2 |
| Premium | 5 | 10 |
| Business | 25 | 50 |
enterprise | Ilimitado | Ilimitado | Ilimitado |

Dica: Um único bot pode ser usado em vários servidores. Você não precisa de um bot separado para cada servidor, a menos que queira uma marca diferente por comunidade.

Presença e atividade do bot

No Premium e superior, você pode configurar uma presença personalizada para seu bot. Isso controla o status e o texto da atividade que aparece na lista de membros.

| Configuração | Opções |
|---|---|
| Status | Online, Inativo, Não perturbe, Invisível
| Tipo de atividade: Jogando, assistindo, ouvindo, competindo
| Texto da atividade: Qualquer string (por exemplo, "restorehub.net" ou "Protecting 10K members")

Criptografia e segurança de token de bot

Todas as credenciais confidenciais (token do bot, segredo do cliente) são criptografadas em repouso usando AES-256 com uma chave de criptografia mestre armazenada em variáveis de ambiente, nunca no banco de dados. Quando o Restore Hub precisa fazer uma chamada de API em nome do seu bot, ele descriptografa o token na memória, usa-o e descarta o texto simples.

Os tokens são somente para gravação no painel. Após a configuração inicial, você pode ver o ID do cliente e o URI de redirecionamento (que não são confidenciais), mas o token do bot e o segredo do cliente nunca são exibidos. Se precisar atualizá-los, você deverá inserir novos valores.

O que os bots personalizados não podem fazer

Como o Restore Hub usa interações HTTP em vez do Gateway, há algumas coisas que o bot não pode fazer por conta própria:

• Não é possível ouvir eventos de mensagens brutas - O bot não vê as mensagens quando elas são enviadas. Os backups de mensagens são obtidos por meio da API REST sob demanda.
• Não é possível mostrar indicadores de digitação em tempo real nem responder automaticamente a mensagens - Nenhum gateway significa nenhum evento MESSAGE_CREATE.
• Não é possível detectar a atividade do canal de voz - As atualizações do estado de voz exigem uma conexão com o gateway.
• Não pode ser executado continuamente em segundo plano - O bot só "acorda" quando um usuário aciona uma interação ou quando o Restore Hub faz uma chamada à API REST.

Dica: essas limitações não afetam a funcionalidade principal. Verificação, atribuição de função, extração, backups e todos os recursos de segurança funcionam perfeitamente por meio da API REST e do endpoint de interações.

Comandos de barra (Premium+)

No Premium e superior, seu bot suporta comandos de barra que os administradores de servidor podem usar diretamente no Discord. O Restore Hub registra esses comandos globalmente no seu bot. Comandos disponíveis:

comando | Descrição | Comando | Descrição
|---|---|
| /setup | Configurar o bot no servidor atual (definir função verificada, canal de registro, etc.)
/verify-embed | Publicar uma incorporação do botão de verificação no canal atual
/pull | Iniciar um member pull deste servidor para um servidor de destino
/backup | Criar um backup manual do servidor atual
/restore | Restaurar um backup no servidor atual
/usercount | Mostra quantos membros verificados e extraíveis existem nesse servidor
/info | Exibir informações do bot, tempo de atividade e detalhes do plano
/blacklist | Colocar um usuário do Discord na lista negra para que não seja verificado em todos os seus servidores
/unblacklist | Remover um usuário da sua lista negra
/whitelist | Adicionar uma regra de lista branca para ignorar verificações de segurança
/massrole | Atribuir uma função a todos os membros verificados
/unrole | Remover uma função de todos os membros verificados
/delunauthed | Chutar todos os membros que não foram verificados
/deluser | Remover um membro verificado específico e revogar sua função
/stats | Exibir estatísticas de verificação do servidor e dados do funil
| /alerts | Configurar alertas de nuke/raid/deletion com notificações por e-mail e webhook
| /firewall | Gerenciar regras de firewall (adicionar/remover IP, país, ASN, etc.)