From 376c99b70fb4e241fb1550ce689a0ba20c2d738f Mon Sep 17 00:00:00 2001 From: antonio <45235678+tonypowa@users.noreply.github.com> Date: Thu, 9 May 2024 14:01:05 +0200 Subject: [PATCH] alerting: webhook doc update (#87492) (#87549) alerting/webhook doc update (#87492) * alerting/webhook doc update * text formath * fixed admonition * typo * headings * formatted headings and prettified it all * one more heading (cherry picked from commit d83cbe4d85a544482767a60fbc8c80dd989b79cb) --- .../integrations/configure-slack.md | 2 +- .../integrations/configure-telegram.md | 95 +++++++++++++++++++ .../integrations/webhook-notifier.md | 43 ++++++--- 3 files changed, 125 insertions(+), 15 deletions(-) create mode 100644 docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-telegram.md diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-slack.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-slack.md index f08ab60fdaa..e80048d0e53 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-slack.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-slack.md @@ -16,7 +16,7 @@ title: Configure Slack for Alerting weight: 300 --- -## Configure Slack for Alerting +# Configure Slack for Alerting Use the Grafana Alerting - Slack integration to send Slack notifications when your alerts are firing. diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-telegram.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-telegram.md new file mode 100644 index 00000000000..e0c237211de --- /dev/null +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-telegram.md @@ -0,0 +1,95 @@ +--- +canonical: https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/configure-telegram/ +description: Configure the Telegram integration to connect alerts generated by Grafana Alerting +keywords: + - grafana + - alerting + - telegram + - integration +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Telegram +title: Configure Telegram for Alerting +weight: 300 +--- + +# Configure Telegram for Alerting + +Use the Grafana Alerting - Telegram integration to send [Telegram](https://telegram.org/) notifications when your alerts are firing. + +## Before you begin + +### Telegram bot API token and chat ID + +To integrate Grafana with Telegram, you need to obtain a Telegram **bot API token** and a **chat ID** (i.e., the ID of the Telegram chat where you want to receive the alert notifications). + +### Set up your Telegram bot + +Create a [Telegram bot](https://core.telegram.org/bots/api). You can associate this bot to your chats and perform different actions with it, such as receiving alerts from Grafana. + +To set up the bot, complete the following steps. + +1. **Open the Telegram app** on your device. +1. Find the Telegram bot named **BotFather**. +1. Type or press `/newbot`. +1. Choose a name for the bot. It must end in **bot** or **\_bot**. E.g. "my_bot". +1. **Copy the API token**. + +### Chat ID + +Add the bot to a group chat by following the steps below. Once the bot is added to the chat, you will be able to route your alert notifications to that group. + +1. In the Telegram app, **open a group or start a new one**. +1. Search and **add the bot to the group**. +1. **Interact with the bot** by sending a dummy message that starts with "`/`". E.g. `/hola @bot_name`. + + {{< figure src="/media/blog/telegram-grafana-alerting/telegram-screenshot.png" alt="A screenshot that shows a message to a Telegram bot." >}} + +1. To obtain the **chat ID**, send an [HTTP request](https://core.telegram.org/bots/api#getupdates) to the bot. Copy the below URL and replace `{your_bot_api_token}` with your bot API token. + + ``` + https://api.telegram.org/bot{your_bot_api_token}/getUpdates + ``` + +1. **Paste the URL in your browser**. +1. If the request is successful, it will return a response in JSON format. + + ``` + ... + "chat": { + "id": -4065678900, + "title": "Tony and Hello world bot", + "type": "group", + ... + ``` + +1. Copy the value of the `“id”` that appears under `“chat”`. + +## Procedure + +To create your Telegram integration in Grafana Alerting, complete the following steps. + +1. Navigate to **Alerts & IRM** -> **Alerting** -> **Contact points**. +1. Click **+ Add contact point**. +1. Enter a contact point name. +1. From the Integration list, select Telegram. +1. In the **BOT API Token** field, copy in the bot API token. +1. In the **Chat ID** field, copy in the chat ID. +1. Click **Test** to check that your integration works. +1. Click **Save contact point**. + +## Next steps + +To add the contact point and integration you created to your default notification policy, complete the following steps. + +1. Navigate to **Alerts & IRM** -> **Alerting** -> **Notification policies**. +1. In the **Default policy**, click the ellipsis icon (…) and then **Edit**. +1. Change the default policy to the contact point you created. +1. Click **Update default policy**. + +{{}} +If you have more than one contact point, add a new child notification policy rather than edit the default one, so you can route specific alerts to Telegram. +{{}} diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md index 769297b6d3e..13d072a0279 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md @@ -24,9 +24,11 @@ title: Configure the webhook notifier for Alerting weight: 200 --- -### Configure the webhook notifier for Alerting +# Configure the webhook notifier for Alerting -Example JSON body: +The webhook notification is a simple way to send information about a state change over HTTP to a custom endpoint. Using this notification you could integrate Grafana into a system of your choosing. + +## Webhook JSON payload ```json { @@ -98,9 +100,9 @@ Example JSON body: } ``` -### Webhook fields +## Webhook fields -## Body +### Body | Key | Type | Description | | ----------------- | ------------------------- | ------------------------------------------------------------------------------- | @@ -136,18 +138,31 @@ Example JSON body: | panelURL | string | **Will be deprecated soon** | | imageURL | string | URL of a screenshot of a panel assigned to the rule that created this notification | -### Removed fields related to dashboards +{{< admonition type="note" >}} +Alert rules are not coupled to dashboards anymore therefore the fields related to dashboards `dashboardId` and `panelId` have been removed. +{{< /admonition >}} -Alerts are not coupled to dashboards anymore therefore the fields related to dashboards `dashboardId` and `panelId` have been removed. +## Procedure -## WeCom +To create your webhook integration in Grafana Alerting, complete the following steps: -WeCom contact points need a Webhook URL. These are obtained by setting up a WeCom robot on the corresponding group chat. To obtain a Webhook URL using the WeCom desktop Client please follow these steps: +1. Navigate to **Alerts & IRM** -> **Alerting** -> **Contact points**. +1. Click **+ Add contact point**. +1. Enter a contact point name. +1. From the Integration list, select **Webhook**. +1. In the **URL** field, copy in your Webhook URL. +1. Click **Test** to check that your integration works. +1. Click **Save contact point**. -1. Click the "..." in the top right corner of a group chat that you want your alerts to be delivered to -2. Click "Add Group Robot", select "New Robot" and give your robot a name. Click "Add Robot" -3. There should be a Webhook URL in the panel. +## Next steps -| Setting | Description | -| ------- | ------------------ | -| Url | WeCom webhook URL. | +To add the contact point and integration you created to your default notification policy, complete the following steps. + +1. Navigate to **Alerts & IRM** -> **Alerting** -> **Notification policies**. +1. In the **Default policy**, click the ellipsis icon (…) and then **Edit**. +1. Change the default policy to the contact point you created. +1. Click **Update default policy**. + +{{< admonition type="note" >}} +If you have more than one contact point, add a new notification policy rather than edit the default one, so you can route specific alerts to your webhook. +{{< /admonition >}}