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

Notify v2

This is the home branch of Notify v2. It is currently in active development and not yet ready for production use. The main branch will stay the default branch until v2 is ready for production use. At this point, the main branch will be renamed to v1 and the v2 branch will be merged into the main branch.

Notify v2 lets you enjoy the simplicity of Notify v1 with more power and flexibility at your hands. Providing a simple interface that lets you send attachments, define custom message renderers and dynamic message enrichment.

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

Usage of this library should comply with the stated rules and the terms present in the license and code of conduct. Failure to comply, including but not limited to misuse or spamming, can result in permanent banning from all supported platforms as governed by the respective platform's rules and regulations.

Notify's functionality is determined by the consistency of the supported external services and their corresponding latest client libraries; it may change without notice. This fact, coupled with the inevitable inconsistencies that can arise, dictates that Notify should not be used in situations where its failure or inconsistency could result in significant damage, loss, or disruption. Always have a backup plan and only use Notify after understanding and accepting these conditions.

Please read the license for a complete understanding of the permissions, conditions, and limitations of use.

Install

go get -u github.com/nikoksr/notify/v2

Example usage

You can use Notify just like you're used to from v1. A simple example in which we send a notification to a Telegram channel could look like this:

func main() {
    // Create a new telegram service. We're using the new constructor option WithRecipients() to specify the recipients. We can,
    // however, also rely on the old way of doing things and add the recipients to the service later on using the AddRecipients()
    // method.
    svc, _ := telegram.New(token,
        telegram.WithRecipients(recipient),
    )

	// Create the actual notify instance and pass the telegram service to it. Again, we're making use of the new constructor
	// option WithServices() to specify the services. UseServices() is still available and can be used to add services later
	// on.
    dispatcher := notify.New(
        notify.WithServices(svc),
    )

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

We touched a little bit on what's new in v2 in the example above. Let's take a deeper dive into the new, more advanced features.

In this example, we're going to send a notification to a Discord channel. We're going to make use of the new discord.Webhook service, which allows us to send notifications to Discord webhooks. We're also going to define a custom message renderer, which allows us to define how the message should look like. Lastly, we're going to send a couple of attachments and metadata along with the notification.

func main() {
    // Create a new discord webhook service.
    svc, _ := discord.NewWebhook(
        discord.WithRecipients(webhookURL),
        discord.WithMessageRenderer(customRenderer),
    )

	// Open a couple of files to send as attachments.
    img, _ := os.Open("/path/to/image.png")
	defer img.Close()

    txt, _ := os.Open("/path/to/text.txt")
	defer txt.Close()

	// Create some example metadata that we make use of in our custom renderer.
    exampleMetadata := map[string]interface{}{
        "foo":  "bar",
    }

	// Send a notification with the attachments and metadata. In this case, we're using the service directly.
    _ = svc.Send(ctx,
        "[Test] Notify v2",
        "Hello, you awesome gophers! :)",
        notify.SendWithAttachments(img, txt),
        notify.SendWithMetadata(exampleMetadata),
    )
}


// The custom renderer allows us to define how the message should look like. The respective SendConfig is passed to the
// renderer, which contains all the information we need to render the message.
func customRenderer(conf discord.SendConfig) string {
    var builder strings.Builder

	// For demo purposes, we're just going to marshal the metadata to human-readable JSON and add it to the message.
    metadata, _ := json.MarshalIndent(conf.Metadata(), "", "  ")

	// Put together the message.
    builder.WriteString(conf.Subject())
    builder.WriteString("\n\n")
    builder.WriteString(conf.Message())
    builder.WriteString("\n\n")
	builder.WriteString("Metadata:\n")
	builder.WriteString(string(metadata))
	builder.WriteString("\n\n")
    builder.WriteString("<-- A super necessary footer -->\n")

    return builder.String()
}

Also note that we're using a Dispatcher in the first example, which allows us to send notifications to multiple services at once. In the second example, we're using a Service directly, which only allows us to send notifications to a single service.

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.

Special Thanks

Maintainers

• @svaloumas

Logo

The logo was made by the amazing MariaLetta.

Similar projects

Just to clarify, Notify was not inspired by any other project. I created it as a tiny subpackage of a larger project and only later decided to make it a standalone project. In this section I just want to mention other great projects.

• containrrr/shoutrrr
• caronc/apprise

Show your support

Please give a ⭐️ if you like the project! It draws more attention to the project, which helps us improve it even faster.