Como Criar um Bot de Hashtag no Mastodon com a Streaming API

Você quer criar um bot no Mastodon que escuta uma hashtag específica em tempo real e automaticamente responde, impulsiona ou salva publicações correspondentes. A Streaming API do Mastodon permite que seu bot receba um fluxo contínuo de publicações públicas que correspondem a uma hashtag sem precisar consultar o servidor repetidamente. Este artigo explica como configurar um bot em Python usando a biblioteca Mastodon.py, conectar-se ao endpoint de streaming e lidar com publicações recebidas com ações personalizadas.

Entendendo a Streaming API do Mastodon para Bots de Hashtag

A Streaming API do Mastodon fornece uma conexão WebSocket que entrega novas publicações correspondentes a uma hashtag assim que são publicadas. Diferente da API REST, que exige que você envie requisições HTTP repetidamente, a API de streaming envia dados para seu bot em tempo real. Isso é mais eficiente e permite que seu bot reaja instantaneamente.

O endpoint para streaming de hashtag é /api/v1/streaming/hashtag?tag=suahashtag. Quando seu cliente se conecta, o servidor envia objetos JSON representando novos status que incluem a hashtag especificada. A conexão permanece aberta até que seu cliente desconecte ou o servidor a feche.

Pré-requisitos

Antes de construir o bot, verifique se você tem o seguinte:

• Python 3.7 ou superior instalado no seu sistema.
• Uma conta no Mastodon em qualquer instância. O bot usará essa conta para autenticar e realizar ações.
• Um aplicativo registrado na instância do Mastodon com escopos de leitura e escrita. Você pode registrar um aplicativo em Preferências > Desenvolvimento.
• A biblioteca Mastodon.py instalada via pip: pip install Mastodon.py.

Passos para Construir o Bot de Hashtag

Siga estes passos para criar um script Python que escuta uma hashtag e automaticamente impulsiona cada publicação correspondente.

1. Registre seu aplicativo e obtenha as credenciais
   Faça login na sua conta do Mastodon. Vá em Preferências > Desenvolvimento > Novo Aplicativo. Dê um nome para seu bot, como “HashtagBooster”. Em Escopos, selecione read:statuses e write:statuses. Clique em Enviar. Copie a Chave do Cliente, o Segredo do Cliente e o Token de Acesso da página do aplicativo. Salve-os em um arquivo chamado config.py.
2. Crie o script principal do bot
   Abra um novo arquivo Python, por exemplo hashtag_bot.py. Importe a classe Mastodon de Mastodon.py e a classe StreamListener. Defina uma classe que herda de StreamListener e sobrescreva o método on_update. Este método recebe um objeto status e pode chamar métodos da API como status_reblog para impulsionar a publicação.
3. Implemente a subclasse StreamListener
   Dentro da sua subclasse, escreva o método on_update. O método recebe um parâmetro: status. Verifique se o status contém a hashtag que você está monitorando. Em seguida, chame mastodon.status_reblog(status['id']) para impulsionar a publicação. Opcionalmente, adicione um breve atraso usando time.sleep(2) para evitar limitação de taxa.
4. Conecte-se ao endpoint de streaming
   No bloco principal do seu script, crie uma instância da classe Mastodon usando suas credenciais. Em seguida, chame o método stream_hashtag com a string da sua hashtag e uma instância do seu listener. Exemplo: mastodon.stream_hashtag('python', listener). Isso abre a conexão WebSocket e começa a receber publicações.
5. Execute o bot
   Execute o script no seu terminal: python hashtag_bot.py. O bot exibirá as publicações recebidas no console e as impulsionará. Deixe o terminal aberto para manter o bot em execução. Para pará-lo, pressione Ctrl+C.

O que Evitar e Armadilhas Comuns

O Bot Dispara Limitação de Taxa ou é Bloqueado

As instâncias do Mastodon impõem limites de taxa nas chamadas de API. Se o seu bot impulsionar todas as publicações imediatamente, pode exceder o limite e receber um erro 429 Too Many Requests. Sempre adicione um atraso entre as ações. Use time.sleep(5) ou mais. Além disso, evite impulsionar publicações de um único usuário repetidamente em um curto período.

Sensibilidade a Maiúsculas/Minúsculas em Hashtags

Hashtags no Mastodon não diferenciam maiúsculas de minúsculas. Ao filtrar publicações no seu método on_update, compare a hashtag em minúsculas. A API de streaming entrega a tag no formato que você especificou, mas os usuários podem digitá-la em maiúsculas e minúsculas misturadas. Use status['tags'] para obter uma lista de objetos de tag e verifique tag['name'].lower().

Conexão Cai Inesperadamente

A conexão da API de streaming pode cair devido a problemas de rede ou reinicializações do servidor. A biblioteca Mastodon.py reconecta automaticamente se você definir run_async=True e tratar exceções. Alternativamente, envolva a chamada stream_hashtag em um loop while True com um bloco try-except para reiniciar o stream em caso de desconexão.

Conta do Bot é Suspensa por Spam

Executar um bot que interage automaticamente com muitas publicações pode ser confundido com spam. Adicione um intervalo de espera: acompanhe o último horário de impulso por usuário e pule se o mesmo usuário publicou nos últimos 60 segundos. Além disso, inclua uma nota no perfil do seu bot informando que é automatizado e forneça uma forma de optar por não participar.

Streaming API vs API REST para Bots de Hashtag no Mastodon

Item	Streaming API	API REST
Tipo de conexão	WebSocket persistente	Requisições HTTP de curta duração
Entrega de dados	Enviado em tempo real	Obtido por consultas periódicas
Latência	Sub-segundo	Depende do intervalo de consulta (geralmente 5-60 segundos)
Risco de limite de taxa	Baixo — uma conexão	Alto — muitas requisições por minuto
Complexidade	Requer loop de eventos ou threads	Loop simples com requisições
Caso de uso	Reações em tempo real como impulsionar, responder	Processamento periódico em lote ou análises

Agora você pode construir um bot de hashtag no Mastodon que escuta em tempo real usando a Streaming API e a biblioteca Mastodon.py. Comece registrando um aplicativo, criando uma subclasse StreamListener e conectando-se a stream_hashtag. Adicione um atraso entre as ações e lide com reconexões para manter o bot estável. Para um bot mais avançado, estenda o método on_update para responder com mensagens personalizadas ou salvar publicações. Considere executar o bot em um VPS de baixo custo ou em um Raspberry Pi para que ele fique online continuamente.