Collect Telegram setup issues

[Matvey-Kuk]

Filing this issue cause we hear periodic complains from users about how to set up Telegram. I propose to review the whole telegram setup from 0 to 1 and build a list of places which may be confusing or error-prone. Define unclear steps etc.

My assumption is that there are a few low-hanging fruits which should help us to make TG installation easy and simple.

[raphael-batte]

Possible directions from first explorations:

1. add more clear bot setup description to the OnCall documentation
2. add the TELEGRAM_TOKEN field setup to the Telegram settings tab (table will be as well)
3. after connecting the bot, add the "Send test notification" button directly to the Telegram settings tab

[raphael-batte]

UPD

1. add more clear setup steps description to the OnCall documentation
2. make more clear separation between org/personal Telegram
3. add description about 'localhost' limitations

[raphael-batte]

If the user uses a hobby setup and his address is 'localhost', Telegram can't connect to OnCall.

Solution is to make redirect by TELEGRAM_WEBHOOK_HOST more clear as step.

[raphael-batte]

Proposal upd to the docs page https://grafana.com/docs/oncall/latest/open-source/#update-grafana-oncall-oss:

1. Ensure your OnCall environment is up and running.
2. Create OnCall bot via BotFather and request a key. Then add your key in TELEGRAM_TOKEN in your Grafana OnCall Env Variables.
3. Telegram connection requires external URL. Make sure that you set it in TELEGRAM_WEBHOOK_HOST in your Grafana OnCall Env Variables.
4. Reboot backend and setup Team Telegram in ChatOps tab. For personal Telegram connection use Telegram tab in profile settings.

[raphael-batte]

ChatOps setup upd:

[raphael-batte]

Documentation:

I. Setup connection to Telegram API

1. Ensure your OnCall environment is up and running.
2. Create OnCall bot via BotFather and save HTTP API token which provided.
3. Add received token to TELEGRAM_TOKEN row in your Grafana OnCall Env Variables page.
4. Make sure that you has set the TELEGRAM_WEBHOOK_HOST variable on the Env Variables page. TELEGRAM_WEBHOOK_HOST must start with “https://” and be publicly available (meaning that it can be reached by Telegram servers). If your host is private or local, you can use redirecting services like Ngrok.
5. Reboot backend after TELEGRAM_WEBHOOK_HOST update. (ps this will be eliminated by update)
6. Now you can connect personal Telegram accounts or manage team workspace in ChatOps tab.

If steps 3-4 don't meet Telegram's requirements, parts 2-3 are locked and user see warning.

ChatOps Telegram tab:

II. Setup team Telegram workspace

1. Create a New Private Channel and enable Sign Messages in channel settings.
2. Create a new discussion group. This group handles alert actions and comments.
3. Connect the discussion group with the channel. In Manage Channel, click Discussion to find and add your group.
4. Click https://t.me/* to add the OnCall bot to your contacts. Add the bot to your channel as an Admin and allow it to Post Messages.
5. Add the bot to the discussion group.
6. Send the verification code *** to the channel and wait for the confirmation message.
7. Start to manage alerts in your Telegram workspace.

• Make sure your team connect Telegram in their OnCall user profiles. Users can perform notification actions (acknowledge, resolve, silence) and discuss alerts in the comments section only if they set up personal Telegram connection.
• If you already have a private channel to use with OnCall, you can use the following activation code: ***

User profile tab:

III. Setup personal Telegram connection

‘Connect automatically’ button or add bot manually:

1. Go to https://t.me/*
2. Send *** to telegram bot
3. Start to manage alerts in your Team Telegram workspace and receive personal notifications as DM from bot.

[raphael-batte]

Initial info for users.

ChatOps:

You can manage incidents directly in your team channel. Make sure your team connects Telegram in their OnCall user profiles too. Users can perform actions (acknowledge, resolve, silence) and discuss alerts only if they set up personal Telegram connection. Notifications will be serve as links to the channel.

To manage incidents as user’s direct messages, your need to connect only personal Telegram.

Alert: Telegram environment is not detected. 
Before connecting channel, please configure your OnCall bot and fill out ENV variables related to Telegram.

Find more in OnCall documentation.

[raphael-batte]

Connect personal Telegram

You can manage incidents directly in your personal Telegram. To establish connection you need to setup Telegram environment first.

Alert: Telegram environment is not detected. 
Before connecting personal telegram account, please configure your OnCall bot and fill out ENV variables related to Telegram.

Find more in OnCall documentation.

[vadimkerr]

Closing this issue since documentation issues should be resolved by https://github.com/grafana/oncall/pull/406.

[tommy04062019]

@vadimkerr I am really so tired and spend so much time to configure Telegram connection. My configuration satisfies all the conditions stated in the documentation, So far it still doesn't work and I don't understand where I went wrong. Some configurations that I have set bellow:

• Create a Telegram bot and turn off Group Privacy

      - name: FEATURE_TELEGRAM_INTEGRATION_ENABLED
        value: "True"
      - name: TELEGRAM_WEBHOOK_HOST
        value: https://74a3-27-72-98-102.ap.ngrok.io
      - name: TELEGRAM_TOKEN
        value: 5730377723:xxxx

• Chat with bot with /start command. Nothing response from the bot. Additionally, webhook https://74a3-27-72-98-102.ap.ngrok.io stills be called via POST to path /telegram with status code 200.

[AMDTonyRyzen]

I agree with the previous speaker. It would be easier to set up integration, knowing that you need to throw in the telegram api curl -F "url=https://oncall-domain.com/telegram/" https://api.telegram.org/bot[token]/setWebhook