Telegram

Telegram is an optional Organization Application. It sends selected activity from a Hamstik Project to a Telegram group or supergroup, including a forum topic. It is a one-way notification surface: native Hamstik inbox and email notifications remain independent.

Before you connect

1. In Telegram, open @BotFather and create a bot with /newbot.
2. Keep the bot dedicated to Hamstik. Telegram permits only one webhook per bot, so sharing a bot with another service can interrupt that service.
3. Keep Telegram group privacy mode enabled. Hamstik uses the addressed /hamstik connect … command for linking and does not need ordinary group conversation.

Never paste the token into a Work Item, comment, support message, URL, or chat. Hamstik validates it and stores it encrypted; the token is not shown again. Telegram’s Bot API necessarily uses the token in the HTTPS provider request path, but Hamstik does not put it in Hamstik URLs, browser responses, logs, jobs, analytics, or audit details.

Install and connect a destination

An Organization administrator opens Organization Settings → Apps → Telegram, enters a connection name and the BotFather token, and confirms the dedicated-bot webhook warning when applicable. Hamstik validates the bot identity before registering its webhook.

Select Connect destination to create a short-lived, single-use code. Issue the displayed command in the target Telegram group or forum topic:

/hamstik connect CODE

The command must be issued by a Telegram group administrator or creator. Hamstik verifies the group, the sender’s administrator status, and that the bot can participate before saving the destination. The code is hashed and expires shortly after it is created; it cannot be reused.

Supported destinations are Telegram groups and supergroups, including forum topics. Personal/private chats and channels are not supported in this version. A connected destination is represented in Hamstik by safe display metadata; raw Telegram chat identifiers are not shown in ordinary UI responses.

Bind Telegram to a Project

In Project Settings → Apps, enable Telegram and choose a connected destination. Configure each category independently:

• assignments;
• status changes;
• comments;
• mentions.

The default content level is Metadata only. Selecting Comment excerpts is an explicit administrator choice. Everyone who can read the Telegram chat or topic may see delivered content independently of Hamstik permissions, so choose a destination with the appropriate audience.

If a comment contains several native notification reasons, Telegram sends at most one message for that Project binding and event. Telegram is not a per-user inbox and does not send one copy per Hamstik recipient.

Messages and links

Messages identify Hamstik, the Organization and Project, the Work Item key and title, the event, and the actor when still available. Each message includes a canonical Hamstik Work Item link. Untrusted names, titles, statuses, and optional excerpts are escaped for Telegram HTML. Link previews are disabled and messages are kept within Telegram’s size limit.

Test delivery and health

Use Test beside a connected destination to send a fixed test message. The Organization App view shows the bot username, webhook state, last successful delivery, and the last sanitized error code.

• Connected means Hamstik has a validated token and registered webhook.
• Needs attention means an administrator action is required, such as replacing a revoked token or restoring access to a group.
• A rate-limit error is retried using Telegram’s retry_after value and bounded backoff.
• Network and suitable Telegram server failures are retried asynchronously. Permanent token, permission, or inaccessible-destination failures stop retrying until configuration is corrected.

Telegram does not provide an idempotency key for sendMessage. Hamstik’s durable job state prevents intentional duplicate sends, but a transport timeout after Telegram accepts a message is ambiguous and can result in one duplicate after retry. Exactly-once delivery is not claimed.

Rotation and lifecycle

Use token rotation when BotFather revokes or replaces a token. The replacement must identify the same bot; Hamstik never silently changes bot ownership. Disconnecting a destination immediately prevents new Project delivery to it and makes queued delivery obsolete.

Disabling Telegram stops new delivery, obsoletes queued Telegram work, and removes the Telegram webhook. Re-enabling reconciles and registers the webhook again. Uninstalling removes delivery state and encrypted secrets after attempting provider cleanup. If Telegram cannot be reached during cleanup, Hamstik still blocks local processing and marks the installation for operator reconciliation.

Troubleshooting

• Webhook ownership required: the bot already has another webhook. Use a dedicated bot, or explicitly confirm replacement only when you are certain that Hamstik should own it.
• Sender is not an administrator: issue the command as a group administrator or creator.
• Bot cannot send: add the bot to the group and check its group permissions. Forum-topic delivery also requires selecting the intended topic during linking.
• Invalid or revoked token: rotate the token from Organization Settings → Apps → Telegram.
• Rate limited: wait for the displayed retry window; the worker honors Telegram’s retry_after response.
• No messages: check that the Project binding is enabled, a destination is selected, and the relevant event filters are enabled. Changing filters does not replay older events.

Telegram activity delivery never blocks the originating Work Item or comment mutation, native inbox projection, or email delivery.