Instructions

...

Telegram is a "messaging app with a focus on speed and security, it’s super-fast, simple and free". It's cloud based like Slack and RockChat. According to Telegram, the app's architecture does not support federation yet like Mattermost.

The messaging format is simpler that RocketChat, Mattermost or Slack. It doesn't allow complex messages like showing avatars, fields, headers, etc. The message format is closer to an SMS message than a "Card" like Slack provides.

JEMHCloud supports Telegram notifications from Issue Events and Post Functions. You will be able to notify your Telegram Channels when JEMHC detects an issue change.

Configuring the Telegram Connection

In order to send Telegram notifications from Issue and Post function events, you need to create a Bot and add a Bot a group or a private conversation.

Once you have the Bot, you can enter the bot token to JEMHCloud in order to create the Telegram Connection. 

Configure Telegram's Bot

For this step, we are assuming that you have a Telegram account.

1. Log into Telegram Web Portal and talk to the BotFather. The link is the following https://web.telegram.org/#/im?p=@BotFather 
2. To create a new bot, send the message /newbot to the BotFather. Enter a unique Bot Name and Bot Username (for example myCompoanyJira and my CompanyJira_bot).
3. This will create and configure the bot. The bot has a token associated that will be used to authenticate JEMHC with Telegram sending messages as your bot.
4. Image Added
5. Click on the t.me/MyBotUsername_bot link to start a conversation with your Bot. Send a message to the Bot. This will simplify the bot user search when creating a group.
6. Image Added
7. Create a Group where you want JEMHC to notify about issue changes. Add the created bot and your team members to the group.
8. Image AddedImage AddedImage Added
9. Image Added
10. Double check that the Bot is added to the group. Use @ notation to mention the bot user. 
11. Copy the token BotFather has generated for your room.

Create JEMHCloud's Telegram Connection

1. Go to JEMHCloud → Messages → Telegram Connections
2. Click on Create button.
3. Once in the Telegram Connection form, enter a name and paste the token generated in Telegram's BotFather chat.
4. Image Added
5. Submit. If the configuration is ok, you should see a test message in Telegram's chat
6. Image Added
7. Image Added

Create JEMHCloud's Telegram Notification Mapping

Like Email and SMS Notification Mapping, Telegram Notification Mapping is in charge of sending Telegram messages from Issue events through the Telegram Connection.

Creating a Telegram Notification Mapping:

1. Go to JEMH Cloud → Notifications → Telegram → Create
2. Complete the form, select the nominated project, select the Telegram Connection and the chat (for example the new group chat where the bot is a member). Enter a velocity script if you want to modify the notification behavior at runtime (more below). Be sure that the Group Chat is listed in the select. If not, mention the bot user in the Telegram's chat group.
3. Image Added
4. On Submit, you should see the new Telegram mapping
5. Image Added
6. To test the mapping, create an issue in the nominated project and go to Auditing → Events
7. You should see the issue created an event in the queue. When the event has been processed, the configured channel in the mapping should have received a Telegram message
8. Image Added
9. Image Added
10. Image Added
11. The report of the event should confirm the message sent 
12. Image Added
13. In Auditing → Outbound Messages → Type Telegram, the table should show the Telegram messages sent and the cog icon should show their contents.
14. Image Added
15. Image Added

Send Telegram Notifications from Post Functions

JEMHCloud allows you to send Telegram notifications when Issue transitions are performed through JIRA Post Functions.

Adding the Telegram Notification Post Function to workflow transition:

1. Go to right corner Cog → JIRA Administration → Issue → Workflows. Edit the workflow of the project you want to add the Post Function
2. Click on the transition you want to change and select the Post Functions tab. Click on Add post function
3. Image Added
4. Select Send Telegram Notification by JEMHCloud and click Add
5. Image Added
6. Set the Telegram Connection and Velocity script if necessary. Press Add/Update
7. Image Added
8. Once the Post Function is in the right position, publish the workflow draft.
9. Image Added
10. To test the post function, go to an issue of the given workflow and perform the transition that will fire the post function.
11. Image Added
12. Post function event should appear in JEMH Cloud → Notifications → Events.
13. Image Added
14. The event report should show the used incoming webhook URL
15. Image Added
16. The message in Telegram:
17. Image Added
18. In Auditing → Outbound Messages, the table should show the Telegram messages sent and the cog icon should show their contents.
19. Image Added
20. Image Added

Filter Scripts

Both Telegram Notification Mapping and Telegram Post Function behavior can be changed at runtime with a Velocity Script. The script can use the event data or be time-based to change how notifications are performed.

Change Channel

#if ($context.issue.fields.priority.name.textValue() != 'Critical')
  $telegramNotificationUtils.setChat('Fernando') ## JEMHC to send the message to chat. It can be the chat id or a name of a group or a user.

Restrict notifications to specific time ranges

#if (!$dateTimeUtils.betweenHours("18:00", "06:00"))
   $telegramNotificationUtils.inhibitNotification() ## Telegram messages are not sent during business hours **
#end

Restrict by priority

#if ($context.issue.fields.priority.name.textValue() != 'Blocker')
   $telegramNotificationUtils.inhibitNotification()
#end

Related articles

...