Skip to content

atc0005/send2teams

BranchesTags

Repository files navigation

send2teams

Small CLI tool used to submit messages to Microsoft Teams.

Latest Release Go Reference go.mod Go version Lint and Build Project Analysis

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

First of all, many thanks to the developer/contributors of the original dasrick/go-teams-notify package. While this project now uses a fork of that original project, this project would likely not have been possible without the efforts of the original developer.

This project provides:

  • send2teams
    • Small CLI tool used to submit messages to Microsoft Teams. send2teams is intended for use by Nagios, scripts or other actions that may need to submit pass/fail results to a MS Teams channel.

Prior to v0.4.7 this project also provided a teams subpackage. All of that functionality has since been migrated to the atc0005/go-teams-notify project. All client code for that package has been updated to use atc0005/go-teams-notify in place of the previous teams subpackage of this project.

Features

  • single binary, no outside dependencies
  • minimal configuration
  • very few build dependencies
  • optional conversion of messages with Windows, Mac or Linux newlines to increase compatibility with Teams formatting
  • message delivery retry support with retry and retry delay values configurable via flag
  • support for user mentions
  • optional support for noting a sending application as the source of the message
  • optional support for specifying target url, description comma-separated pairs for use as labelled "buttons" within a Microsoft Teams message
  • optional support for omitting the "branding" trailer from generated messages

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.

Requirements

The following is a loose guideline. Other combinations of Go and operating systems for building and running tools from this repo may work, but have not been tested.

Building source code

  • Go
    • see this project's go.mod file for preferred version
    • this project tests against officially supported Go releases
      • the most recent stable release (aka, "stable")
      • the prior, but still supported release (aka, "oldstable")
  • GCC
    • if building with custom options (as the provided Makefile does)
  • make
    • if using the provided Makefile

Running

  • Windows 10
  • Ubuntu Linux 18.04+

How to install it

From source

  1. Download Go
  2. Install Go
    • NOTE: Pay special attention to the remarks about $HOME/.profile
  3. Clone the repo
    1. cd /tmp
    2. git clone https://github.com/atc0005/send2teams
    3. cd send2teams
  4. Install dependencies (optional)
    • for Ubuntu Linux
      • sudo apt-get install make gcc
    • for CentOS Linux
      1. sudo yum install make gcc
  5. Build
    • for current operating system
      • go build -mod=vendor ./cmd/send2teams/
        • forces build to use bundled dependencies in top-level vendor folder
    • for all supported platforms (where make is installed)
      • make all
    • for Windows
      • make windows
    • for Linux
      • make linux
  6. Copy the applicable binary to whatever systems needs to run it
    • if using Makefile: look in /tmp/release_assets/send2teams/
    • if using go build: look in /tmp/send2teams/

NOTE: Depending on which Makefile recipe you use the generated binary may be compressed and have an xz extension. If so, you should decompress the binary first before deploying it (e.g., xz -d send2teams-linux-amd64.xz).

Using release binaries

  1. Download the latest release binaries
  2. Decompress binaries
    • e.g., xz -d send2teams-linux-amd64.xz
  3. Deploy
    • Place send2teams in a location of your choice
      • e.g., /usr/local/bin/send2teams

NOTE:

DEB and RPM packages are provided as an alternative to manually deploying binaries.

Configuration Options

Setup a connection to Microsoft Teams

Overview

Warning

Microsoft announced July 3rd, 2024 that Office 365 (O365) connectors within Microsoft Teams would be retired in 3 months and replaced by Power Automate workflows (or just "Workflows" for short).

Quoting from the microsoft365dev blog:

We will gradually roll out this change in waves:

  • Wave 1 - effective August 15th, 2024: All new Connector creation will be blocked within all clouds
  • Wave 2 - effective October 1st, 2024: All connectors within all clouds will stop working

Microsoft later changed some of the details regarding the retirement timeline of O365 connectors:

Update 07/23/2024: We understand and appreciate the feedback that customers have shared with us regarding the timeline provided for the migration from Office 365 connectors. We have extended the retirement timeline through December 2025 to provide ample time to migrate to another solution such as Power Automate, an app within Microsoft Teams, or Microsoft Graph. Please see below for more information about the extension:

  • All existing connectors within all clouds will continue to work until December 2025, however using connectors beyond December 31, 2024 will require additional action.
    • Connector owners will be required to update the respective URL to post by December 31st, 2024. At least 90 days prior to the December 31, 2024 deadline, we will send further guidance about making this URL update. If the URL is not updated by December 31, 2024 the connector will stop working. This is due to further service hardening updates being implemented for Office 365 connectors in alignment with Microsoft's Secure Future Initiative
  • Starting August 15th, 2024 all new creations should be created using the Workflows app in Microsoft Teams

Since O365 connectors will likely persist in many environments until the very end of the deprecation period this project will continue to support them until then alongside Power Automate workflows.

Workflow connectors

Workflow webhook URL format

