Como criar um bot de Telegram usando Python

Artigo original: https://www.freecodecamp.org/news/how-to-create-a-telegram-bot-using-python/

Os chatbots automatizados são bastante úteis para estimular interações. Podemos criar chatbots para o Slack, o Discord e outras plataformas.

Neste artigo, vou ensinar a você como construir um chatbot do Telegram que vai dizer o seu horóscopo. Então, vamos começar!

Como obter seu token de bot

Para configurar um novo bot, você precisará falar com o BotFather. Não, ele não é uma pessoa – ele também é um bot e é o chefe de todos os bots do Telegram.

1. Procure por @botfather no Telegram.

2.  Comece uma conversa com o BotFather clicando no botão Iniciar (ou Start, na versão em inglês).

3.  Digite /newbot e siga as instruções para configurar um novo bot. O BotFather dará a você um token que você usará para autenticar seu bot e conceder a ele acesso à API do Telegram.

Observação: não se esqueça de armazenar o token de modo seguro. Qualquer pessoa com acesso ao seu token pode facilmente manipular seu bot.

Como configurar seu ambiente de programação

Vamos configurar o ambiente de programação. Embora existam várias bibliotecas disponíveis para criar um bot do Telegram, usaremos a biblioteca pyTelegramBotAPI. É uma implementação simples, mas extensível, do Python para a API de bots do Telegram, com recursos síncronos e assíncronos.

Instale a biblioteca pyTelegramBotAPI usando o pip:

pip install pyTelegramBotAPI

Em seguida, abra seu editor de código favorito e crie um arquivo .env para armazenar seu token conforme abaixo:

export BOT_TOKEN=token-do-seu-bot-aqui

Depois disso, execute o comando source .env para ler as variáveis de ambiente a partir do arquivo .env.

Como criar seu primeiro bot

Todas as implementações da API são armazenadas em uma única classe chamada TeleBot. Ela oferece muitas maneiras de ouvir mensagens recebidas, bem como funções como send_message(), send_document() e outras para enviar mensagens.

Crie um arquivo bot.py e cole o seguinte código lá:

import os

import telebot

BOT_TOKEN = os.environ.get('BOT_TOKEN')

bot = telebot.TeleBot(BOT_TOKEN)

No código acima, usamos a biblioteca os para ler as variáveis de ambiente armazenadas em nosso sistema.

Lembre-se: exportamos uma variável de ambiente chamada BOT_TOKEN na etapa anterior. O valor de BOT_TOKEN é lido em uma variável também chamada BOT_TOKEN. Além disso, usamos a classe TeleBot para criar uma instância de bot e passamos o BOT_TOKEN para ela.

Em seguida, precisamos registrar manipuladores de mensagens. Esses manipuladores de mensagens contêm filtros pelos quais uma mensagem deve passar. Se uma mensagem passar pelo filtro, a função decorada é chamada e a mensagem recebida é fornecida como um argumento.

Vamos definir um manipulador de mensagens que manipule os comandos /start e /hello recebidos.

@bot.message_handler(commands=['start', 'hello'])
def send_welcome(message):
    bot.reply_to(message, "Howdy, how are you doing?")

Qualquer nome é aceitável para uma função decorada por um manipulador de mensagens, mas só pode ter um parâmetro (a mensagem).

Vamos adicionar outro manipulador que ecoa todas as mensagens de texto recebidas de volta ao remetente.

@bot.message_handler(func=lambda msg: True)
def echo_all(message):
    bot.reply_to(message, message.text)

O código acima usa uma expressão lambda para testar uma mensagem. Como precisamos ecoar todas as mensagens, sempre retornamos True na função lambda.

Agora você tem um bot simples, que responde aos comandos /start e /hello com uma mensagem estática e que ecoa todas as outras mensagens enviadas. Adicione o seguinte ao final do seu arquivo para iniciar o bot:

bot.infinity_polling()

É isso! Temos um bot do Telegram pronto. Vamos executar o arquivo Python e ir ao Telegram para testar o bot.

Pesquise o bot usando seu nome de usuário se não conseguir encontrá-lo. Você pode testá-lo enviando comandos como /hello e /start e outros textos aleatórios.

Observação: todos os manipuladores de mensagens são testados na ordem em que foram declarados no arquivo-fonte.

Para obter mais informações sobre como usar a biblioteca pyTelegramBotAPI, consulte sua documentação.

Como programar o Horoscope Bot

Vamos mudar nossa atenção para a construção de nosso Horoscope Bot agora. Usaremos o encadeamento de mensagens no bot. O bot primeiro perguntará pelo seu signo do zodíaco, o dia e, em seguida, responderá com o horóscopo desse dia específico.

Internamente, o bot interage com uma API para obter os dados do horóscopo.

Vamos usar a API Horoscope que criei em outro tutorial. Se você deseja aprender como criar uma API, pode ler este tutorial (em inglês). Certifique-se de explorar a API de horóscopo aqui antes de começar.

