Minha Estratégia de Comandos de Bot para Telegram & Discord

Oi pessoal, Marcus aqui do ai7bot.com. É 13 de março de 2026 e eu tenho enfrentado um problema específico ultimamente que aposto que muitos de vocês que estão construindo bots já enfrentaram ou enfrentarão em breve. Estou falando sobre como gerenciar comandos e interações de bots em várias plataformas sem perder a cabeça. Especificamente, eu tenho me aprofundado no Telegram e Discord, tentando descobrir como manter as coisas em ordem quando seu bot precisa fazer coisas semelhantes em ambos os lugares.

Por um tempo, minha abordagem era o que eu chamaria de “duplicação por força bruta.” Se meu bot tinha um comando /help no Telegram, eu escrevia o código para ele. Então, se eu precisasse de um comando semelhante !help no Discord, eu basicamente copiava e colava e fazia algumas alterações. Isso funcionou por um tempo, especialmente quando meus bots eram pequenos e focados. Mas à medida que cresceram e eu comecei a adicionar mais recursos, virou um pesadelo. Atualizar um comando significava atualizar dois, três ou até mais lugares. Correções de bugs? Multiplique pelo número de plataformas. Era lento, propenso a erros e, francamente, tirava a alegria de construir.

Eu lembro de uma noite, provavelmente alimentada por muito café e pouco sono, tentando descobrir por que o comando /status do meu bot do Telegram estava mostrando informações desatualizadas, enquanto o comando !status do bot do Discord estava perfeitamente normal. Acontece que eu havia atualizado a fonte de dados em um lugar e esquecido completamente do outro. Esse foi o meu momento “aha!” Havia que haver uma maneira melhor. E essa maneira melhor, para mim, tem sido apostar fortemente em uma abordagem mais unificada com APIs para a lógica central do bot, abstraindo o que é específico da plataforma o máximo possível.

A Dor de Cabeça dos Bots Multiplataforma: Uma Verdadeira Mãe

Vamos ser honestos, construir um bot para uma única plataforma já é desafiador o suficiente. Você lida com peculiaridades de API, limites de taxa, expectativas dos usuários e a imprevisibilidade geral da internet. Adicione uma segunda, terceira ou até quarta plataforma à mistura e, de repente, você não está apenas construindo um bot; você está construindo uma camada de tradução, um mecanismo de sincronização e um sistema de gerenciamento de saúde mental para você mesmo.

Meu primeiro bot, “WeatherBot 2000” (original, certo?), começou no Telegram. Era simples: você digitava /weather <city> e ele te dava as condições atuais. Ótimo! Então, um amigo perguntou se eu poderia colocar no Discord. “Claro!” eu disse, confiante. Copiei a lógica de busca do tempo, coloquei uma camada de comando do Discord em volta e pronto, “WeatherBot 2000” também estava no Discord, respondendo a !weather <city>. Missão cumprida, ou assim pensei.

Então vieram os pedidos: “Pode mostrar uma previsão de 3 dias?” “Pode usar Celsius em vez de Fahrenheit?” “Pode também me informar sobre a qualidade do ar?” Cada novo recurso significava mexer no código em pelo menos dois lugares. O recurso de previsão, por exemplo, exigia mudar como eu parseava a resposta da API do tempo e como eu formatava a saída. Fazer isso duas vezes, uma para o Markdown do Telegram e outra para o Markdown ligeiramente diferente do Discord (ou embeds para uma aparência mais agradável), era trabalhoso. Não era apenas copiar e colar; era re-implementar a lógica de apresentação.

Por que Separar as Preocupações? É uma Questão de Sanidade.

O cerne do problema era que minha “lógica de negócios” (buscando dados do tempo, processando-os) estava entrelaçada com minha “lógica de apresentação” (como aparece no Telegram, como aparece no Discord). Este é um problema clássico de desenvolvimento de software, e a solução, como eu aprendi da maneira difícil, é separar essas preocupações. Pense assim:

• Lógica Central: Esta é o que seu bot faz. Para o WeatherBot, é fazer chamadas de API para um serviço meteorológico, parsear a resposta JSON e extrair os dados relevantes. Esta parte deve ser independente da plataforma.
• Adaptadores de Plataforma/Lógica de Apresentação: Esta é como seu bot fala em cada plataforma. São as chamadas de API do Telegram, as chamadas de API do Discord, lidando com prefixos de comando, formatando mensagens com Markdown ou embeds, enviando arquivos, etc.

Quando você mantém essas partes separadas, pode atualizar sua lógica central de busca de tempo uma vez, e isso beneficia instantaneamente seus bots do Telegram e do Discord. Se o Telegram liberar uma nova opção de formatação de mensagem, você só precisa atualizar seu adaptador do Telegram. A parte de busca de tempo permanece intacta.

