Monitoring and Troubleshooting

Overview

After the bot is connected, Overview displays:

• the bot name and username;

• a masked token preview;

• the number of active channels;

• the ten latest Jira event outcomes in Recent activity.

Recent activity refreshes when you open Overview. Each row contains a time, channel, event, Jira key, and result.

Settings are blocked by a database update

The settings page does not load configuration controls while required database updates are pending. This prevents settings from reading or writing an incomplete data structure.

1. On Database update required, select Run database updates.

2. Keep the page open. The button remains unavailable while the update runs, and settings unlock automatically after completion.

3. If Database status unavailable appears, select Check again.

4. If the update fails, retry once. If it fails repeatedly, include the displayed error and time in a support request.

The connector also retains its automatic daily database-update run. If another administrator or the scheduled run already started an update, the page waits and checks for completion instead of starting a second copy.

The bot does not connect

1. Obtain a fresh token directly from @BotFather and paste it without extra whitespace.

2. Check that it has the form numeric_id:secret.

3. Do not repeat attempts too quickly; token validation is rate-limited.

4. If the token is accepted but a webhook warning appears, retry later and check Telegram API availability.

5. If the token was ever exposed, revoke it instead of continuing to use it.

The /verify command does not connect the chat

• Make sure you sent the complete command in the exact chat you want to connect.

• The code expires after five minutes. Generate a new code if the timer has elapsed.

• Verify that the bot is a chat member. In a channel, grant administrator or posting rights.

• Do not reuse a code after successful verification or regeneration.

• If the chat already appears in the list, activate the existing row instead of adding it again.

• If the UI shows that the active-channel limit has been reached, deactivate another channel.

Previous-app data is not available to import

• The Import tab appears only after the Forge Telegram bot is connected.

• No matching tenant means the previous service has no installation for the canonical URL of this Jira site.

• No supported data means a matching installation exists but has no channel or parse-chat configuration that the current Forge release can import.

• An authentication or configuration message requires an app-side correction; retry once, then contact support with the displayed text and time.

• A temporary service error can be retried with Check again.

• Already configured is not an error. Import will not overwrite the channel on Channels.

• Needs manual setup means at least one old setting cannot be represented safely, such as different project lists for notification delivery and Jira-key parsing, a deleted Jira project, or an unsupported filter comparison.

An imported channel fails the bot check

1. Confirm that the Forge bot, not only the old bot, is present in the displayed Telegram chat.

2. For a channel, make the bot an administrator and allow posting.

3. For a group, allow sending messages. For Jira-key parsing, also make the bot an administrator or disable Group Privacy and re-add it.

4. Select Refresh checks. If you do not want to import that channel, clear its checkbox.

Notifications do not arrive

1. On Overview, confirm that the correct bot is connected and no webhook warning is shown.

2. On Channels, confirm that the channel is Active.

3. Open Configure and verify that the required Event type is selected. Zero selected events means zero notifications.

4. Review Jira projects. Selected projects with no selection blocks every issue.

5. Temporarily simplify the Advanced filter and repeat the test.

6. Verify that the bot can send messages in the Telegram chat.

7. Return to Recent activity and check whether the result is Filtered, Throttled, or Failed.

If no activity row appears, confirm that the event is supported and that the app is installed on the same Jira site where the issue was created or changed.

An event appears as Filtered

Review the rules in the same order used by the connector: Event types, Jira projects, and Advanced filters. For complex fields, use the display name or key. For missing values, use Is empty. Replace or remove a rule that references a field deleted from Jira.

Ticket parsing does not reply

• Ticket parsing works only in a group or supergroup, not in a channel or private chat.

• The channel must be Active, and Ticket parsing must be enabled and saved.

• The bot must be able to read ordinary messages. Make it an administrator, or disable Group Privacy and re-add it.

• The Jira key must use uppercase Latin letters followed by a hyphen and number.

• The issue must exist and belong to a project allowed for that channel.

• Only the first three unique keys are checked in one message.

A channel unexpectedly became Inactive

This usually means Telegram reported that the bot had been removed or could no longer send messages. Restore the bot and its permissions, then activate the channel manually. The app also performs periodic bot-membership checks.

What to include in a support request

• the time of the problem and your time zone;

• the Jira event type and a test issue key without confidential content;

• the channel name and result from Recent activity;

• the error text shown in the Jira UI;

• the Telegram chat type and confirmation of the bot's permissions.

• for import problems, the wizard step and displayed reason, without exporting the complete legacy response.

Never send a bot token, complete webhook URL, or export of a private conversation to support. Contact @JTNSupport on Telegram.