Início
» Como fazer
»
Crie um bot de eco do Matrix em Python com a biblioteca Simple-Matrix-Bot-Lib.
Crie um bot de eco do Matrix em Python com a biblioteca Simple-Matrix-Bot-Lib.
Em 10 de outubro de 2026, o PyPI listava o Simple-Matrix-Bot-Lib 2.13.1, lançado em 29 de março de 2026. O pacote requer Python 3.9 ou superior, mas o Python 3.9 já atingiu o fim de seu ciclo de vida; utilize uma versão do Python com suporte e que seja compatível com o pacote. A documentação do projeto hospedada ainda identifica a versão como 2.11.0 e alerta que não recebe mais manutenção, portanto, este guia segue o exemplo atual do PyPI para a API do bot e utiliza o manual antigo apenas para notas de configuração claramente identificadas. Verifique a versão e os metadados do pacote no PyPI . Leia o status da documentação do projeto .
A configuração mais rápida e confiável consiste em um usuário dedicado do Matrix, um ambiente virtual Python e um pequeno bot de eco que responde !echoem uma sala de teste. O exemplo é para uma sala não criptografada; salas criptografadas exigem configuração adicional.
O que você precisa antes de instalar a biblioteca?
Crie ou solicite uma conta normal no servidor principal que executará o bot. Dê a ela um nome de usuário distinto, como echo_bot`<nome_de_usuário>`; ela não precisa de privilégios de administrador do servidor principal. O registro pode ser desativado ou restrito por esse servidor, portanto, siga a política de criação de contas dele. Convide a conta apenas para uma sala de teste privada onde ela tenha permissão para enviar mensagens.
Use o Python 3.11 ou outra versão do Python atualmente suportada. Embora os metadados do pacote ainda permitam o uso do Python 3.9, o Python.org indica que essa versão deixará de ser suportada em 31 de outubro de 2025, portanto, a versão mínima recomendada pelo pacote não é adequada para implantação. Consulte o aviso de suporte ao Python 3.9 do Python.org .
Como instalar o Simple-Matrix-Bot-Lib?
Execute esses comandos a partir de uma nova pasta de projeto. Um ambiente virtual mantém os pacotes deste bot separados de outros projetos Python. A fixação de versão torna o exemplo reproduzível com a versão mais recente verificada para este artigo; ao atualizar, verifique a versão atual do PyPI e suas notas de compatibilidade.
No Windows PowerShell, ative o ambiente com `install.packages(" env")` .venv\Scripts\Activate.ps1em vez do sourcecomando `install.packages("env")`. Em seguida, crie um arquivo chamado bot.py`.pypi.py`. A página do projeto no PyPI documenta o nome do pacote e o comando de instalação, e o exemplo publicado usa `.py` Creds, Bot`.py`, um listener de mensagens e `.py` MessageMatch. Veja o exemplo de uso atual no PyPI .
O terminal exibe o ambiente isolado e os comandos de instalação de pacotes fixados para o projeto do bot.
Como faço para conectar a conta do bot e adicionar um comando?
Salve o seguinte como bot.py. Ele solicita a senha do bot na inicialização, portanto, a senha não é gravada no arquivo de origem. Para implantação de serviço não assistida, leia o segredo do gerenciador de segredos do seu sistema operacional ou de uma variável de ambiente protegida, em vez de codificá-lo diretamente no código. Trate qualquer armazenamento de sessão ou token de acesso criado pela biblioteca como uma credencial: mantenha-o privado e fora do controle de versão.
import getpass
import simplematrixbotlib as botlib
creds = botlib.Creds(
homeserver="https://matrix.example.org",
username="echo_bot",
password=getpass.getpass("Bot password: "),
)
bot = botlib.Bot(creds)
PREFIX = "!"
@bot.listener.on_message_event
async def echo(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if (match.is_not_from_this_bot()
and match.prefix()
and match.command("echo")):
text = " ".join(match.args())
reply = text or "Usage: !echo <text>"
await bot.api.send_text_message(room.room_id, reply)
bot.run()
Substitua a URL do servidor de exemplo pela URL base do seu servidor e use o nome de usuário e a senha da conta do bot. O ouvinte recebe as mensagens da sala; MessageMatchele ignora suas próprias mensagens e processa apenas o !echocomando. A chamada da API envia as palavras restantes de volta para a mesma sala. Esses nomes e chamadas de método seguem o exemplo publicado da biblioteca no PyPI. Compare com o guia de início rápido Simple-Matrix-Bot-Lib .
O bloco de credenciais usa uma conta dedicada e solicita a senha em vez de colocar o segredo no arquivo.O manipulador ignora as mensagens do próprio bot, corresponde ao comando !echo e envia seus argumentos de volta para a sala.
Como executar o bot e confirmar se ele está funcionando?
No ambiente virtual ativado, execute:
python bot.py
Digite a senha da conta do bot quando solicitado. Na sala de teste, envie !echo hello. Um bot básico em funcionamento responde hello. Se ele permanecer em silêncio, confirme se a conta do bot entrou na sala, se o usuário tem permissão para enviar mensagens lá, se a URL do servidor está correta e se a mensagem começa com o !prefixo correto. Mantenha o processo em execução; fechar o terminal interrompe esta implantação simples em primeiro plano.
Uma conversa de exemplo em uma sala virtual mostra a solicitação e a resposta esperadas para o comando "echo"; trata-se de uma ilustração, não de um resultado de teste em tempo real.
O exemplo não processa mensagens de salas com criptografia de ponta a ponta. A biblioteca anuncia suporte a E2EE, mas o manual atualmente hospedado é da versão 2.11.0 e pode estar desatualizado; esse manual descreve matrix-nio[e2e]dependências adicionais e uma Config.encryption_enabledconfiguração. Confirme os passos exatos de instalação e verificação para a versão que você instalar antes de habilitar a criptografia. A documentação antiga também expõe uma join_on_inviteconfiguração: convide o bot apenas para as salas às quais ele deve ter acesso e verifique essa configuração se sua implementação precisar controlar a entrada automática em salas. Consulte o manual de E2EE e configuração da biblioteca .
A configuração estará completa quando o bot permanecer conectado, for membro da sala de testes e responder !echo hellocom um hello"sim". Para produção, execute-o sob um gerenciador de processos e proteja sua senha e dados de sessão.