Construindo um Núcleo Unificado com APIs: Meu Exemplo “WeatherBrain”

Depois do meu pesadelo de depuração, decidi reconstruir o “WeatherBot 2000” do zero, mas desta vez com uma separação clara. Criei uma pequena API interna para a funcionalidade central do meu bot. Eu a chamo de “WeatherBrain” (ainda estou trabalhando nos nomes, ok?).

WeatherBrain é apenas uma simples aplicação Python Flask (poderia ser qualquer coisa, até um conjunto de funções em uma biblioteca, mas uma API facilita a escalabilidade e o teste independentemente). Ela expõe endpoints como /api/weather?city=london&units=metric e /api/forecast?city=london&days=3. Quando chamado, ele atinge uma real API meteorológica externa (como OpenWeatherMap ou AccuWeather), processa os dados e retorna uma resposta JSON limpa e consistente.

Aqui está um vislumbre simplificado do que um endpoint do WeatherBrain pode parecer:

# weather_brain_api.py (exemplo simplificado de Flask)
from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

# Idealmente, isso estaria em uma configuração ou variável de ambiente
WEATHER_API_KEY = os.environ.get("OPENWEATHER_API_KEY") 
OPENWEATHER_URL = "http://api.openweathermap.org/data/2.5/weather"

@app.route('/api/weather', methods=['GET'])
def get_current_weather():
 city = request.args.get('city')
 units = request.args.get('units', 'metric') # 'metric' ou 'imperial'

 if not city:
 return jsonify({"error": "O parâmetro da cidade é obrigatório"}), 400

 params = {
 'q': city,
 'appid': WEATHER_API_KEY,
 'units': units
 }

 try:
 response = requests.get(OPENWEATHER_URL, params=params)
 response.raise_for_status() # Levanta uma exceção para erros HTTP
 data = response.json()

 # Processa e simplifica os dados
 weather_info = {
 "city": data['name'],
 "country": data['sys']['country'],
 "description": data['weather'][0]['description'].capitalize(),
 "temperature": data['main']['temp'],
 "feels_like": data['main']['feels_like'],
 "humidity": data['main']['humidity'],
 "wind_speed": data['wind']['speed']
 }
 return jsonify(weather_info)

 except requests.exceptions.RequestException as e:
 app.logger.error(f"Erro ao buscar o tempo para {city}: {e}")
 return jsonify({"error": "Não foi possível buscar os dados meteorológicos"}), 500
 except KeyError as e:
 app.logger.error(f"Erro de chave nos dados meteorológicos para {city}: {e}")
 return jsonify({"error": "Formato inesperado dos dados meteorológicos"}), 500

if __name__ == '__main__':
 app.run(debug=True, port=5001)

Agora, tanto meu bot do Telegram quanto meu bot do Discord não falam diretamente com o OpenWeatherMap. Eles falam com WeatherBrain. Isso é uma grande vitória! Se eu quiser mudar do OpenWeatherMap para o AccuWeather, eu só mudo o código em weather_brain_api.py. Os bots não sabem nem que isso aconteceu.

Bots do Telegram e Discord: Tornando-se Clientes Leves

Com o WeatherBrain lidando com o peso, o código real do meu bot do Telegram e do Discord se tornou muito mais simples. Eles agora agem como “clientes leves” ou “adapters.” O trabalho deles é puramente:

1. Escutar comandos (ex: /weather <city> ou !weather <city>).
2. Parsear o comando e extrair argumentos.
3. Fazer uma requisição HTTP para o WeatherBrain.
4. Receber a resposta JSON do WeatherBrain.
5. Formatar essa resposta JSON em uma mensagem específica da plataforma.
6. Enviar a mensagem de volta ao usuário.

Aqui está um exemplo simplificado de como o adaptador do Telegram pode parecer:

# telegram_bot.py (simplificado)
import telebot
import requests
import os

TELEGRAM_BOT_TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN")
WEATHER_BRAIN_API_URL = "http://localhost:5001/api/weather" # Ou a URL da sua API implantada

bot = telebot.TeleBot(TELEGRAM_BOT_TOKEN)

