notify

README

A dead simple Go library for sending notifications to various messaging services.

[!NOTE] [July 2024 Update]: Notify is back under active maintenance! Read the full announcement here.

About

Notify was born out of my own need to have my API servers running in production be able to notify me when critical errors occur. Of course, Notify can be used for any other purpose as well. The library is kept as simple as possible for quick integration and ease of use.

Disclaimer

Any misuse of this library is your own liability and responsibility and cannot be attributed to the authors of this library. See license for more.

Spamming through the use of this library may get you permanently banned on most supported platforms.

Since Notify is highly dependent on the consistency of the supported external services and the corresponding latest client libraries, we cannot guarantee its reliability nor its consistency, and therefore you should probably not use or rely on Notify in critical scenarios.

Install

go get -u github.com/nikoksr/notify

Example usage

// Create a telegram service. Ignoring error for demo simplicity.
telegramService, _ := telegram.New("your_telegram_api_token")

// Passing a telegram chat id as receiver for our messages.
// Basically where should our message be sent?
telegramService.AddReceivers(-1234567890)

// Tell our notifier to use the telegram service. You can repeat the above process
// for as many services as you like and just tell the notifier to use them.
// Inspired by http middlewares used in higher level libraries.
notify.UseServices(telegramService)

// Send a test message.
_ = notify.Send(
	context.Background(),
	"Subject/Title",
	"The actual message - Hello, you awesome gophers! :)",
)

Recommendation

In this example, we use the global Send() function. Similar to most logging libraries such as zap, we provide global functions for convenience. However, as with most logging libraries, we also recommend avoiding the use of global functions as much as possible. Instead, use one of our versatile constructor functions to create a new local Notify instance and pass it down the stream.

Contributing

Yes, please! Contributions of all kinds are very welcome! Feel free to check our open issues. Please also take a look at the contribution guidelines.

Psst, don't forget to check the list of missing services waiting to be added by you or create a new issue if you want a new service to be added.

Supported services

Click here to request a missing service.

Service	Path	Credits	Status
Amazon SES	service/amazonses	aws/aws-sdk-go-v2	✔
Amazon SNS	service/amazonsns	aws/aws-sdk-go-v2	✔
Bark	service/bark	-	✔
DingTalk	service/dinding	blinkbean/dingtalk	✔
Discord	service/discord	bwmarrin/discordgo	✔
Email	service/mail	jordan-wright/email	✔
Firebase Cloud Messaging	service/fcm	appleboy/go-fcm	✔
Google Chat	service/googlechat	googleapis/google-api-go-client	✔
HTTP	service/http	-	✔
Lark	service/lark	go-lark/lark	✔
Line	service/line	line/line-bot-sdk-go	✔
Line Notify	service/line	utahta/go-linenotify	✔
Mailgun	service/mailgun	mailgun/mailgun-go	✔
Matrix	service/matrix	mautrix/go	✔
Microsoft Teams	service/msteams	atc0005/go-teams-notify	✔
Plivo	service/plivo	plivo/plivo-go	✔
Pushover	service/pushover	gregdel/pushover	✔
Pushbullet	service/pushbullet	cschomburg/go-pushbullet	✔
Reddit	service/reddit	vartanbeno/go-reddit	✔
RocketChat	service/rocketchat	RocketChat/Rocket.Chat.Go.SDK	✔
SendGrid	service/sendgrid	sendgrid/sendgrid-go	✔
Slack	service/slack	slack-go/slack	✔
Syslog	service/syslog	log/syslog	✔
Telegram	service/telegram	go-telegram-bot-api/telegram-bot-api	✔
TextMagic	service/textmagic	textmagic/textmagic-rest-go-v2	✔
Twilio	service/twilio	kevinburke/twilio-go	✔
Twitter	service/twitter	drswork/go-twitter	✔
Viber	service/viber	mileusna/viber	✔
WeChat	service/wechat	silenceper/wechat	✔
Webpush Notification	service/webpush	SherClockHolmes/webpush-go	✔
WhatsApp	service/whatsapp	Rhymen/go-whatsapp	❌

Special Thanks

Maintainers

• @svaloumas

Logo

The logo was made by the amazing MariaLetta.

Support

If you find this project useful, consider giving it a ⭐️! Your support helps bring more attention to the project, allowing us to enhance it even further.

While you're here, feel free to check out my other work:

• nikoksr/konfetty - Zero-dependency, type-safe and powerful post-processing for your existing config solution in Go.

Documentation

Index

• Constants
• Variables
• func Disable(n *Notify)
• func Enable(n *Notify)
• func Send(ctx context.Context, subject, message string) error
• func UseServices(services ...Notifier)
• type Notifier
• type Notify
  • func Default() *Notify
  • func New() *Notify
  • func NewWithOptions(options ...Option) *Notify
  • func NewWithServices(services ...Notifier) *Notify
  • func (n *Notify) Send(ctx context.Context, subject, message string) error
  • func (n *Notify) UseServices(services ...Notifier)
  • func (n *Notify) WithOptions(options ...Option) *Notify
• type Option

Constants

const Version = "unknown"

Version is the current version of the library.

Variables

var ErrSendNotification = errors.New("send notification")

ErrSendNotification signals that the notifier failed to send a notification.

Functions

func Disable

func Disable(n *Notify)

Disable is an Option function that disables the Notify instance. It is enabled by default.

func Enable

func Enable(n *Notify)

Enable is an Option function that enables the Notify instance. This is the default behavior.

func Send

func Send(ctx context.Context, subject, message string) error

Send calls the underlying notification services to send the given subject and message to their respective endpoints.

func UseServices

func UseServices(services ...Notifier)

UseServices adds the given service(s) to the Notifier's services list.

Types

type Notifier

type Notifier interface {
	Send(context.Context, string, string) error
}

Notifier defines the behavior for notification services.

The Send function simply sends a subject and a message string to the internal destination Notifier.

E.g. for telegram.Telegram it sends the message to the specified group chat.

type Notify

type Notify struct {
	Disabled bool
	// contains filtered or unexported fields
}

Notify is the central struct for managing notification services and sending messages to them.

func Default

func Default() *Notify

Default returns the standard Notify instance used by the package-level send function.

func New

func New() *Notify

New returns a new instance of Notify. It returns a new Notify instance with default options. By default, the Notify instance is enabled.

func NewWithOptions

func NewWithOptions(options ...Option) *Notify

NewWithOptions returns a new instance of Notify with the given options. If no options are provided, it returns a new Notify instance with default options. By default, the Notify instance is enabled.

func NewWithServices

func NewWithServices(services ...Notifier) *Notify

NewWithServices returns a new instance of Notify with the given services. By default, the Notify instance is enabled. If no services are provided, it returns a new Notify instance with default options.

func (*Notify) Send

func (n *Notify) Send(ctx context.Context, subject, message string) error

Send calls the underlying notification services to send the given subject and message to their respective endpoints.

func (*Notify) UseServices

func (n *Notify) UseServices(services ...Notifier)

UseServices adds the given service(s) to the Notifier's services list.

func (*Notify) WithOptions

func (n *Notify) WithOptions(options ...Option) *Notify

WithOptions applies the given options to the Notify instance. If no options are provided, it returns the Notify instance unchanged.

type Option

type Option func(*Notify)

Option is a function that can be used to configure a Notify instance. It is used by the WithOptions and NewWithOptions functions. It's a function because it's a bit more flexible than using a struct. The only required parameter is the Notify instance itself.