Service Desk Bot

This is the Service Desk Bot (@proximaservicedeskbot) — the per-user, ticket-focused bot that powers the Mini App. For the group-based operations bot (alerts, group binding, AI Investigator), see the Ops Bot.

The Service Desk bot is a small Go service (built on gopkg.in/telebot.v4) that handles two jobs: helping users link their Telegram account to a Console account, and delivering push notifications when their tickets change. It listens on :8082, reached at the /telegram-bot/ path prefix.

The bot never touches ticket data directly — it authenticates to the Console API with a service-account API key (X-API-Key) and uses it only to look up which Console user a given person maps to.

Commands

Command	Action
/start	Welcome message with an Open Service Desk button that launches the Mini App. A /start <code> from the Console "Link Telegram" button links the account. It does not do paging verification — that proves a private chat with the Ops bot, which is the bot that sends pages.
/tickets	A View Tickets button that opens the Mini App's ticket list.
/new	Two buttons — New Incident and New Task — that open the create-ticket flow.
/link <code>	Links the Telegram account to a Console user using a short-lived code (see Account Linking & Security). Sent without a code, it replies with instructions on where to generate one.
/unlink	Explains how to unlink the account from the Console UI.

Jira / JSM webhook → notifications

The bot exposes a webhook receiver at POST /telegram-bot/webhook/jira. Jira Service Management is configured to post ticket events there, and the bot converts each event into a Telegram message routed to the affected users.

Events and messages

Event	Example message
Status change	📋 SUP-142 — Status Updated — Status: Open → In Progress, By: J. Smith
New comment	📋 SUP-141 — New Comment — By: J. Smith, "Working on this now"
Ticket created	📋 SUP-143 — New Ticket — By: A. Kim, Priority: High
Assignee change	📋 SUP-142 — Reassigned — Assigned to: J. Smith

Routing logic

1. Extract the reporter and assignee emails from the JSM webhook payload.
2. Look up the corresponding Console users by email and read their linked telegram_id.
3. Send each one a Telegram message that includes a View Ticket inline button — a deep link that opens the Mini App directly on that ticket.
4. Skip the person who triggered the event — you don't get pinged for your own action.

Webhook security

• The webhook can require a shared secret, validated via the X-Hub-Signature / X-Atlassian-Webhook-Signature headers. This is configured with JIRA_WEBHOOK_SECRET; when that variable is empty, signature validation is skipped.
• The request body is capped at 1 MB (http.MaxBytesReader) to guard against oversized payloads.

Environment variables

The bot is configured entirely through environment variables. On the retired single-box path these came from /opt/proxima/.env; the image is now built by CI and its tag bumped by deploy:k8s-gitops — see Deployment for how the two paths differ and which one is live.

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Bot token from @BotFather.
TELEGRAM_MINIAPP_URL	Yes	Base URL of the Mini App (e.g. https://tg-console.prxm.uz).
CONSOLE_API_KEY	Yes	Service-account API key used for Console user lookups.
TELEGRAM_WEBHOOK_URL	No	Public URL for receiving Telegram updates. If empty, the bot uses long polling instead.
CONSOLE_API_URL	No	Base URL of the Console backend. Defaults to https://api-console.prxm.uz.
JIRA_WEBHOOK_SECRET	No	Shared secret for validating JSM webhook signatures. Validation is skipped if empty.
HTTP_LISTEN_ADDR	No	Address the HTTP server listens on. Defaults to :8082.

Webhook vs. polling

If TELEGRAM_WEBHOOK_URL is set, the bot registers a Telegram webhook to receive updates; otherwise it falls back to long polling. The JSM webhook receiver (/telegram-bot/webhook/jira) is independent of this and is always available.