Usar bots
Bots acrescentam comandos, votações, música e miniapps ao seu servidor. Este guia é para quem usa ou administra o Monky. Você não precisa programar para seguir estas instruções.
Quer criar um bot?
Comece em Seu primeiro bot. A documentação do SDK de bots tem guias separados por recurso, exemplos e referência completa da API.
O que é um bot?
É um programa externo que se conecta ao servidor e aparece na lista de membros com o selo BOT. Seu operador mantém esse processo em execução; vincular um bot no Monky não instala nem hospeda automaticamente o programa.
O bot publica seu próprio nome e avatar. A administração do servidor controla o vínculo e as permissões, não a identidade visual dele.
Duas formas de adicionar um bot
Você precisa ser dono/administrador ou ter Adicionar e gerenciar bots. Abra nome do servidor → Configurações do Servidor → Bots.
1. Via URL (recomendado)
Peça ao operador a URL do manifest, não a página do GitHub nem a URL de download do programa.
- Cole a URL em Vincular bot por URL e clique em Vincular.
- Confira o nome, a descrição e as capacidades solicitadas.
- Ative somente os acessos que deseja conceder. Os switches começam desligados.
- Clique em Confirmar e vincular bot e aguarde a conclusão.
O servidor precisa alcançar o manifest e o bot precisa conseguir conectar de volta ao servidor. Se um está em uma VPS e o outro no seu computador, localhost não conecta essas duas máquinas. O operador encontra os detalhes em Requisitos de rede do bot.
2. Manual por token (avançado)
Use quando o bot não expõe um manifest acessível:
- Abra Mostrar opção avançada e gere um vínculo/token.
- Copie o token mostrado uma única vez e informe-o no setup do bot.
- Aguarde o processo conectar e anunciar sua identidade e capacidades.
- Abra as configurações desse bot, revise Permissões e salve.
O token autentica o vínculo; não aprova ações. Uma reserva ainda sem identidade fica aguardando a conexão na administração de bots. Não divulgue o token nem o confunda com o token do GitHub usado para baixar releases privadas.
Executar um comando
Em um canal de texto, digite /. O catálogo mostra o bot responsável, o nome e a descrição de cada comando. Comandos podem ter nomes traduzidos de acordo com sua preferência de idioma.
- Navegue com as setas e confirme por clique ou
Enter. - Espaço seleciona o comando destacado sem executá-lo imediatamente.
- Preencha os campos obrigatórios; os opcionais aparecem em +N.
- Em buscas com sugestões, selecione um resultado válido. Digitar texto sozinho não confirma uma escolha de autocomplete.
- Use os controles de cancelamento quando não quiser continuar.
Comandos sem parâmetros e sem download podem começar assim que forem selecionados. No autocomplete, confirmar o último obrigatório pode executar imediatamente quando não há opcionais. Havendo opcionais, o compositor permanece aberto para você revisar e enviar.
Respostas, formulários e votações
A resposta padrão de um comando é privada: só a conexão que executou o comando a vê, dentro do chat. Ela não entra no histórico público. O bot pode publicar explicitamente um resultado, se tiver permissão.
Uma votação pública é diferente: fica no canal para os membros autorizados responderem e pode continuar após você fechar a conversa. Os controles informam as escolhas e o estado; tempo, limite de participantes e possibilidade de trocar o voto dependem da configuração da votação.
Preferências e permissões
Clique com o botão direito no bot — na lista de membros ou em sua mensagem — e abra Configurações do bot. Também há acesso pela lista de bots nas configurações do servidor.
| Seção | Quem controla | O que muda |
|---|---|---|
| Minhas preferências | Você | Idioma desse bot e preferências pessoais neste dispositivo |
| Comportamento | Administração ou cargo autorizado a configurar bots | Opções compartilhadas que o próprio bot disponibiliza neste servidor |
| Permissões | Quem pode gerenciar bots | Capacidades que o bot pode executar nesse servidor |
| Armazenamento | Quem pode gerenciar bots (no servidor) e você (neste computador) | Espaço que o bot ocupa no servidor e no seu computador, limites e exclusão |
Quem pode gerenciar bots também vê, no topo das configurações, a URL do Manifest usada para vincular o bot, com um botão para copiá-la. Bots vinculados por token, ou antes de o servidor guardar essa informação, aparecem sem URL registrada.
Seguir o Monky usa o idioma do aplicativo. Uma escolha própria vale somente para esse bot/servidor/identidade neste perfil; não traduz mensagens antigas nem renomeia os comandos para todo mundo.
Ao revisar capacidades, o servidor encerra o trabalho anterior daquele bot, incluindo interações e mídia. Uma reconexão pode acontecer; alterações não devem ser usadas como tentativa de "reiniciar" uma música em andamento.
Quem pode usar
Além da autorização do bot, a pessoa precisa de Executar comandos de bots no cargo. O canal precisa manter Permitir comandos de bots ligado. Desligar esse switch bloqueia comandos e interações naquele canal, inclusive para administradores.
Bots não recebem cargos de pessoas. Estar autorizado a publicar áudio ou abrir um miniapp não dá acesso irrestrito a canais privados.
Ferramentas no seu computador
Permissão no servidor não autoriza o seu dispositivo. Alguns comandos pedem que o Monky prepare ferramentas locais. O pedido explica o motivo, as ferramentas e o espaço necessário; você pode negar, permitir até desconectar ou manter a autorização até revogá-la.
Ao selecionar o comando, Verificando permissões e ferramentas locais... indica a preparação antes de liberar os campos, mesmo com autorização já concedida. Você pode cancelar fechando o comando; uma falha aparece no lugar do carregamento.
Em Configurações → Ferramentas de bots, consulte ferramentas, espaço, cache, permissões e tarefas. Remover uma ferramenta ou revogar acesso interrompe o trabalho afetado. As instalações são gerenciadas pelo Monky, não uma autorização para o bot enviar scripts arbitrários.
Baixar para o Soundboard
Configure antes uma pasta em Configurações → Soundboard. O download autorizado mostra nome, destino e origem e nunca substitui um arquivo existente. Ouvir uma prévia não baixa o som para essa pasta nem transmite áudio para a chamada.
Para voltar a confirmar o nome de cada arquivo, abra Configurações do bot → Minhas preferências → Perguntar o nome antes de baixar e salve.
Miniapps na sala de voz
Um bot pode abrir uma tela interativa compartilhada na sala. O convite e o card ficam no palco de voz, não como um site externo que se abre sozinho.
Abrir miniapp inicia sua visualização. Sair do miniapp fecha só a sua visualização. Encerrar miniapp, disponível para quem o criou ou para um administrador autorizado, encerra aquela instância para todos.
Antes de fechar, o miniapp pode fazer uma pergunta, como se você quer salvar a partida. Responda no próprio miniapp ou clique em Fechar agora (ou Encerrar agora) para não esperar. Sair da sala nunca espera o miniapp.
Você pode navegar pelo Monky, como um canal de texto, o Início ou outro servidor, sem fechar o miniapp: enquanto você estiver na chamada, ele continua aberto em segundo plano, e um aviso na barra lateral oferece Voltar ao miniapp para retomá-lo no palco. O som continua no volume escolhido, e o próprio miniapp pode pausar enquanto você está longe. Sair da sala o fecha.
Com a visualização aberta, o card ganha o mesmo controle de volume de uma transmissão de tela, no canto inferior direito: passe o mouse sobre o botão (ou chegue com Tab) para ajustar de 0 a 200% e clique nele para mutar. Volume e mudo valem para todos os miniapps do mesmo bot; o volume fica salvo neste computador e o mudo dura até você sair da sala.
Dados guardados pelo bot
Bots com a capacidade Guardar dados no servidor mantêm arquivos próprios no servidor, como saves de jogos. Só quem pode gerenciar bots vê, na aba Armazenamento das configurações do bot, quanto eles ocupam, ajusta o limite (100 MB por padrão) e apaga os dados; as demais pessoas veem ali apenas os dados do próprio computador. Desvincular o bot apaga o que ele guardou no servidor.
Se o bot também pode pedir para guardar dados nos computadores, ao abrir um miniapp você escolhe Não guardar, Só nesta sessão ou Sempre. Sem permitir, o miniapp funciona normalmente e você ainda pode baixar arquivos manualmente. Em Configurações do bot → Armazenamento → Neste computador, mude a decisão (Perguntar, Sempre ou Nunca), o limite (50 MB por padrão) ou apague os dados. Em Configurações → Ferramentas de bots → Dados de bots neste computador, você vê e apaga o que todos os bots guardaram aqui, inclusive de servidores e bots que já não usa. O Monky nunca apaga esses dados remotamente.
Quando o espaço no seu computador está quase cheio, o card do miniapp mostra Armazenamento quase cheio; quando enche, Armazenamento cheio: saves automáticos pausados. Quem pode gerenciar bots também recebe esse aviso sobre o armazenamento no servidor. Clique no aviso para liberar espaço ou aumentar o limite.
Bots que recebem voz
Um bot só pode receber microfones se solicitar a capacidade Ouvir microfones nas salas de voz e um administrador aprová-la em Configurações do bot → Permissões. Publicar áudio é uma permissão independente: bots de música não começam a ouvir automaticamente.
A lista de participantes mostra Ouvindo vozes enquanto a recepção autorizada está ativa. O microfone e os fones usam o símbolo administrativo de proibição quando falta, respectivamente, permissão para transmitir ou ouvir. Ter permissão sem ativar a recepção não mostra o aviso de escuta.
Deafen do bot interrompe a recepção; silenciar o próprio microfone impede que ele seja recebido. Mutar o bot só para você muda apenas sua reprodução local, não a autorização de escuta do bot. Câmera, tela, Soundboard e prévias privadas não fazem parte dessa API.
O SDK não grava nem transcreve conversas. O operador do bot é responsável por informar qualquer processamento, envio externo ou retenção que ele implementar. Consulte o guia de voz antes de conceder acesso.
Monky Bot (bot oficial)
O MonkyBot oferece utilitários, lembretes, sorteios, música e jogos. A instalação do processo é descrita no repositório do bot; depois, faça o vínculo e a revisão no Monky.
| Objetivo | Comandos |
|---|---|
| Conferir disponibilidade e ajuda | /ping, /ajuda |
| Utilitários | /dado, /moeda, /8ball |
| Agendar lembrete e criar sorteio | /lembrete, /sorteio |
| Buscar e adicionar música | /play |
| Ver a reprodução | /queue, /nowplaying |
| Controlar a fila | /pause, /resume, /skip, /remove, /clear |
| Parar ou sair | /stop, /leave |
| Abrir uma partida compartilhada | /jogo-da-velha |
Os nomes exibidos podem variar com o idioma. Use o catálogo para ver os nomes locais, parâmetros e descrições da versão instalada.
Entre em voz antes de usar os comandos musicais. Há uma fila por servidor; se o bot já estiver em outra sala, entre nela para controlar a reprodução. A busca, a resolução e a conversão de áudio usam o cliente de quem pediu, com consentimento; a VPS do bot não substitui automaticamente esse dispositivo.
Spotify, playlists, álbuns e transmissões ao vivo não são suportados por essa integração. Use somente conteúdo cuja reprodução você está autorizado a realizar e respeite os termos do provedor. Mudanças no provedor podem impedir a reprodução mesmo com a chamada funcionando.
Quando algo não funciona
| Sintoma | O que conferir |
|---|---|
| Bot online, sem comandos | Capacidades declaradas/aprovadas, permissão do cargo e switch do canal. Não reinstale nem apague chaves para resolver uma aprovação pendente |
| Erro ao abrir o manifest | Processo do bot em execução, URL correta, porta e firewall nos dois sentidos |
| Token inválido ou identidade diferente | O operador precisa conferir o vínculo e preservar a identidade original; não gere chaves a cada reinício |
| Comando pede ferramentas novamente | Confira se a autorização era temporária ou foi revogada, e se a preparação terminou |
| Prévia funciona, mas a música não toca | Confirme sua presença em voz, as ferramentas, o acesso ao provedor e o transporte privado de mídia |
| Bot para após atualizar | Confira compatibilidade de protocolo, logs do processo e capacidades recém-solicitadas |
Desvincular revoga o acesso daquele cadastro. Vincular novamente exige outra revisão. Atualizar um bot não deve exigir apagar a identidade ou os cadastros válidos dos outros servidores.
Links de versões anteriores da documentação
As seções de desenvolvimento agora têm páginas próprias:
- Modo Marketplace (multi-servidor)
- Persistência dos vínculos
- Requisitos de rede
- Propriedades úteis
- Eventos
- Segurança: token e identidade
- Fotos dos bots
- CLI e pacote automático do bot
- Atualizações opcionais do CLI
- Anatomia de um comando
- Idioma dos comandos e preferências
- Parâmetros guiados no chat
- Autocomplete antes de executar
- Respostas privadas e publicação
- Formulários e conversas em etapas
- Seletores privados
- Seletores públicos e votações
- Reações e respostas por emoji
- Configurações por bot e servidor
- Permissões e canais
- Capacidades solicitadas e consentimento
- Seleção com prévia de áudio
- Áudio gerado somente ao ouvir
- Downloads locais autorizados
- Voz para bots
- Execução local de capacidades
- Contratos do SDK
- Validação integrada no checkout
- Telas programáveis compartilhadas
- Criando seu próprio bot
- Pré-requisitos
- Instalação do SDK
- Exemplo básico
- Referência rápida da API
- BotClient
- BotOptions
- ServeOptions