Valid Power Automate Workflow URLs used to submit messages to Microsoft Teams use this format:

  • https://*.logic.azure.com:443/workflows/GUID_HERE/triggers/manual/paths/invoke?api-version=YYYY-MM-DD&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=SIGNATURE_HERE

Example URL from the LinkedIn Bring Microsoft Teams incoming webhook security to the next level with Azure Logic App article:

  • https://webhook-jenkins.azure-api.net/manual/paths/invoke?api-version=2016-10-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=f2QjZY50uoRnX6PIpyPT3xk
How to create a Workflow connector webhook URL

Tip

Use a dedicated "service" account not tied to a specific team member to help ensure that the Workflow connector is long lived.

The initial O365 retirement blog post provides a list of templates which guide you through the process of creating a Power Automate Workflow webhook URL.

Using Teams client Workflows context option
  1. Navigate to a channel or chat
  2. Select the ellipsis on the channel or chat
  3. Select Workflows
  4. Type when a webhook request
  5. Select the appropriate template
    • Post to a channel when a webhook request is received
    • Post to a chat when a webhook request is received
  6. Verify that Microsoft Teams is successfully enabled
  7. Select Next
  8. Select an appropriate value from the Microsoft Teams Team drop-down list.
  9. Select an appropriate Microsoft Teams Channel drop-down list.
  10. Select Create flow
  11. Copy the new workflow URL
  12. Select Done
Using Teams client app
  1. Open Workflows application in teams
  2. Select Create across the top of the UI
  3. Choose Notifications at the left
  4. Select Post to a channel when a webhook request is received
  5. Verify that Microsoft Teams is successfully enabled
  6. Select Next
  7. Select an appropriate value from the Microsoft Teams Team drop-down list.
  8. Select an appropriate Microsoft Teams Channel drop-down list.
  9. Select Create flow
  10. Copy the new workflow URL
  11. Select Done
Using Power Automate web UI

This template walks you through the steps of creating a new Workflow using the https://make.powerautomate.com/ web UI:

  1. Select or create a new connection (e.g., [email protected]) to Microsoft Teams
  2. Select Create
  3. Select an appropriate value from the Microsoft Teams Team drop-down list.
  4. Select an appropriate Microsoft Teams Channel drop-down list.
  5. Select Create
  6. If prompted, read the info message (e.g., "Your flow is ready to go") and dismiss it.
  7. Select Edit from the menu across the top
    • alternatively, select My flows from the side menu, then select Edit from the "More commands" ellipsis
  8. Select When a Teams webhook request is received (e.g., left click)
  9. Copy the HTTP POST URL value
    • this is your private custom Workflow connector URL
    • by default anyone can POST a request to this Workflow connector URL
      • while this access setting can be changed it will prevent this library from being used to submit webhook requests

O365 connectors

O365 webhook URL format

Warning

O365 connector webhook URLs are deprecated and scheduled to be retired on 2024-10-01.

Valid (deprecated) O365 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 an O365 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 an O365 connector webhook URL

Warning

O365 connector webhook URLs are deprecated and scheduled to be retired on 2024-10-01.

  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

Command-line

Currently send2teams only supports command-line configuration flags. Requests for other configuration sources will be considered.

Flag Required Default Possible Description
h, help No N/A N/A Display Help; show available flags.
v, version No false true, false Whether to display application version and then immediately exit application.
channel No unspecified valid Microsoft Teams channel name The target channel where we will send a message. If not specified, defaults to unspecified.
color No NotUsed N/A NOOP; this setting is no longer used. Values specified for this flag are ignored.
message Yes valid message string The (optionally) Markdown-formatted message to submit.
team No unspecified valid Microsoft Teams team name The name of the Team containing our target channel. If not specified, defaults to unspecified.
title No valid title string The (optional) title for the message to submit.
sender No valid application or script name The (optional) sending application name or generator of the message this app will attempt to deliver.
url Yes valid Webhook URL The Webhook URL provided by a pre-configured Connector.
target-url No valid comma-separated url, description pair The target URL and label (specified as comma separated pair) usually visible as a button towards the bottom of the Microsoft Teams message.
verbose No false true, false Whether detailed output should be shown after message submission success or failure
silent No false true, false Whether ANY output should be shown after message submission success or failure
convert-eol No false true, false Whether messages with Windows, Mac and Linux newlines are updated to use break statements before message submission
disable-url-validation No false true, false Whether webhook URL validation should be disabled. Useful when submitting generated JSON payloads to a service like https://httpbin.org/.
disable-branding-trailer No false true, false Whether the branding trailer should be omitted from all messages generated by this application.
ignore-invalid-response No false true, false Whether an invalid response from remote endpoint should be ignored. This is expected if submitting a message to a non-standard webhook URL.
retries No 2 positive whole number The number of attempts that this application will make to deliver messages before giving up.
retries-delay No 2 positive whole number The number of seconds that this application will wait before making another delivery attempt.
user-mention No one or more valid comma-separated name, id pairs The DisplayName and ID of the recipient (specified as comma separated pair) for a user mention. May be repeated to create multiple user mentions.