Como obter os dados de horóscopo

Vamos criar uma função utilitária para obter os dados de horóscopo para um dia específico.

import requests

def get_daily_horoscope(sign: str, day: str) -> dict:
    """Get daily horoscope for a zodiac sign.
    Keyword arguments:
    sign:str - Zodiac sign
    day:str - Date in format (YYYY-MM-DD) OR TODAY OR TOMORROW OR YESTERDAY
    Return:dict - JSON data
    """
    url = "https://horoscope-app-api.vercel.app/api/v1/get-horoscope/daily"
    params = {"sign": sign, "day": day}
    response = requests.get(url, params)

    return response.json()

No código Python acima, criamos uma função que aceita dois argumentos de string – sign e day – e retorna dados JSON. Enviamos uma solicitação GET ao URL da API e passamos sign e day como parâmetros de consulta.

Se você testar a função, obterá um resultado semelhante ao que vemos abaixo:

{
   "data":{
      "date": "Dec 15, 2022",
      "horoscope_data": "Lie low during the day and try not to get caught up in the frivolous verbiage that dominates the waking hours. After sundown, feel free to speak your mind. You may notice that there is a sober tone and restrictive sensation today that leaves you feeling like you will never be able to break free from your current situation. Don't get caught in this negative mindset."
   },
   "status": 200,
   "success": true
}

Observação: você pode saber mais sobre a biblioteca requests do Python neste tutorial (em inglês).

Como adicionar um manipulador de mensagens

Agora que temos uma função que retorna os dados do horóscopo, vamos criar um manipulador de mensagens em nosso bot que pergunte o signo do zodíaco do usuário.

@bot.message_handler(commands=['horoscope'])
def sign_handler(message):
    text = "What's your zodiac sign?\nChoose one: *Aries*, *Taurus*, *Gemini*, *Cancer,* *Leo*, *Virgo*, *Libra*, *Scorpio*, *Sagittarius*, *Capricorn*, *Aquarius*, and *Pisces*."
    sent_msg = bot.send_message(message.chat.id, text, parse_mode="Markdown")
    bot.register_next_step_handler(sent_msg, day_handler)

A função acima é um pouco diferente das outras funções que definimos anteriormente. A funcionalidade de horóscopo do bot será invocada pelo comando /horoscope. Estamos enviando uma mensagem de texto para o usuário, mas observe que definimos o parse_mode como Markdown ao enviar a mensagem.

Como usaremos encadeamento de mensagens, usamos o método register_next_step_handler(). Esse método aceita dois parâmetros: a mensagem enviada pelo usuário e a função de callback que deve ser chamada após a mensagem. Assim, passamos a variável sent_msg e uma nova função day_handler, que definiremos a seguir.

Vamos definir a função day_handler(), que aceita a mensagem.

def day_handler(message):
    sign = message.text
    text = "What day do you want to know?\nChoose one: *TODAY*, *TOMORROW*, *YESTERDAY*, or a date in format YYYY-MM-DD."
    sent_msg = bot.send_message(
        message.chat.id, text, parse_mode="Markdown")
    bot.register_next_step_handler(
        sent_msg, fetch_horoscope, sign.capitalize())

Buscamos o signo do zodíaco do atributo message.text. Semelhante à função anterior, ela também pergunta o dia para o qual você deseja saber o horóscopo.

No final, usamos o mesmo método register_next_step_handler() e passamos sent_msg, a função de callback fetch_horoscope e o sign.

Vamos, agora, definir a função fetch_horoscope(), que aceita a mensagem e o signo.

def fetch_horoscope(message, sign):
    day = message.text
    horoscope = get_daily_horoscope(sign, day)
    data = horoscope["data"]
    horoscope_message = f'*Horoscope:* {data["horoscope_data"]}\\n*Sign:* {sign}\\n*Day:* {data["date"]}'
    bot.send_message(message.chat.id, "Here's your horoscope!")
    bot.send_message(message.chat.id, horoscope_message, parse_mode="Markdown")

Essa é a função final, onde obtemos o signo no parâmetro de função e o dia do atributo message.text.

Em seguida, buscamos o horóscopo usando a função get_daily_horoscope() e criamos nossa mensagem. No final, enviamos a mensagem com os dados do horóscopo.

Demonstração do bot

Depois de executar o arquivo Python, você pode testar essa funcionalidade. Aqui está a demonstração:

Próximos passos recomendados

A partir de agora, o bot para de funcionar assim que paramos nossa aplicação do Python. Para fazê-lo funcionar sempre, você pode implantar o bot em plataformas como o Heroku, o Render e assim por diante.

Aqui está um link do repositório no GitHub para esse projeto - sinta-se à vontade para conferir.

Você também pode adicionar mais funcionalidades ao bot explorando as APIs do Telegram.

Obrigado pela leitura! Se quiser, você pode seguir o autor no Twitter.