Send a free-form text message to the configured Telegram chat.

Use this for casual messages, inline code snippets, status updates, or any content that does not require structured formatting.

Args: text : The message body. Supports Telegram Markdown v1 by default. parse_mode : 'Markdown', 'HTML', or '' for plain text. Default: 'Markdown'.

Send a structured notification to the configured Telegram chat.

Automatically prepends an emoji for quick visual scanning. Default emojis by event type: completed → ✅ error → ❌ progress → 🔄 question → ❓

Override the default emoji with the icon parameter when the context calls for something more specific (e.g. icon='🚀' for a deployment, '🧪' for a test run, '📊' for a report).

Args: event : Event type — 'completed', 'error', 'progress', or 'question'. summary : One-line summary shown prominently (≤200 chars recommended). details : Optional multi-line body — stack traces, next steps, metrics, etc. icon : Optional emoji to override the default event icon.

Send a structured notification with up to 4 inline action buttons.

Buttons let the user reply with a single tap instead of typing. After sending, call wait_for_reply to capture the chosen button or typed reply.

Button design guidelines:

• Provide 2–4 buttons with clear, action-oriented labels.

• Keep each label under 30 characters.

• Buttons are suggestions — users can always type a custom reply instead.

• Use emoji prefixes in labels to aid scannability (e.g. '✅ Approve', '❌ Cancel').

Args: event : Event type — 'completed', 'error', 'progress', or 'question'. summary : One-line summary (≤200 chars). buttons : List of 1–4 button label strings. Each label becomes the button text AND the callback payload. details : Optional additional context or instructions for the user. icon : Optional emoji to override the default event icon.

Wait for a reply from the user via Telegram and return it.

Handles both plain text messages and inline button taps (callback queries).

Smart polling intervals (minimises API calls): 0 – 10 min elapsed → poll every 30 s 10 min – 1 hr → poll every 60 s 1 hr+ → poll every 120 s

LLM guidelines for choosing max_wait_seconds: Simple yes/no or quick question → 300 (5 min) General task approval → 1 800 (30 min) ← default Stock price / alert trigger → 1 800 (30 min) End-of-day review → 7 200 (2 hr) Overnight / long-running job → 86 400 (24 hr) Multi-day wait → any value — no maximum

Args: max_wait_seconds : How long to wait. Default 1800, no upper limit. Pick a value appropriate to how soon a reply is expected.