A package to send messages to Microsoft Teams (channels)

• Project home
• Overview
• Features
• Project Status
  • Now
  • Past
  • Future
• Changelog
• Usage
  • Add this project as a dependency
  • Webhook URLs
    • Expected format
    • How to create a webhook URL (Connector)
  • Example: Basic
  • Example: Disable webhook URL prefix validation
• References

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

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 with complex messages supporting multiple sections, key/value pairs (aka, Facts) and/or externally hosted images.

• 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)
• Submit messages to Microsoft Teams

This fork is now a standalone project.

This project should be considered to be in "maintenance" mode. Further contributions and but fixes are welcome, but the overall cadence and priority is likely to be lower in comparison to other projects that I maintain. 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.

1. Initial release up to and including v2.1.0
   • The last upstream project release.
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 onward
   • I merged vendored local changes from another project that I maintain, atc0005/send2teams.

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.

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.

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.

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:

• https://outlook.office.com/webhook/a1269812-6d10-44b1-abc5-b84f93580ba0@9e7b80c7-d1eb-4b52-8582-76f921e416d9/IncomingWebhook/3fdd6767bae44ac58e5995547d66a4e4/f332c8d9-3397-4ac5-957b-b8e3fc465a8c
• https://outlook.office365.com/webhook/a1269812-6d10-44b1-abc5-b84f93580ba0@9e7b80c7-d1eb-4b52-8582-76f921e416d9/IncomingWebhook/3fdd6767bae44ac58e5995547d66a4e4/f332c8d9-3397-4ac5-957b-b8e3fc465a8c
• https://example.webhook.office.com/webhookb2/a1269812-6d10-44b1-abc5-b84f93580ba0@9e7b80c7-d1eb-4b52-8582-76f921e416d9/IncomingWebhook/3fdd6767bae44ac58e5995547d66a4e4/f332c8d9-3397-4ac5-957b-b8e3fc465a8c
  • note the webhookb2 sub-URI specific to this FQDN pattern

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.

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

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

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

• Original project

• Forks of original project

• Microsoft Teams

  • MS Teams - adaptive cards (de-de, en-us)
  • MS Teams - send via connectors (de-de, en-us)
  • adaptivecards.io

• Related projects

  • https://github.com/atc0005/send2teams
  • https://github.com/atc0005/bounce
  • https://github.com/atc0005/brick