Install the App and Connect a Telegram Bot

Each Jira installation uses a bot owned by the customer. Your organization controls the bot's name, its access to Telegram chats, and token revocation.

Before you begin

• Confirm that Vivid Connector is installed on the required Jira Cloud site. If it is not installed, open the Atlassian Marketplace listing and install it with a Jira administrator account.

• Prepare a Telegram account that can create bots and add them to the required channels or groups.

• Assign an owner for the bot within your organization. The token grants full Bot API access for that bot and must be treated as a secret.

Step 1. Create a bot in Telegram

1. Open the official @BotFather account.

2. Send /newbot.

3. Choose a display name and a unique username ending in bot.

4. Copy the issued token. It contains a numeric identifier, a colon, and a secret string.

5. Never publish the token in a Jira issue, Telegram chat, documentation page, or screenshot.

If the token is exposed, revoke it immediately with @BotFather, generate a new one, and update the app configuration.

Step 2. Open the configuration page in Jira

Open Jira app management, locate Vivid Connector for Jira and Telegram (Forge Edition), and open its configuration. On first use, the page displays a connection card and setup wizard.

If Jira asks for a database update

Before loading any bot, channel, project, or activity settings, the page checks that every required database update has completed. When updates are pending, the complete settings interface is replaced by Database update required.

1. Select Run database updates.

2. Keep the page open while the progress indicator is visible.

3. After all updates finish, the page unlocks automatically and continues to the normal setup or Overview screen.

The existing automatic daily database-update run remains enabled; the button provides an immediate recovery path and does not change that schedule. If an update is already running, the button is temporarily unavailable and the page checks for completion automatically.

If the page cannot check database status, select Check again. If an update fails, retry Run database updates; record the displayed error and contact support if it fails repeatedly.

Step 3. Validate and save the token

1. Select Connect bot.

2. Paste the token into Bot token.

3. Continue. The app first validates the format and then calls Telegram's getMe method.

4. After successful validation, the token is stored in Forge secret storage.

5. The app obtains its Forge webtrigger URL and registers it automatically as the Telegram webhook. Manual webhook setup is not required.

On the confirmation screen, verify the bot name and @username. The UI displays only a masked token preview; the usable secret is never returned to the browser.

If the token is saved but webhook registration fails, the app displays a warning. Resolve the warning before adding channels because incoming /verify commands and ticket-parsing messages depend on the webhook.

After the bot is connected, the settings page also checks the read-only previous-app migration service for supported data belonging to the same Jira base URL. Existing customers can continue with Import Settings from the Previous Vivid Connector App. New customers can ignore Import and add channels normally.

Step 4. Prepare the bot's Telegram permissions

For a Telegram channel

Add the bot to the channel and allow it to post messages. The app must also be able to verify the bot's membership status.

For a group or supergroup

For event notifications, the bot needs to be a member and able to send messages. For ticket parsing, it must also be able to read ordinary group messages. Use either option:

• make the bot a group administrator; or

• disable Group Privacy for the bot in @BotFather, then remove and re-add the bot to the group.

Re-adding the bot after changing Group Privacy is important because Telegram may not apply the new mode to an existing membership automatically.

Update the token

1. On Overview, select Update Token.

2. Enter and confirm the new token.

3. The app validates the bot again and registers a webhook for the new token.

4. Add the new bot to every previously configured Telegram chat and verify its permissions before resuming notifications.

Changing the token also changes the Telegram bot when the new token belongs to a different bot account. A configuration stored in Jira cannot add the new bot to Telegram chats automatically.

Remove the token

Remove token attempts to delete the Telegram webhook and removes the token, cached bot details, and stored webhook URL from Forge KVS. The app can no longer send notifications or process Telegram commands afterward.

Removing the token does not remove the bot from Telegram chats. Remove it there manually when required. Before reconnecting with another bot, review every channel and its permissions.

Next step

If you used the previous app, continue with Import Settings from the Previous Vivid Connector App. Otherwise continue with Connect and Manage Telegram Channels and Groups.