improve notifications documentation (telegram, webhook)
This commit is contained in:
Dmitry Verkhoturov
committed by
Umputun
Umputun
parent
4f672cdec5
commit
e341e25f0f
@@ -230,10 +230,10 @@ type NotifyGroup struct {
|
||||
} `group:"email" namespace:"email" env-namespace:"EMAIL"`
|
||||
Slack struct {
|
||||
Token string `long:"token" env:"TOKEN" description:"slack token"`
|
||||
Channel string `long:"chan" env:"CHAN" description:"slack channel"`
|
||||
Channel string `long:"chan" env:"CHAN" description:"slack channel for admin notifications"`
|
||||
} `group:"slack" namespace:"slack" env-namespace:"SLACK"`
|
||||
Webhook struct {
|
||||
WebhookURL string `long:"url" env:"URL" description:"webhook notification URL"`
|
||||
WebhookURL string `long:"url" env:"URL" description:"webhook URL for admin notifications"`
|
||||
Template string `long:"template" env:"TEMPLATE" description:"webhook authentication template" default:"{\"text\": \"{{.Text}}\"}"`
|
||||
Headers []string `long:"headers" description:"webhook authentication headers in format --notify.webhook.headers=Header1:Value1,Value2,..."` // env NOTIFY_WEBHOOK_HEADERS split in code bellow to allow , inside ""
|
||||
Timeout time.Duration `long:"timeout" env:"TIMEOUT" description:"webhook timeout" default:"5s"`
|
||||
|
||||
@@ -2,28 +2,30 @@
|
||||
title: Notification
|
||||
---
|
||||
|
||||
## Email
|
||||
There are two types of notifications, "Admin" and "User" notifications. Admin notifications will forward every new comment on the site to your desired location, like email or Telegram channel. User notifications will allow users to subscribe to replies to their comments. Enabling user notifications doesn't enable them by default; for example, users need to click a button in the interface to subscribe to email notifications even if they are logged in by email.
|
||||
|
||||
[Email](https://remark42.com/docs/configuration/email/) and [Telegram](https://remark42.com/docs/configuration/telegram/) notifications are described on separate pages.
|
||||
|
||||
## Slack admin notifications
|
||||
|
||||
In order to integrate notifications from remark42 with the [slack](https://slack.com), you should create [a bot](https://slack.com/intl/en-cn/help/articles/115005265703-Create-a-bot-for-your-workspace) and obtain a token.
|
||||
To integrate notifications from remark42 with [Slack](https://slack.com), you should create [a bot](https://slack.com/intl/en-cn/help/articles/115005265703-Create-a-bot-for-your-workspace) and obtain a token.
|
||||
|
||||
### Create a Slack Bot
|
||||
|
||||
1. Create a [Slack app](https://api.slack.com/apps/new) if you don't already have one, or select an existing app you've created.
|
||||
2. Click the OAuth & Permissions tab in the left sidebar.
|
||||
3. Below Bot Token Scopes, select the `chat:write`, `chat:write.public` and `channels:read` scopes. Then click Add an OAuth Scope.
|
||||
3. Below Bot Token Scopes, select the `chat:write`, `chat:write.public`, and `channels:read` scopes. Then click Add an OAuth Scope.
|
||||
4. Scroll to the top of the page, and click on Install to workspace.
|
||||
5. You should see the "_View basic information about public channels in your workspace_", "_Send Message as ..._" and "_Send messages to channels ... isn't a member of_" as the permission, then click allow.
|
||||
6. You can then see you token, in the form of `xoxb-...-...-...`
|
||||
6. You can then see the token, in the form of `xoxb-...-...-...`
|
||||
|
||||
### Remark42 configuration
|
||||
|
||||
The slack token which you obtained before should be used as `NOTIFY_SLACK_TOKEN`.
|
||||
The Slack token which you obtained before should be used as `NOTIFY_SLACK_TOKEN`.
|
||||
|
||||
You also need to set `NOTIFY_ADMINS=slack` for the Slack notification to be active.
|
||||
|
||||
By default, the notification are sent to the `general` channel on slack. If you need another channel, you can specify it, for instance with `NOTIFY_SLACK_CHAN=random`.
|
||||
By default, the notifications are sent to the `general` channel on Slack. If you need another channel, you can specify it with `NOTIFY_SLACK_CHAN=channel_name`.
|
||||
|
||||
```
|
||||
- NOTIFY_ADMINS=slack
|
||||
@@ -38,47 +40,10 @@ If all goes fine, you should be able to see the following message on your Slack
|
||||
> New comment from _author_ -> _original author_
|
||||
>
|
||||
> > [Demo | Remark42](http://127.0.0.1:8080/web/#remark42__comment-11288987987)
|
||||
> > This is the comment written by _author_
|
||||
> > This is the comment written by the _author_
|
||||
|
||||
## Telegram
|
||||
## WebHook admin notifications
|
||||
|
||||
### Telegram notifications for administrators
|
||||
You need to set `NOTIFY_ADMINS=webhook` to enable WebHook notifications on all new comments and set at least `NOTIFY_WEBHOOK_URL` for them to start working.
|
||||
|
||||
In order to integrate notifications about any comment on your sites with remark42 with [telegram](https://telegram.org)
|
||||
|
||||
1. Set `NOTIFY_ADMINS=telegram`
|
||||
1. Make [a channel](https://telegram.org/faq_channels) and add it's ID to remark42 configuration as `NOTIFY_TELEGRAM_CHAN`
|
||||
* To obtain public channel ID, forward any message from it to [@JsonDumpBot](https://t.me/JsonDumpBot): look for `id` in `forward_from_chat`.
|
||||
* If you want to use private channel or chat, use [these instructions](https://github.com/GabrielRF/telegram-id) to obtain the ID.
|
||||
1. Get a token according to the instruction below and add it to the configuration as well
|
||||
|
||||
### Getting token for Telegram
|
||||
|
||||
In order to get token "just talk to [BotFather](https://core.telegram.org/bots#6-botfather)". All you need is to send `/newbot` command, and choose the name for your bot (it must end in `bot`). This is it, you got a token which you'll need to write down into remark42 configuration as `TELEGRAM_TOKEN`.
|
||||
|
||||
_Example of such a "talk":_
|
||||
|
||||
```
|
||||
Umputun:
|
||||
/newbot
|
||||
|
||||
BotFather:
|
||||
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
|
||||
|
||||
Umputun:
|
||||
example_comments
|
||||
|
||||
BotFather:
|
||||
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
|
||||
|
||||
Umputun:
|
||||
example_comments_bot
|
||||
|
||||
BotFather:
|
||||
Done! Congratulations on your new bot. You will find it at t.me/example_comments_bot. You can now add a description, about section and profile picture for your bot, see /help for a list of commands. By the way, when you've finished creating your cool bot, ping our Bot Support if you want a better username for it. Just make sure the bot is fully operational before you do this.
|
||||
|
||||
Use this token to access the HTTP API:
|
||||
12345678:xy778Iltzsdr45tg
|
||||
|
||||
For a description of the Bot API, see this page: https://core.telegram.org/bots/api
|
||||
```
|
||||
Additionally, you might want to set `NOTIFY_WEBHOOK_TEMPLATE` (which is Go Template, `{"text": "{{.Text}}"}` by default) and `NOTIFY_WEBHOOK_HEADERS`, which is HTTP header(s) in format `Header1:Value1,Header2:Value2,...`.
|
||||
|
||||
@@ -93,8 +93,8 @@ services:
|
||||
| notify.queue | NOTIFY_QUEUE | `100` | size of notification queue |
|
||||
| notify.telegram.chan | NOTIFY_TELEGRAM_CHAN | | ID of telegram channel for admin notifications |
|
||||
| notify.slack.token | NOTIFY_SLACK_TOKEN | | Slack token |
|
||||
| notify.slack.chan | NOTIFY_SLACK_CHAN | `general` | Slack channel |
|
||||
| notify.webhook.url | NOTIFY_WEBHOOK_URL | | Webhook notification URL |
|
||||
| notify.slack.chan | NOTIFY_SLACK_CHAN | `general` | Slack channel for admin notifications |
|
||||
| notify.webhook.url | NOTIFY_WEBHOOK_URL | | Webhook notification URL for admin notifications |
|
||||
| notify.webhook.template | NOTIFY_WEBHOOK_TEMPLATE | `{"text": "{{.Text}}"}` | Webhook payload template |
|
||||
| notify.webhook.headers | NOTIFY_WEBHOOK_HEADERS | | HTTP header in format Header1:Value1,Header2:Value2,...|
|
||||
| notify.webhook.timeout | NOTIFY_WEBHOOK_TIMEOUT | `5s` | Webhook connection timeout |
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Telegram
|
||||
---
|
||||
|
||||
You can enable Telegram for a user or admin [notifications](https://remark42.com/docs/configuration/notifications/) and user auth.
|
||||
|
||||
To set up notifications or auth with Telegram, first, you need to create a bot and write its access token to the remark42 configuration.
|
||||
|
||||
## Getting bot token for Telegram
|
||||
|
||||
To get a token, talk to [BotFather](https://core.telegram.org/bots#6-botfather). All you need is to send `/newbot` command and choose the name for your bot (it must end in `bot`). That is it, and you got a token which you'll need to write down into remark42 configuration as `TELEGRAM_TOKEN`.
|
||||
|
||||
_Example of such a "talk"_:
|
||||
|
||||
```
|
||||
Umputun:
|
||||
/newbot
|
||||
|
||||
BotFather:
|
||||
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
|
||||
|
||||
Umputun:
|
||||
example_comments
|
||||
|
||||
BotFather:
|
||||
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
|
||||
|
||||
Umputun:
|
||||
example_comments_bot
|
||||
|
||||
BotFather:
|
||||
Done! Congratulations on your new bot. You will find it at t.me/example_comments_bot. You can now add a description, about section and profile picture for your bot, see /help for a list of commands. By the way, when you've finished creating your cool bot, ping our Bot Support if you want a better username for it. Just make sure the bot is fully operational before you do this.
|
||||
|
||||
Use this token to access the HTTP API:
|
||||
12345678:xy778Iltzsdr45tg
|
||||
|
||||
For a description of the Bot API, see this page: https://core.telegram.org/bots/api
|
||||
```
|
||||
|
||||
## Auth
|
||||
|
||||
To enable Telegram authorization for the users, set variable `AUTH_TELEGRAM=true`.
|
||||
|
||||
## Notifications
|
||||
|
||||
### Notifications for administrators
|
||||
|
||||
To integrate notifications about any comment on your sites with remark42 with [Telegram](https://telegram.org)
|
||||
|
||||
1. Set `NOTIFY_ADMINS=telegram`
|
||||
1. Make [a channel](https://telegram.org/faq_channels) and add its ID to remark42 configuration as `NOTIFY_TELEGRAM_CHAN`
|
||||
* To obtain a public channel ID, forward any message from it to [@JsonDumpBot](https://t.me/JsonDumpBot): look for `id` in `forward_from_chat`.
|
||||
* If you want to use a private channel or chat, use [these instructions](https://github.com/GabrielRF/telegram-id) to obtain the ID.
|
||||
|
||||
### Notifications for users
|
||||
|
||||
**IMPORTANT: It doesn't work as of 20.12.2021, will be working after [this](https://github.com/umputun/remark42/issues/830) issue resolution** (waits for frontend support).
|
||||
|
||||
Enabling Telegram user notifications allows users to sign up for notifications about replies to their messages. To do it, set the variable `NOTIFY_USERS=telegram`.
|
||||
|
||||
### Technical details
|
||||
|
||||
Telegram notifications formatting is [limited](https://core.telegram.org/bots/api#html-style) by Telegram API and, because of that, lose most of the formatting of the original comment. Notification implementation of the remark42 backend takes the rendered HTML of the comment and strips it of the unsupported tags before sending it to Telegram.
|
||||
|
||||
The only way to improve the formatting of the messages would be to replace unsupported tags with supported ones, [like](https://github.com/umputun/remark42/issues/1202) `h1`-`h6` with `<b>`.
|
||||
@@ -27,13 +27,17 @@
|
||||
"title": "Authorization",
|
||||
"href": "/configuration/authorization/"
|
||||
},
|
||||
{
|
||||
"title": "Notifications",
|
||||
"href": "/configuration/notifications/"
|
||||
},
|
||||
{
|
||||
"title": "Email",
|
||||
"href": "/configuration/email/"
|
||||
},
|
||||
{
|
||||
"title": "Notifications",
|
||||
"href": "/configuration/notifications/"
|
||||
"title": "Telegram",
|
||||
"href": "/configuration/telegram/"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user