README
¶
Notify
This library provides ability to send notifications using multiple services:
- Telegram
- Slack
- Webhook
Install
go get -u github.com/go-pkgz/notify
Usage
All supported notification methods could adhere to the following interface. Example on how to use it:
package main
import (
"context"
"fmt"
"github.com/go-pkgz/notify"
)
func main() {
// create notifiers
notifiers := []notify.Notifier{
notify.NewWebhook(notify.WebhookParams{}),
notify.NewEmail(notify.SMTPParams{}),
notify.NewSlack("token"),
}
tg, err := notify.NewTelegram(notify.TelegramParams{Token: "token"})
if err == nil {
notifiers = append(notifiers, tg)
}
err = notify.Send(context.Background(), notifiers, "https://example.com/webhook", "Hello, world!")
if err != nil {
fmt.Printf("Sent message error: %s", err))
}
}
mailto: scheme is supported. Only subject and from query params are used.
Examples:
mailto:"John Wayne"<john@example.org>?subject=test-subj&from="Notifier"<notify@example.org>mailto:addr1@example.org,addr2@example.org?&subject=test-subj&from=notify@example.org
package main
import (
"context"
"log"
"time"
"github.com/go-pkgz/notify"
)
func main() {
wh := notify.NewEmail(notify.SMTPParams{
Host: "localhost", // the only required field, others are optional
Port: 25,
TLS: false, // TLS, but not STARTTLS
ContentType: "text/html",
Charset: "UTF-8",
Username: "username",
Password: "password",
TimeOut: time.Second * 10, // default is 30 seconds
})
err := wh.Send(
context.Background(),
`mailto:"John Wayne"<john@example.org>?subject=test-subj&from="Notifier"<notify@example.org>`,
"Hello, World!",
)
if err != nil {
log.Fatalf("problem sending message using email, %v", err)
}
}
Telegram
telegram: scheme akin to mailto: is supported. Query params parseMode (doc, legacy Markdown by default, preferable use MarkdownV2 or HTML instead). Examples:
telegram:channeltelegram:channelID// channel ID is a number, like-1001480738202: use that instruction to obtain ittelegram:userID
Here is an instruction on obtaining token for your notification bot.
package main
import (
"context"
"log"
"time"
"github.com/go-pkgz/notify"
)
func main() {
tg, err := notify.NewTelegram(notify.TelegramParams{
Token: "token", // required
Timeout: time.Second * 10, // default is 5 seconds
SuccessMsg: "Success", // optional, for auth, set by default
ErrorMsg: "Error", // optional, for auth, unset by default
})
err = tg.Send(context.Background(), "telegram:-1001480738202", "Hello, World!")
if err != nil {
log.Fatalf("problem sending message using telegram, %v", err)
}
}
HTML Formatting
parseMode HTML supports limited set of tags, so Telegram provides TelegramSupportedHTML method which strips all unsupported tags and replaces h1-h3 with <b> and h4-h6 with <i><b> to preserve formatting.
If you want to post text into HTML tag like text, you can use EscapeTelegramText method to escape it (by replacing symbols &, <, > with &, <, >).
Authorisation
You can use Telegram notifications as described above, just to send messages. But also, you can use Telegram to authorise users as a login method or to sign them up for notifications. Functions used for processing updates from users are GetBotUsername, AddToken, CheckToken, Request, and Run or ProcessUpdate (only one of two can be used at a time).
Normal flow is following:
- you run the
Rungoroutine - call
AddTokenand provide user with that token - user clicks on the link
https://t.me/<BOT_USERNAME>/?start=<TOKEN> - you call
CheckTokento verify that the user clicked the link, and if so you will receive user's UserID
Alternative flow is the same, but instead of running the Run goroutine, you set up process update flow separately (to use with auth as well, for example) and run ProcessUpdate when update is received. Example of such a setup can be seen in Remark42.
Slack
slack: scheme akin to mailto: is supported. title, titleLink, attachmentText and query params are used: if they are defined, message would be sent with a text attachment. Examples:
slack:channelslack:channelIDslack:userIDslack:channel?title=title&attachmentText=test%20text&titleLink=https://example.org
package main
import (
"context"
"log"
"github.com/go-pkgz/notify"
"github.com/slack-go/slack"
)
func main() {
wh := notify.NewSlack(
"token",
slack.OptionDebug(true), // optional, you can pass any slack.Options
)
err := wh.Send(context.Background(), "slack:general", "Hello, World!")
if err != nil {
log.Fatalf("problem sending message using slack, %v", err)
}
}
Webhook
http:// and https:// schemas are supported.
package main
import (
"context"
"log"
"time"
"github.com/go-pkgz/notify"
)
func main() {
wh := notify.NewWebhook(notify.WebhookParams{
Timeout: time.Second, // optional, default is 5 seconds
Headers: []string{"Content-Type:application/json,text/plain"}, // optional
})
err := wh.Send(context.Background(), "https://example.org/webhook", "Hello, World!")
if err != nil {
log.Fatalf("problem sending message using webhook, %v", err)
}
}
Status
The library extracted from remark42 project. The original code in production use on multiple sites and seems to work fine.
go-pkgz/notify library still in development and until version 1 released some breaking changes possible.
Documentation
¶
Overview ¶
Package notify provides notification functionality.
Index ¶
- func EscapeTelegramText(text string) string
- func Send(ctx context.Context, notifiers []Notifier, destination, text string) error
- func TelegramSupportedHTML(htmlText string) string
- type Email
- type Notifier
- type SMTPParams
- type Slack
- type Telegram
- func (t *Telegram) AddToken(token, user, site string, expires time.Time)
- func (t *Telegram) CheckToken(token, user string) (telegram, site string, err error)
- func (t *Telegram) GetBotUsername() string
- func (t *Telegram) ProcessUpdate(ctx context.Context, textUpdate string) error
- func (t *Telegram) Request(ctx context.Context, method string, b []byte, data interface{}) error
- func (t *Telegram) Run(ctx context.Context)
- func (t *Telegram) Schema() string
- func (t *Telegram) Send(ctx context.Context, destination, text string) error
- func (t *Telegram) String() string
- type TelegramBotInfo
- type TelegramParams
- type TelegramUpdate
- type Webhook
- type WebhookParams
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EscapeTelegramText ¶
EscapeTelegramText returns text sanitized of symbols not allowed inside other HTML tags in Telegram HTML message payload
func Send ¶
Send sends message to provided destination, picking the right one based on destination schema
func TelegramSupportedHTML ¶
TelegramSupportedHTML returns HTML with only tags allowed in Telegram HTML message payload, also trims ending newlines
Types ¶
type Email ¶
type Email struct {
SMTPParams
// contains filtered or unexported fields
}
Email notifications client
func (*Email) Send ¶
Send sends the message over Email, with "from", "subject" and "unsubscribeLink" parsed from destination field with "mailto:" schema. "unsubscribeLink" passed as a header, https://support.google.com/mail/answer/81126 -> "Use one-click unsubscribe"
Example:
- mailto:"John Wayne"<john@example.org>?subject=test-subj&from="Notifier"<notify@example.org> - mailto:addr1@example.org,addr2@example.org?subject=test-subj&from=notify@example.org&unsubscribeLink=http://example.org/unsubscribe
type Notifier ¶
type Notifier interface {
fmt.Stringer
Schema() string // returns schema prefix supported by this client
Send(ctx context.Context, destination, text string) error // sends message to provided destination
}
Notifier defines common interface among all notifiers
type SMTPParams ¶
type SMTPParams struct {
Host string // SMTP host
Port int // SMTP port
TLS bool // TLS auth
StartTLS bool // StartTLS auth
InsecureSkipVerify bool // skip certificate verification
ContentType string // Content type
Charset string // Character set
LoginAuth bool // LOGIN auth method instead of default PLAIN, needed for Office 365 and outlook.com
Username string // username
Password string // password
TimeOut time.Duration // TCP connection timeout
}
SMTPParams contain settings for smtp server connection
type Slack ¶
type Slack struct {
// contains filtered or unexported fields
}
Slack notifications client
func (*Slack) Send ¶
Send sends the message over Slack, with "title", "titleLink" and "attachmentText" parsed from destination field with "slack:" schema same way "mailto:" schema is constructed.
Example:
- slack:channelName - slack:channelID - slack:userID - slack:channel?title=title&attachmentText=test%20text&titleLink=https://example.org
type Telegram ¶
type Telegram struct {
TelegramParams
// contains filtered or unexported fields
}
Telegram notifications client
func NewTelegram ¶
func NewTelegram(params TelegramParams) (*Telegram, error)
NewTelegram makes telegram bot for notifications
func (*Telegram) CheckToken ¶
CheckToken verifies incoming token, returns the user address if it's confirmed and empty string otherwise
func (*Telegram) GetBotUsername ¶
GetBotUsername returns bot username
func (*Telegram) ProcessUpdate ¶
ProcessUpdate is alternative to Run, it processes provided plain text update from Telegram so that caller could get updates and send it not only there but to multiple sources
func (*Telegram) Run ¶
Run starts processing login requests sent in Telegram, required for user notifications to work Blocks caller
func (*Telegram) Send ¶
Send sends provided message to Telegram chat, with `parseMode` parsed from destination field (Markdown by default) with "telegram:" schema same way "mailto:" schema is constructed.
Example:
- telegram:channel - telegram:chatID // chatID is a number, like `-1001480738202` - telegram:channel?parseMode=HTML
type TelegramBotInfo ¶
type TelegramBotInfo struct {
Username string `json:"username"`
}
TelegramBotInfo structure contains information about telegram bot, which is used from whole telegram API response
type TelegramParams ¶
type TelegramParams struct {
Token string // token for telegram bot API interactions
Timeout time.Duration // http client timeout
ErrorMsg, SuccessMsg string // messages for successful and unsuccessful subscription requests to bot
// contains filtered or unexported fields
}
TelegramParams contain settings for telegram notifications
type TelegramUpdate ¶
type TelegramUpdate struct {
Result []struct {
UpdateID int `json:"update_id"`
Message struct {
Chat struct {
ID int `json:"id"`
Name string `json:"first_name"`
Type string `json:"type"`
} `json:"chat"`
Text string `json:"text"`
} `json:"message"`
} `json:"result"`
}
TelegramUpdate contains update information, which is used from whole telegram API response
type Webhook ¶
type Webhook struct {
WebhookParams
// contains filtered or unexported fields
}
Webhook notifications client
type WebhookParams ¶
type WebhookParams struct {
Timeout time.Duration
Headers []string // headers in format "header:value"
}
WebhookParams contain settings for webhook notifications
Source Files