@bot.message_handler(commands=['weather'])
def send_weather(message):
 try:
 args = message.text.split(maxsplit=1)
 if len(args) < 2:
 bot.reply_to(message, "Por favor, forneça uma cidade. Ex: `/weather Londres`")
 return

 city = args[1]
 
 # Chame a API interna
 response = requests.get(WEATHER_BRAIN_API_URL, params={'city': city, 'units': 'metric'})
 response.raise_for_status()
 weather_data = response.json()

 if "error" in weather_data:
 bot.reply_to(message, f"Erro: {weather_data['error']}")
 return

 # Formatar para o Telegram
 output = (
 f"*{weather_data['city']}, {weather_data['country']}*\n"
 f"Clima: {weather_data['description']}\n"
 f"Temperatura: {weather_data['temperature']:.1f}°C (Sensation como {weather_data['feels_like']:.1f}°C)\n"
 f"Umidade: {weather_data['humidity']}%\n"
 f"Vento: {weather_data['wind_speed']:.1f} m/s"
 )
 bot.reply_to(message, output, parse_mode='Markdown')

 except requests.exceptions.RequestException as e:
 bot.reply_to(message, "Desculpe, não consegui buscar o tempo agora. Meu cérebro parece estar tirando uma soneca.")
 print(f"Erro ao chamar a API do WeatherBrain: {e}")
 except Exception as e:
 bot.reply_to(message, "Ocorreu um erro inesperado. Por favor, tente novamente mais tarde.")
 print(f"Erro geral no bot do Telegram: {e}")

bot.polling()

E o adaptador do Discord ficaria muito parecido, apenas usando a biblioteca Discord.py (ou qualquer que você preferir) para lidar com comandos e formatar mensagens com a sintaxe específica do Discord (ex: embeds para mensagens mais ricas).

A chave aqui é que ambos os bots estão buscando os mesmos dados estruturados do WeatherBrain. Eles apenas os apresentam de maneiras diferentes. Isso reduz drasticamente o código duplicado e torna a adição de novas funcionalidades ou correções de bugs muito mais fácil.

Além dos Comandos: Webhooks e Eventos

Essa abordagem orientada a APIs não é apenas para comandos. E se seu bot precisar reagir a eventos externos? Suponha que você tenha um bot de monitoramento que verifica o tempo de atividade de um site. Quando o site fica fora do ar, seu serviço de monitoramento pode enviar um webhook para seu WeatherBrain (ou uma API separada chamada “NotifierBrain”). Essa API então decide quais plataformas notificar (Telegram, Discord, email, SMS) e qual mensagem enviar, passando os dados da alerta estruturados para cada adaptador de plataforma.

É aqui que o poder realmente brilha. Sua API central se torna a única fonte de verdade para a inteligência do seu bot, e os componentes específicos da plataforma são apenas canais de comunicação.

Principais Dicas para Seu Próximo Projeto de Bot

Se você está construindo um bot, especialmente um que você espera expandir para várias plataformas ou adicionar funcionalidades complexas, considere estes pontos:

1. Isolar Sua Lógica Principal: Antes mesmo de tocar em uma API específica da plataforma, escreva (ou codifique) o que seu bot faz fundamentalmente. Que dados ele precisa? Quais cálculos ele realiza? Isso é o seu “cérebro”.
2. Construa uma API Interna (Mesmo uma Simples): Seja um aplicativo Flask, um serviço FastAPI, ou apenas um módulo Python bem organizado com funções claras, crie uma camada que encapsule sua lógica principal e retorne dados consistentes e estruturados (JSON é ótimo para isso). Isso torna a API testável e reutilizável.
3. Trate Bots Específicos da Plataforma como Adaptadores: O trabalho deles é traduzir a entrada do usuário em chamadas para sua API interna e, em seguida, traduzir as respostas da API interna em mensagens adequadas para essa plataforma. Eles devem ser “finos” – lógica mínima, máxima comunicação.
4. Planeje o Tratamento de Erros: Quando você tem múltiplas camadas (bot da plataforma -> API interna -> API externa), erros podem acontecer em qualquer estágio. Certifique-se de que cada camada lide graciosamente com falhas da camada abaixo dela e forneça feedback informativo (mas não excessivamente técnico) ao usuário.
5. Considere a Implantação: Se sua API interna é um serviço separado, você precisará implantá-la em algum lugar. Serviços como Heroku, Render, ou até mesmo um pequeno VPS podem hospedar esses microserviços. Certifique-se de que seus bots de plataforma possam acessar sua API interna (por exemplo, se estiver rodando localmente, eles precisam estar na mesma rede ou acessíveis via uma URL pública).
6. Comece Pequeno, Itere: Você não precisa construir uma arquitetura massiva de microserviços desde o primeiro dia. Comece com uma função central, isole-a e, em seguida, construa seu primeiro adaptador de plataforma. À medida que você adiciona mais funcionalidades ou plataformas, você naturalmente expandirá sua API interna.

Adotar essa abordagem me economizou inúmeras horas de depuração e me permitiu escalar meus bots de maneira muito mais eficaz. A configuração inicial pode parecer um pouco mais trabalhosa, mas acredite, os benefícios a longo prazo em manutenibilidade, escalabilidade, e, francamente, sua própria sanidade, valem absolutamente a pena. Boa construção de bots!

🕒 Published: April 2, 2026