goteamsnotify
A package to send messages to a Microsoft Teams channel.
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 messages
to a Microsoft Teams channel. These messages can be composed of legacy
MessageCard
or Adaptive Card
card
formats.
Simple messages can be created by specifying only a title and a text body.
More complex messages may be composed of multiple sections (MessageCard
) or
containers (Adaptive Card
), key/value pairs (aka, Facts
) and externally
hosted images. See the Features list for more information.
NOTE: Adaptive Card
support is currently limited. The goal is to expand
this support in future releases to include additional features supported by
Microsoft Teams.
Features
- Submit simple or complex messages to Microsoft Teams
- simple messages consist of only a title and a text body (one or more strings)
- complex messages may consist of multiple sections (
MessageCard
), containers (Adaptive Card
) key/value pairs (aka,Facts
) and externally hosted images
- Support for Actions, allowing users to take quick actions within Microsoft Teams
- Support for user mentions (
Adaptive Card
format) - 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 validation of
Adaptive Card
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
Project Status
In short:
- The upstream project is no longer being actively developed or maintained.
- This fork is now a standalone project, accepting contributions, bug reports and feature requests.
- Others have also taken an interest in maintaining their own forks of the original project. See those forks for other ideas/changes that you may find useful.
For more details, see the Releases section or our Changelog.
Supported Releases
Series | Example | Status |
---|---|---|
v1.x.x |
v1.3.1 |
Not Supported (EOL) |
v2.x.x |
v2.6.0 |
Supported |
v3.x.x |
v3.0.0-alpha.1 |
TBD |
The current plan is to continue extending the v2 branch with new functionality while retaining backwards compatibility. Any breakage in compatibility for the v2 series is considered a bug (please report it).
Long-term, the goal is to learn from missteps made in current releases and correct as many as possible for a future v3 series.
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
See the Examples section for more details.
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
- e.g.,
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
- note the
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)
- Open Microsoft Teams
- Navigate to the channel where you wish to receive incoming messages from this application
- Select
โฏ
next to the channel name and then choose Connectors. - Scroll through the list of Connectors to Incoming Webhook, and choose Add.
- Enter a name for the webhook, upload an image to associate with data from the webhook, and choose Create.
- 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.
- Choose Done.
Credit: docs.microsoft.com, gist comment from shadabacc3934
Examples
Basic
This is an example of a simple client application which uses this library.
Specify proxy server
This is an example of a simple client application which uses this library to route a generated message through a specified proxy server.
User Mention
These examples illustrates the use of one or more user mentions. This feature
is not available in the legacy MessageCard
card format.
- File: user-mention-single
- File: user-mention-multiple
- File: user-mention-verbose
- this example does not necessarily reflect an optimal implementation
Tables
These examples illustrates the use of a Table
. This
feature is not available in the legacy MessageCard
card format.
- File: table-manually-created
- File: table-unordered-grid
- File: table-with-headers
Set custom user agent
This example illustrates setting a custom user agent.
Adaptive Card
- File: custom-user-agent
MessageCard
- File: custom-user-agent
Add an Action
This example illustrates adding an OpenUri
(MessageCard
) or OpenUrl
Action. When used,
this action triggers opening a URL in a separate browser or application.
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).
Adaptive Card
- File: disable-validation
MessageCard
- File: disable-validation
Enable custom patterns' validation
This example demonstrates how to enable custom validation patterns for webhook URLs.
Adaptive Card
- File: custom-validation
MessageCard
- File: custom-validation
Used by
See the Known importers lists below for a dynamically updated list of projects using either this library or the original project.
References
-
Microsoft Teams
- MS Teams - adaptive cards (de-de, en-us)
- MS Teams - send via connectors (de-de, en-us)
- adaptivecards.io
- Legacy actionable message card reference