Merge pull request #1127 from influxdata/flux/telegram-pkg

Flux Telegram package

content/v2.0/reference/flux/stdlib/contrib/teams/message.md

@@ -2,7 +2,7 @@
 title: teams.message() function
 description: >
   The `teams.message()` function sends a single message to a Microsoft Teams channel using
-  an [incoming webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks&amp?page=3).
+  an [incoming webhook](https://docs.microsoft.com/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook).
 menu:
   v2_0_ref:
     name: teams.message

content/v2.0/reference/flux/stdlib/contrib/telegram/_index.md

@@ -0,0 +1,50 @@
+---
+title: Flux Telegram package
+list_title: Telegram package
+description: >
+  The Flux Telegram package provides functions for sending messages to
+  [Telegram](https://telegram.org/) using the [Telegram Bot API](https://core.telegram.org/bots/api).
+  Import the `contrib/sranka/telegram` package.
+menu:
+  v2_0_ref:
+    name: Telegram
+    parent: Contributed
+weight: 202
+v2.0/tags: [functions, teams, microsoft, package]
+---
+
+The Flux Telegram package provides functions for sending messages to
+[Telegram](https://telegram.org/) using the [Telegram Bot API](https://core.telegram.org/bots/api).
+Import the `contrib/sranka/telegram` package:
+
+```js
+import "contrib/sranka/telegram"
+```
+
+{{< children type="functions" show="pages" >}}
+
+## Set up a Telegram bot
+The **Telegram Bot API** requires a **bot token** and a **channel ID**.
+To set up a Telegram bot and obtain the required bot token and channel ID:
+
+1.  [Create a new Telegram account](https://telegram.org/) or use an existing account.
+2.  [Create a Telegram bot](https://core.telegram.org/bots#creating-a-new-bot).  
+    Telegram provides a **bot token** for the newly created bot.
+3.  Use the **Telegram application** to create a new channel.
+4.  [Add the new bot to the channel](https://stackoverflow.com/questions/33126743/how-do-i-add-my-bot-to-a-channel) as an **Administrator**.
+    Ensure the bot has permissions necessary to **post messages**.
+5.  Send a message to bot in the channel.
+6.  Send a request to `https://api.telegram.org/bot$token/getUpdates`.
+
+    ```sh
+    curl https://api.telegram.org/bot$token/getUpdates
+    ```
+
+    Find your **channel ID** in the `id` field of the response.
+
+
+{{% note %}}
+#### Package author and maintainer
+**Github:** [@sranka](https://github.com/sranka)  
+**InfluxDB Slack:** [@sranka](https://influxdata.com/slack)
+{{% /note %}}

content/v2.0/reference/flux/stdlib/contrib/telegram/endpoint.md

@@ -0,0 +1,106 @@
+---
+title: telegram.endpoint() function
+description: >
+  The `telegram.endpoint()` function sends a message to a Telegram channel
+  using data from table rows.
+menu:
+  v2_0_ref:
+    name: telegram.endpoint
+    parent: Telegram
+weight: 202
+---
+
+The `telegram.endpoint()` function sends a message to a Telegram channel
+using data from table rows.
+
+_**Function type:** Output_
+
+```js
+import "contrib/sranka/telegram"
+
+telegram.endpoint(
+  url: "https://api.telegram.org/bot",
+  token: "S3crEtTel3gRamT0k3n",
+  parseMode: "MarkdownV2",
+  disableWebPagePreview: false,
+)
+```
+
+{{% note %}}
+For information about retrieving your Telegram **bot token** and **channel ID**,
+see [Set up a Telegram bot](/v2.0/reference/flux/stdlib/contrib/telegram/#set-up-a-telegram-bot).
+{{% /note %}}
+
+## Parameters
+
+### url
+URL of the Telegram bot endpoint.
+Default is `https://api.telegram.org/bot`.
+
+_**Data type:** String_
+
+### token
+<span class="req">Required</span>
+Telegram bot token.
+
+_**Data type:** String_
+
+### parseMode
+[Parse mode](https://core.telegram.org/bots/api#formatting-options) of the message text.
+Default is `"MarkdownV2"`.
+
+_**Data type:** String_
+
+### disableWebPagePreview
+Disable preview of web links in the sent message.
+Default is `false`.
+
+_**Data type:** Boolean_
+
+## Usage
+`telegram.endpoint` is a factory function that outputs another function.
+The output function requires a `mapFn` parameter.
+
+### mapFn
+A function that builds the object used to generate the POST request.
+Requires an `r` parameter.
+
+_**Data type:** Function_
+
+`mapFn` accepts a table row (`r`) and returns an object that must include the
+following fields:
+
+- `channel`
+- `text`
+- `silent`
+
+_For more information, see [`telegram.message()`](/v2.0/reference/flux/stdlib/contrib/telegram/message/)._
+
+## Examples
+
+##### Send critical statuses to a Telegram channel
+```js
+import "influxdata/influxdb/secrets"
+import "contrib/sranka/telegram"
+
+token = secrets.get(key: "TELEGRAM_TOKEN")
+endpoint = telegram.endpoint(token: token)
+
+crit_statuses = from(bucket: "example-bucket")
+  |> range(start: -1m)
+  |> filter(fn: (r) => r._measurement == "statuses" and status == "crit")
+
+crit_statuses
+  |> endpoint(mapFn: (r) => ({
+      channel: "-12345",
+      text: "Disk usage is **${r.status}**.",
+      silent: true
+    })
+  )
+```
+
+{{% note %}}
+#### Package author and maintainer
+**Github:** [@sranka](https://github.com/sranka)  
+**InfluxDB Slack:** [@sranka](https://influxdata.com/slack)
+{{% /note %}}

content/v2.0/reference/flux/stdlib/contrib/telegram/message.md

@@ -0,0 +1,107 @@
+---
+title: telegram.message() function
+description: >
+  The `telegram.message()` function sends a single message to a Telegram channel using
+  the [`sendMessage` method of the Telegram Bot API](https://core.telegram.org/bots/api#sendmessage).
+menu:
+  v2_0_ref:
+    name: telegram.message
+    parent: Telegram
+weight: 202
+---
+
+The `telegram.message()` function sends a single message to a Telegram channel using
+the [`sendMessage` method of the Telegram Bot API](https://core.telegram.org/bots/api#sendmessage).
+
+_**Function type:** Output_
+
+```js
+import "contrib/sranka/telegram"
+
+telegram.message(
+  url: "https://api.telegram.org/bot",
+  token: "S3crEtTel3gRamT0k3n",
+  channel: "-12345",
+  text: "Example message text",
+  parseMode: "MarkdownV2",
+  disableWebPagePreview: false,
+  silent: true
+)
+```
+
+{{% note %}}
+For information about retrieving your Telegram **bot token** and **channel ID**,
+see [Set up a Telegram bot](/v2.0/reference/flux/stdlib/contrib/telegram/#set-up-a-telegram-bot).
+{{% /note %}}
+
+## Parameters
+
+### url
+URL of the Telegram bot endpoint.
+Default is `https://api.telegram.org/bot`.
+
+_**Data type:** String_
+
+### token
+<span class="req">Required</span>
+Telegram bot token.
+
+_**Data type:** String_
+
+### channel
+<span class="req">Required</span>
+Telegram channel ID.
+
+_**Data type:** String_
+
+### text
+Message text.
+
+_**Data type:** String_
+
+### parseMode
+[Parse mode](https://core.telegram.org/bots/api#formatting-options) of the message text.
+Default is `"MarkdownV2"`.
+
+_**Data type:** String_
+
+### disableWebPagePreview
+Disable preview of web links in the sent message.
+Default is `false`.
+
+_**Data type:** Boolean_
+
+### silent
+Send message [silently](https://telegram.org/blog/channels-2-0#silent-messages).
+Default is `true`.
+
+_**Data type:** Boolean_
+
+## Examples
+
+##### Send the last reported status to a Microsoft Teams channel
+```js
+import "influxdata/influxdb/secrets"
+import "contrib/sranka/telegram"
+
+token = secrets.get(key: "TELEGRAM_TOKEN")
+
+lastReported =
+  from(bucket: "example-bucket")
+    |> range(start: -1m)
+    |> filter(fn: (r) => r._measurement == "statuses")
+    |> last()
+    |> findRecord(fn: (key) => true, idx: 0)
+
+    telegram.message(
+      token: token,
+      channel: "-12345"
+      text: "Disk usage is **${lastReported.status}**.",
+    )
+```
+
+{{% note %}}
+#### Package author and maintainer
+**Github:** [@sranka](https://github.com/sranka)  
+**InfluxDB Slack:** [@sranka](https://influxdata.com/slack)
+{{% /note %}}