Summary

When TELEGRAM_HOME_CHANNEL is set to a Telegram username (e.g., @some_user) instead of a numeric chat ID, any webhook cross-platform delivery to Telegram crashes with ValueError: invalid literal for int() with base 10. This silently breaks all webhook-to-Telegram delivery including cron job notifications.

Impact

Any user who sets TELEGRAM_HOME_CHANNEL to their username (a natural thing to do) will find that:

• Webhook deliver: telegram routes silently fail
• Cron job notifications never arrive
• No error is surfaced to the user — the delivery just disappears after retries

This is particularly insidious because interactive Telegram sessions work fine (the gateway already has the numeric chat_id from the Telegram update object). The bug only manifests for webhook-initiated deliveries that fall back to the home channel.

Reproduction

1. Set TELEGRAM_HOME_CHANNEL=@some_user (or any non-numeric value) in .env
2. Configure a webhook route with deliver: telegram (no deliver_extra.chat_id)
3. POST to the webhook route
4. Observe in gateway logs:

ValueError: invalid literal for int() with base 10: '@some_user'
ERROR gateway.platforms.base: [Webhook] Failed to deliver response after 2 retries: invalid literal for int() with base 10: '@some_user'

Root Cause

gateway/platforms/webhook.py line 760-762:

home = self.gateway_runner.config.get_home_channel(target_platform)
if home:
    chat_id = home.chat_id  # This is a string like "@some_user"

This chat_id string is then passed directly to adapter.send() which calls telegram.py line 983:

chat_id=int(chat_id),  # 💥 crashes on non-numeric strings

The HomeChannel dataclass (gateway/config.py line 81) stores chat_id as str, and from_dict() (line 95) does str(data["chat_id"]) with no validation or resolution.

TELEGRAM_HOME_CHANNEL env var (config.py line 851-857) is taken verbatim with no validation:

telegram_home = os.getenv("TELEGRAM_HOME_CHANNEL")
if telegram_home and Platform.TELEGRAM in config.platforms:
    config.platforms[Platform.TELEGRAM].home_channel = HomeChannel(
        platform=Platform.TELEGRAM,
        chat_id=telegram_home,  # No validation — accepts any string
        name=os.getenv("TELEGRAM_HOME_CHANNEL_NAME", "Home"),
    )

Current Workaround

Set TELEGRAM_HOME_CHANNEL to the numeric chat ID instead of the username. Can be found via the Telegram Bot API getUpdates endpoint or from ~/.hermes/channel_directory.json.

Alternatively, specify deliver_extra.chat_id explicitly in each webhook route config:

deliver: telegram
deliver_extra:
  chat_id: "1234567890"

Suggested Fix

Two changes needed:

1. Resolve usernames to numeric chat IDs at startup (gateway/config.py):

In _load_env_config(), after setting the home_channel from the env var, if the chat_id is not purely numeric, attempt to resolve it using the bot's get_chat() method (available after the Telegram adapter connects). If resolution fails, log a warning and suggest using the numeric ID.

# In _load_env_config(), after line 857:
if telegram_home and not telegram_home.lstrip("@").isdigit():
    # Will be resolved after Telegram adapter connects
    # (deferred resolution needed since bot isn't available yet)
    logger.warning(
        "TELEGRAM_HOME_CHANNEL='%s' is not a numeric chat ID. "
        "Username resolution will be attempted after bot connects. "
        "For reliability, set TELEGRAM_HOME_CHANNEL to your numeric chat ID.",
        telegram_home,
    )

2. Make telegram.py:send() resilient (gateway/platforms/telegram.py):

Add a try/except around int(chat_id) with a clear error message:

# Line 983, replace:
chat_id=int(chat_id),
# With:
try:
    numeric_chat_id = int(chat_id)
except (ValueError, TypeError):
    # Attempt username resolution via bot.get_chat()
    try:
        chat_obj = await self._bot.get_chat(chat_id)
        numeric_chat_id = chat_obj.id
    except Exception:
        raise ValueError(
            f"chat_id '{chat_id}' is not numeric and could not be resolved. "
            f"Telegram requires a numeric chat ID. Set TELEGRAM_HOME_CHANNEL "
            f"to your numeric ID (found via @userinfobot or channel_directory.json)."
        ) from None

This makes the Telegram adapter resilient to username-based chat IDs while guiding users to the proper fix.

Environment

• hermes-agent: latest main (commit after v0.23.x)
• OS: Ubuntu 22.04
• Python: 3.11
• Discovered during: email-triage webhook pipeline development
• Gateway log evidence: ValueError: invalid literal for int() with base 10 on webhook delivery retry