Limitations

message size

Per official documentation (see references), each message sent to Microsoft Teams can be approximately 28 KB. This includes the message itself (text, image links, etc.), @-mentions, and reactions.

Examples

One-off

This example illustrates the basics of using the application to submit a single message. This can serve as a starting point for use with Nagios, scripts or any other tool that calls out to others in order to perform its tasks.

The same example, shown split over multiple lines for readability (e.g., shell script):

send2teams \
  --silent \
  --channel "Alerts" \
  --team "Support" \
  --message "System XYZ is down!" \
  --title "System outage alert" \
  --sender "Nagios" \
  --url "https://outlook.office.com/webhook/www@xxx/IncomingWebhook/yyy/zzz"

and on a single line (e.g., one-off via terminal or batch file):

send2teams.exe --silent --channel "Alerts" --team "Support" --message "System XYZ is down!" --title "System outage alert" --sender "Nagios" --url "https://outlook.office.com/webhook/www@xxx/IncomingWebhook/yyy/zzz"

Note:

  • remove the -silent flag in order to see pass or failure output
  • use the -verbose flag to see the JSON payload submitted to Microsoft Teams
  • check the exit code ($?) to determine overall success/failure result

Using an invalid flag

Accidentally typing the wrong flag results in a message like this one:

flag provided but not defined: -fake-flag

Specifying url, description pairs

send2teams \
  --silent \
  --channel "Alerts" \
  --team "Support" \
  --message "Useful starting points" \
  --title "Learn more about Go" \
  --sender "Nagios" \
  --url "https://outlook.office.com/webhook/www@xxx/IncomingWebhook/yyy/zzz" \
  --target-url "https://go.dev/, Go Homepage" \
  --target-url "https://github.com/dariubs/GoBooks, Awesome Go Books"

and on a single line (e.g., one-off via terminal or batch file):

send2teams.exe --silent --channel "Alerts" --team "Support" --message "Useful starting points" --title "Learn more about Go" --sender "Nagios" --url "https://outlook.office.com/webhook/www@xxx/IncomingWebhook/yyy/zzz" --target-url "https://go.dev/, Go Homepage" --target-url "https://github.com/dariubs/GoBooks, Awesome Go Books"

User mentions

One mention

This example illustrates mentioning a user along with providing a brief message.

The example, shown split over multiple lines for readability (e.g., shell script):

send2teams \
  --silent \
  --channel "Alerts" \
  --team "Support" \
  --message "System XYZ is down!" \
  --user-mention "John Doe,[email protected]" \
  --sender "Nagios" \
  --url "https://outlook.office.com/webhook/www@xxx/IncomingWebhook/yyy/zzz"

and on a single line (e.g., one-off via terminal or batch file):

send2teams --silent --channel "Alerts" --team "Support" --message "System XYZ is down!" --user-mention "John Doe,[email protected]" --sender "Nagios" --url "https://outlook.office.com/webhook/www@xxx/IncomingWebhook/yyy/zzz"

Note:

  • remove the -silent flag in order to see pass or failure output
  • use the -verbose flag to see the JSON payload submitted to Microsoft Teams
  • check the exit code ($?) to determine overall success/failure result

Multiple mentions

This example illustrates mentioning multiple users along with providing a brief message. The --user-mention flag is repeated for each user mention.

Though valid syntax, repeating the same user mention does not increase the number of times the same user is notified of a user mention.

The example, shown split over multiple lines for readability (e.g., shell script):

send2teams \
  --silent \
  --channel "Alerts" \
  --team "Support" \
  --message "System XYZ is down!" \
  --user-mention "John Doe,[email protected]" \
  --user-mention "Jane Doe,[email protected]" \
  --sender "Nagios" \
  --url "https://outlook.office.com/webhook/www@xxx/IncomingWebhook/yyy/zzz"

and on a single line (e.g., one-off via terminal or batch file):

send2teams --silent --channel "Alerts" --team "Support" --message "System XYZ is down!" --user-mention "John Doe,[email protected]" --user-mention "Jane Doe,[email protected]" --sender "Nagios" --url "https://outlook.office.com/webhook/www@xxx/IncomingWebhook/yyy/zzz"

Note:

  • remove the -silent flag in order to see pass or failure output
  • use the -verbose flag to see the JSON payload submitted to Microsoft Teams
  • check the exit code ($?) to determine overall success/failure result

License

From the LICENSE file:

MIT License

Copyright 2021 Adam Chalkley

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

References

About

Small CLI tool used to submit messages to Microsoft Teams.

Topics

go cli golang nagios microsoft-teams

Resources

Readme

License

MIT license
Activity

Stars

26 stars

Watchers

4 watching

Forks

1 fork
Report repository

Releases 105

v0.13.7 Latest
Nov 13, 2024
+ 104 releases

Contributors 2

  •  
  •  

Languages