/go-teams-notify

A package to send messages to Microsoft Teams (channels)

Primary LanguageGoMIT LicenseMIT

go-teams-notify

A package to send messages to Microsoft Teams (channels)

Latest release Go Reference License Validate Codebase Validate Docs Lint and Build using Makefile Quick Validation

Table of contents

Project home

See our GitHub repo for the latest code, to file an issue or submit improvements for review and potential inclusion into the project.

Overview

The goteamsnotify package (aka, go-teams-notify) allows sending simple or complex messages to a Microsoft Teams channel.

Simple messages can be composed of only a title and a text body. More complex messages can be composed of multiple sections, key/value pairs (aka, Facts) and/or externally hosted images.

Features

  • Generate simple or complex messages
    • simple messages consist of only a title and a text body (one or more strings)
    • complex messages consist of one or more sections, key/value pairs (aka, Facts) and/or externally hosted images. or images (hosted externally)
  • Configurable validation of webhook URLs
    • enabled by default, attempts to match most common known webhook URL patterns
    • option to disable validation entirely
    • option to use custom validation patterns
  • Configurable validation of MessageCard type
    • default assertion that bare-minimum required fields are present
    • support for providing a custom validation function to override default validation behavior
  • Configurable timeouts
  • Configurable retry support
  • Submit messages to Microsoft Teams

Project Status

Now

This fork is now a standalone project.

This project should be considered in "maintenance" mode. Further contributions and bug fixes are welcome, but the overall cadence and priority is likely to be lower in comparison to other projects that I maintain. That said, I plan to apply bugfixes, maintain dependencies and make improvements as warranted to meet the needs of dependent projects.

With work having stalled on the upstream project, others have also taken an interest in maintaining their own forks of the parent project codebase. See those forks for other ideas/changes that you may find useful.

History

  1. Initial release up to and including v2.1.0
  2. v2.1.1
    • Further attempts to reach the upstream project maintainer failed.
    • I promoted my PR-only fork into a standalone project.
    • The first release from this project since diverging from upstream.
  3. v2.2.0
    • I merged vendored local changes from another project that I maintain, atc0005/send2teams.

For more recent changes, see the Releases section or our Changelog.

Future

I hope to eventually collapse this project and merge all changes back into the upstream project. As of early 2021 however, I've still not heard back from the upstream project maintainer, so this does not look to be the case any time soon. In the meantime, I plan to continue maintaining this fork and making changes as needed to support dependent projects.

Changelog

See the CHANGELOG.md file for the changes associated with each release of this application. Changes that have been merged to master, but not yet an official release may also be noted in the file under the Unreleased section. A helpful link to the Git commit history since the last official release is also provided for further review.

Usage

Add this project as a dependency

Assuming that you're using Go Modules, add this line to your imports like so:

import "github.com/atc0005/go-teams-notify/v2"

Your editor will likely resolve the import and update your go.mod and go.sum files accordingly. If not, read the official Go Modules blog post on the topic for further information.

Webhook URLs

Expected format

Valid webhook URLs for Microsoft Teams use one of several (confirmed) FQDNs patterns:

  • outlook.office.com
  • outlook.office365.com
  • *.webhook.office.com
    • e.g., example.webhook.office.com

Using a webhook URL with any of these FQDN patterns appears to give identical results.

Here are complete, equivalent example webhook URLs from Microsoft's documentation using the FQDNs above:

All of these patterns when provided to this library should pass the default validation applied. See the example further down for the option of disabling webhook URL validation entirely.

How to create a webhook URL (Connector)

  1. Open Microsoft Teams
  2. Navigate to the channel where you wish to receive incoming messages from this application
  3. Select ⋯ next to the channel name and then choose Connectors.
  4. Scroll through the list of Connectors to Incoming Webhook, and choose Add.
  5. Enter a name for the webhook, upload an image to associate with data from the webhook, and choose Create.
  6. Copy the webhook URL to the clipboard and save it. You'll need the webhook URL for sending information to Microsoft Teams.
    • NOTE: While you can create another easily enough, you should treat this webhook URL as sensitive information as anyone with this unique URL is able to send messages (without authentication) into the associated channel.
  7. Choose Done.

