Skip to main content

Imported from docs/HEROKU_TELEGRAM_DEPLOY.md. Edit source file, then re-run sync.

Heroku Deployment + Telegram E2E (API)

This guide deploys the api service to Heroku so you can test Telegram onboarding and assistant actions end-to-end.

1) Prerequisites​

  • Heroku CLI installed and authenticated
  • A MongoDB connection string (Atlas recommended)
  • A Telegram bot token from BotFather
  • Optional but recommended: Heroku Redis add-on
  • Dashboard deployed (for Telegram link completion + Google connect pages)

2) Create and deploy API app​

From repo root:

npm run deploy:heroku:api -- <your-api-app-name>

This helper configures buildpack baseline and pushes the api subtree.

Manual alternative:

cd api
heroku create <your-api-app-name>
heroku buildpacks:clear -a <your-api-app-name>
heroku buildpacks:add heroku/nodejs -a <your-api-app-name>
git subtree push --prefix api "https://git.heroku.com/<your-api-app-name>.git" main

Option B: Container deployment​

heroku stack:set container -a <your-api-app-name>
heroku container:push web -a <your-api-app-name>
heroku container:release web -a <your-api-app-name>

3) Add Redis + Mongo​

heroku addons:create heroku-redis:mini -a <your-api-app-name>

Set Mongo:

heroku config:set MONGODB_URI='<your-mongodb-uri>' -a <your-api-app-name>

4) Set required config vars​

heroku config:set \
  NODE_ENV=production \
  API_PREFIX=v1 \
  JWT_SECRET='<strong-secret>' \
  JWT_REFRESH_SECRET='<strong-refresh-secret>' \
  GOOGLE_CLIENT_ID='<google-client-id>' \
  GOOGLE_CLIENT_SECRET='<google-client-secret>' \
  CORS_ORIGINS='https://<your-dashboard-domain>' \
  TELEGRAM_APP_BOT_TOKEN='<telegram-bot-token>' \
  TELEGRAM_APP_WEBHOOK_SECRET='<telegram-webhook-secret>' \
  TELEGRAM_APP_WEB_URL='https://<your-dashboard-domain>' \
  MAILCOW_ENABLED=true \
  MAILCOW_API_URL='https://<mailcow-host>' \
  MAILCOW_API_KEY='<mailcow-api-key>' \
  MAILCOW_DOMAIN='<mailcow-domain>' \
  MAILCOW_SMTP_HOST='<smtp-host>' \
  MAILCOW_IMAP_HOST='<imap-host>' \
  -a <your-api-app-name>

Notes:

  • Heroku Redis usually injects REDIS_URL automatically; API now supports REDIS_URL and TLS (REDIS_TLS=true if needed).
  • If your REDIS_URL is rediss://..., TLS is auto-enabled.

5) Configure Telegram webhook​

From repo root:

API_BASE_URL="https://<your-api-app-name>.herokuapp.com" \
TELEGRAM_APP_BOT_TOKEN='<telegram-bot-token>' \
TELEGRAM_APP_WEBHOOK_SECRET='<telegram-webhook-secret>' \
./scripts/setup-telegram-webhook.sh

Webhook target should become:

https://<your-api-app-name>.herokuapp.com/v1/telegram/app/webhook

6) Validate flow​

  1. In Telegram, send /start to your bot.
  2. Open the link returned by bot (/auth/telegram-link?token=...).
  3. Sign in and complete link.
  4. In Telegram, run:
    • /assistant (list)
    • /assistant <assistant-id> (select)
    • send an email to jeff@jeff.com saying I'll be back soon
  5. Confirm message is queued/sent from assistant default sender (Mailcow-managed sender).

7) Current scope and known gaps​

Working now:

  • Telegram /start login-link flow
  • Account linking to workspace user
  • Assistant selection and instruction execution for send-email phrasing

Still pending for "full Telegram app":

  • Native Telegram inbox commands (read/search/summarize existing emails)
  • Rich LLM intent routing (parser is currently rule-based for send-email)
  • Optional split of web and worker process types for production-grade reliability