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, destination, event, Jira key, and result. A topic destination appears as Group / Topic; a group-root or ordinary-group destination shows only the group name. When Telegram has not exposed a topic name yet, the destination temporarily uses the Topic #ID fallback.

The list is a fixed ten-outcome history, not a full audit log. Older outcomes are overwritten as new ones arrive. If no new events arrive, existing outcomes remain until they are overwritten or the app installation is removed.

The subscription is inactive

Vivid Connector for Jira and Telegram is a paid Marketplace app. If the settings page reports that an active subscription is required, renew or reactivate the Marketplace license. While inactive, resolver actions, Jira event processing, scheduled checks, and Telegram webhook processing are paused. Existing stored configuration is not automatically deleted.

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 or topic you want to connect.

• For a forum topic, confirm that the bot's response appears inside that topic; sending the command elsewhere connects a different destination.

• 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 exact root or Topic row already appears in the list, activate the existing row instead of adding it again.

Notifications do not arrive

1. Confirm that the Marketplace subscription is active.

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

3. On Channels, confirm that the exact root or Topic row is Active.

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

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

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

7. Verify that the bot can send messages in the Telegram chat and topic.

8. Return to Recent activity and check whether the result is Filtered, Throttled, or Failed. Temporary delivery work is recovered for up to one hour from the original Jira event.

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 Is one of and Is not one of, inspect every value row: matching ignores case and surrounding whitespace and checks all comparable values in Jira arrays and objects. A null, blank, empty, or non-comparable actual value fails both operators. For missing values, use Is empty. Replace or remove a rule that references a field deleted from Jira. For Watchers, remember that the list is checked only during an already supported Jira event; adding a watcher alone does not create a notification event.

A Watchers filter appears as Failed

1. Confirm that the app can browse the issue's project and that issue-security settings allow access to the issue.

2. In Jira permissions, grant the app View voters and watchers for the project.

3. Retry with a controlled Issue created, Issue updated, or supported comment event. A watcher change by itself is not a supported event.

4. If only Watchers-filtered channels fail, Jira may have denied the dedicated watcher request or returned an incomplete list. Channels without a Watchers rule continue to be evaluated.

Ticket parsing does not reply

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

• The exact root or Topic row must be Active, and Ticket parsing must be enabled and saved for that row.

• A topic does not inherit Ticket parsing from the group root or another topic.

• 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 destination.

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

A notification appears in the group root instead of a topic

Remove the unintended root row if it is not needed, generate a new verification code, and send it inside the required topic. Adding a forum group by ID, username, or link always connects the root. Existing groups created before topic support also remain root destinations until a topic is connected separately.

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.

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

Grouped notifications

If Notification grouping is enabled for a channel or Topic, the app intentionally waits 60 seconds from the first matching event before it sends a summary. This applies to a single event as well. Check the grouping setting before treating that interval as a delivery failure.