telegram.py

"""Utility to send messages via Telegram API.

This module provides a single function :func:`send_telegram_message` which
sends a text message to a specified chat using a Telegram bot token.  The
implementation is intentionally lightweight and only depends on the
:mod:`requests` package.
"""
from __future__ import annotations

from typing import Any

import requests


def send_telegram_message(token: str, chat_id: str | int, message: str) -> dict[str, Any]:
    """Send a message using the Telegram Bot API."""

    url = f"https://api.telegram.org/bot{token}/sendMessage"
    payload: dict[str, Any] = {"chat_id": chat_id, "text": message}

    response = requests.post(url, data=payload, timeout=10)
    response.raise_for_status()
    return response.json()