This is the guide how to use Telegram connector for Bitbucket add-on. Here you can find the necessary information how to start working with it step-by-step.

Step 1 - Create your bot

(warning) for Bitbucket administrators

Before you begin to receive notifications, Bitbucket administrator must establish a connection between Telegram and Bitbucket itself.

All communication between these services is performed via your custom telegram bot. If you don’t have one, please use the official documentation to get your bot. (see here)

Here is a quick guide how to:

  1. Open Telegram.

  2. Search for BotFather bot.

  3. Type /start and follow the given workflow to create your bot (bot’s name must end in "bot").

  4. Done. Your bot is created.

Step 2 - Set up connection

(warning) for Bitbucket administrators

After add-on installation Bitbucket administrator must go to Settings → Telegram Connector to establish connection between Bitbucket and Telegram.

Here administrator must add crucial information about created Telegram bot:

This information is given only to bot creator from BotFather. Alongside with other control options.

After configuration is saved, service connection is complete. Now users can set up their own notification rules.

Proxy

Optionally add-on supports sending messages using proxy. To send add-on traffic via proxy add required information into bot configuration settings:

Press Save/Restart to update information.

Step 3 - Create configuration

Users can be notified on events happening with your project or repository via Telegram group chats. All notifications are sent from Bitbucket on behalf of your custom bot used for the whole Bitbucket instance.

Each project or repository administrator can set up configuration that will notify on certain events.

To do so go to project/repository settings → Telegram Connector. On this page you can create as many configurations as you want as long as they use different Telegram group ID.

There are 2 places where user can set up a connector in Bitbucket. 

  1. Repository settings

  2. Project settings

Both sections have identical basic features, yet connector on repository level will send notifications on events in particular repository. While connector on project level will notify on events in all repositories in project.

Configurations created on project level can be viewed on repository page, yet can cannot be edited there. Editing is possible only from add-on configuration in project settings.  

For Project: Bitbucket → Project → Project settings → Telegram Connector

For Repository: Bitbucket → Project → Repository → Repository settings → Telegram Connector

Telegram Group address

To start creating a configuration user must fill in the required fields:

How to get Telegram group ID

  1. Create Telegram group chat (see instruction)

  2. Add bot to group chat (find bot name under "Telegram group ID" field)

  3. Send /info command in chat to get Telegram group ID. (use /start command first if needed)

Telegram group ID will change when group is promoted to supergroup.

This can happen in several cases:

  • Number of group members is reaching 200

  • Administrator is added to group

  • User permissions are changed

  • History visibility is changed

  • Group is made public

You can always test your connection to see if it is set up correctly by clicking on "Test connection” button.

Events picking

After managing the Telegram group ID and bot commands users can select events they want to be notified on. Each configuration is split by 3 column of events depending on their specifics:

Activating toggles next to events will enable sending notifications to Telegram chat as soon as this event takes place in Bitbucket.

To enable/disable the whole event column - activate or deactivate toggle for the whole column.

Press Save to apply your changes.

Telegram is a separate tool. Due to this fact there is a small chance of network connectivity related issues.