clientsflow/telegram_backend

telegram_backend

Ingress/API адаптер Telegram Business.

Задача сервиса

• принимать webhook Telegram и нормализовать payload в envelope;
• ставить задачи в Hatchet (process-telegram-inbound, process-telegram-outbound);
• предоставлять GraphQL API:
  • enqueueTelegramOutbound (для backend);
  • sendTelegramMessage (для telegram_worker).

Сервис не содержит CRM бизнес-логику и не использует Prisma.

API

GET /health

Проверка живости сервиса.

POST /webhooks/telegram/business

Прием Telegram Business webhook.

При активном TELEGRAM_WEBHOOK_SECRET ожидается заголовок:

• x-telegram-bot-api-secret-token: <TELEGRAM_WEBHOOK_SECRET>

POST /graphql

Мутации:

• enqueueTelegramOutbound(input: TelegramOutboundTaskInput!): TaskEnqueueResult!
• sendTelegramMessage(input: TelegramSendMessageInput!): TelegramSendResult!

Переменные окружения

• PORT (default: 8080)
• MAX_BODY_SIZE_BYTES (default: 1048576)
• TELEGRAM_WEBHOOK_SECRET (optional, но обязателен для production)
• TELEGRAM_BACKEND_GRAPHQL_SHARED_SECRET (optional)
• TELEGRAM_BOT_TOKEN (required для sendTelegramMessage)
• TELEGRAM_API_BASE (default: https://api.telegram.org)
• HATCHET_CLIENT_TOKEN (required)
• HATCHET_CLIENT_TLS_STRATEGY (optional, например none для self-host без TLS)
• HATCHET_CLIENT_HOST_PORT (optional, например hatchet-engine:7070)
• HATCHET_CLIENT_API_URL (optional)

Запуск

npm ci
npm run start

Надежность

• 200 на webhook возвращается только после успешного enqueue задачи в Hatchet.
• При ошибке enqueue сервис возвращает 503, чтобы Telegram повторил доставку.
• Ретраи и оркестрация выполняются в Hatchet worker (telegram_worker).