Notificação via Telegram

.env.example

# Telegram
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_IDS=

.gitignore

.env

README.md

Telegram Notify

Sistema simples para envio de notificações via Telegram.

Instalação

pip install httpx python-decouple

Configuração

Copie o arquivo .env.example para .env e preencha as variáveis:

cp .env.example .env

Variáveis de ambiente

Variável	Descrição
TELEGRAM_BOT_TOKEN	Token do bot obtido através do @BotFather no Telegram
TELEGRAM_CHAT_IDS	IDs dos chats separados por vírgula. Pode ser ID de usuário ou de grupo

Como obter o TELEGRAM_BOT_TOKEN

1. Abra o Telegram e busque por @BotFather
2. Envie o comando /newbot
3. Siga as instruções para criar o bot
4. Copie o token fornecido

Como obter o TELEGRAM_CHAT_ID

1. Adicione o bot @userinfobot no Telegram
2. Envie qualquer mensagem para ele
3. Ele retornará seu ID de usuário

Para grupos:

1. Adicione o bot ao grupo
2. Envie uma mensagem no grupo
3. Acesse: https://api.telegram.org/bot<SEU_TOKEN>/getUpdates
4. Procure pelo campo chat.id (grupos têm ID negativo)

Uso

Como módulo

from telegram_notify import send_telegram_notification

# Envia para todos os chat IDs configurados no .env
resultado = send_telegram_notification("Sua mensagem aqui")

# Envia para chat IDs específicos
resultado = send_telegram_notification("Mensagem", chat_ids=["123456789"])

# Usando formatação HTML
resultado = send_telegram_notification("<b>Título</b>\n\nTexto da mensagem")

Direto pelo terminal

python telegram_notify.py

Retorno

A função retorna um dicionário com o resultado de cada envio:

{
    "123456789": {
        "success": True,
        "status_code": 200,
        "response": {...}
    }
}

telegram_notify.py

from pathlib import Path

import httpx
from decouple import Config, RepositoryEnv

# Carrega as variáveis do .env
env_path = Path(__file__).resolve().parent / ".env"
config = Config(RepositoryEnv(env_path))

TELEGRAM_BOT_TOKEN = config("TELEGRAM_BOT_TOKEN")
TELEGRAM_CHAT_IDS = config("TELEGRAM_CHAT_IDS", default="").split(",")


def send_telegram_notification(message: str, chat_ids: list[str] = None) -> dict:
    """
    Envia uma mensagem para um ou mais chats do Telegram.

    Args:
        message: Texto da mensagem a ser enviada.
        chat_ids: Lista de chat IDs. Se não fornecido, usa os IDs do .env.

    Returns:
        Dicionário com o resultado de cada envio.
    """
    if not TELEGRAM_BOT_TOKEN:
        raise ValueError("TELEGRAM_BOT_TOKEN não configurado no .env")

    if chat_ids is None:
        chat_ids = TELEGRAM_CHAT_IDS

    url = f"https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendMessage"
    results = {}

    for chat_id in chat_ids:
        chat_id = chat_id.strip()
        if not chat_id:
            continue

        payload = {
            "chat_id": chat_id,
            "text": message,
            "parse_mode": "HTML",
        }

        response = httpx.post(url, json=payload)
        results[chat_id] = {
            "success": response.is_success,
            "status_code": response.status_code,
            "response": response.json(),
        }

    return results


if __name__ == "__main__":
    resultado = send_telegram_notification("Teste de notificação via Telegram!")
    print(resultado)