Credit: docs.microsoft.com, gist comment from shadabacc3934

Example: Basic

Here is an example of a simple client application which uses this library:

import (
  "github.com/atc0005/go-teams-notify/v2"
)

func main() {
  _ = sendTheMessage()
}

func sendTheMessage() error {
  // init the client
  mstClient := goteamsnotify.NewClient()

  // setup webhook url
  webhookUrl := "https://outlook.office.com/webhook/YOUR_WEBHOOK_URL_OF_TEAMS_CHANNEL"

  // setup message card
  msgCard := goteamsnotify.NewMessageCard()
  msgCard.Title = "Hello world"
  msgCard.Text = "Here are some examples of formatted stuff like "+
      "<br> * this list itself  <br> * **bold** <br> * *italic* <br> * ***bolditalic***"
  msgCard.ThemeColor = "#DF813D"

  // send
  return mstClient.Send(webhookUrl, msgCard)
}

Of note:

  • default timeout
  • package-level logging is disabled by default
  • validation of known webhook URL prefixes is enabled
  • simple message submitted to Microsoft Teams consisting of formatted body and title

Example: Disable webhook URL prefix validation

This example disables the validation webhook URLs, including the validation of known prefixes so that custom/private webhook URL endpoints can be used (e.g., testing purposes).

import (
  "github.com/atc0005/go-teams-notify/v2"
)

func main() {
  _ = sendTheMessage()
}

func sendTheMessage() error {
  // init the client
  mstClient := goteamsnotify.NewClient()

  // setup webhook url
  webhookUrl := "https://example.webhook.office.com/webhook/YOUR_WEBHOOK_URL_OF_TEAMS_CHANNEL"

  // Disable webhook URL validation
  mstClient.SkipWebhookURLValidationOnSend(true)

  // setup message card
  msgCard := goteamsnotify.NewMessageCard()
  msgCard.Title = "Hello world"
  msgCard.Text = "Here are some examples of formatted stuff like "+
      "<br> * this list itself  <br> * **bold** <br> * *italic* <br> * ***bolditalic***"
  msgCard.ThemeColor = "#DF813D"

  // send
  return mstClient.Send(webhookUrl, msgCard)
}

Of note:

  • webhook URL validation is disabled
    • allows use of custom/private webhook URL endpoints
  • other settings are the same as the basic example previously listed

Example: Enable custom patterns' validation

This example demonstrates how to enable custom validation patterns for webhook URLs.

import (
  "github.com/atc0005/go-teams-notify/v2"
)

func main() {
  _ = sendTheMessage()
}

func sendTheMessage() error {
  // init the client
  mstClient := goteamsnotify.NewClient()

  // setup webhook url
  webhookUrl := "https://my.domain.com/webhook/YOUR_WEBHOOK_URL_OF_TEAMS_CHANNEL"

  // Add a custom pattern for webhook URL validation
  mstClient.AddWebhookURLValidationPatterns(`^https://.*\.domain\.com/.*$`)
  // It's also possible to use multiple patterns with one call
  // mstClient.AddWebhookURLValidationPatterns(`^https://arbitrary\.example\.com/webhook/.*$`, `^https://.*\.domain\.com/.*$`)
  // To keep the default behavior and add a custom one, use something like the following:
  // mstClient.AddWebhookURLValidationPatterns(DefaultWebhookURLValidationPattern, `^https://.*\.domain\.com/.*$`)

  // setup message card
  msgCard := goteamsnotify.NewMessageCard()
  msgCard.Title = "Hello world"
  msgCard.Text = "Here are some examples of formatted stuff like "+
      "<br> * this list itself  <br> * **bold** <br> * *italic* <br> * ***bolditalic***"
  msgCard.ThemeColor = "#DF813D"

  // send
  return mstClient.Send(webhookUrl, msgCard)
}

Of note:

  • webhook URL validation uses custom pattern
    • allows use of custom/private webhook URL endpoints
  • other settings are the same as the basic example previously listed

Used by

This library is used by the following projects.

See the Known importers lists below for a dynamically updated list of projects using either this library or the original project.

  • original project
  • this fork

References