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

• Install it from its Atlassian Marketplace listing on the required Jira Cloud site 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.

The production app requires an active paid Marketplace subscription. If Jira reports that the subscription is inactive, setup and all existing connector processing remain paused until the license is active again.

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, creates a separate installation-scoped webhook secret, and registers both with Telegram automatically. 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.

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.

For a supergroup with Topics

Add the bot to the supergroup, then connect each required topic separately by sending the Jira verification command inside that topic. The bot's membership and message-reading permission apply to the whole group, but Jira projects, events, filters, active state, and ticket parsing are stored independently for every connected topic.

Adding the supergroup by ID, username, or public link connects only its root destination. Use verification inside a topic when notifications and parsing must stay in that topic.

Update the token

1. On Overview, select Update Token.

2. Enter and confirm the new token.

3. The app validates the bot again, rotates the webhook secret, 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, webhook secret, 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 delete saved channels, project selections, event selections, ticket-parsing settings, or advanced filters. It also does not remove the bot from Telegram chats. Remove it there manually when required. Before reconnecting with another bot, review every saved channel and the new bot's permissions.

Next step

Continue with Connect and Manage Telegram Channels and Groups.