Telegram Bot

Optional webhook-based Telegram entrypoint mapped to the same billing-aware chat pipeline.

Telegram integration provides an alternate user interface to the core chat pipeline through a webhook route.

Optional integration

Telegram is disabled by default unless required TELEGRAM_* environment variables are configured.

Architecture Overview

Primary route:

POST /api/webhooks/telegram

Behavior:

route is enabled only when webhook env is configured; otherwise returns 404
bot flow maps Telegram user identity to internal account
bot sends incoming text/attachments into buildChatStream(...) via internal bridge
same billing and limit logic as web chat is reused

Commands and Capabilities

/upgrade
/plan
/usage
DM and mention-based group interactions
progressive response updates with status labels
attachment handling with upload/size/type validation

Limit Handling and Upgrade Path

When chat path returns limit_exceeded:

internal bot flow receives a typed limit error
bot can generate signed upgrade links with expiry
upgrade endpoint: GET /api/billing/telegram-upgrade?token=...
checkout metadata includes telegram_user_id

Security Model

webhook authenticity uses TELEGRAM_CHAT_WEBHOOK_SECRET_TOKEN
upgrade links are HMAC-signed and expiry-validated
token verification uses timing-safe signature comparison

Required Environment Variables

APP_URL=https://app.yourdomain.com
TELEGRAM_CHAT_BOT_TOKEN=...
TELEGRAM_CHAT_BOT_USERNAME=...
TELEGRAM_CHAT_WEBHOOK_SECRET_TOKEN=...

Optional:

TELEGRAM_CHAT_API_BASE_URL=
TELEGRAM_UPGRADE_LINK_SECRET=
TELEGRAM_UPGRADE_PLAN_ID=prime

Webhook Setup Commands

Register webhook

curl -X POST "https://api.telegram.org/bot$TELEGRAM_CHAT_BOT_TOKEN/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.yourdomain.com/api/webhooks/telegram",
    "secret_token": "'"$TELEGRAM_CHAT_WEBHOOK_SECRET_TOKEN"'"
  }'

Verify webhook state

curl "https://api.telegram.org/bot$TELEGRAM_CHAT_BOT_TOKEN/getWebhookInfo"

On this page