diff --git a/README.md b/README.md
index fa171af..5e232c4 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@ A package to send messages to Microsoft Teams (channels)
- [How to create a webhook URL (Connector)](#how-to-create-a-webhook-url-connector)
- [Examples](#examples)
- [Basic](#basic)
+ - [Set custom user agent](#set-custom-user-agent)
- [Add an Action](#add-an-action)
- [Disable webhook URL prefix validation](#disable-webhook-url-prefix-validation)
- [Enable custom patterns' validation](#enable-custom-patterns-validation)
@@ -70,6 +71,7 @@ information.
- Configurable timeouts
- Configurable retry support
- Support for overriding the default `http.Client`
+- Support for overriding default project-specific user agent
## Project Status
@@ -185,6 +187,12 @@ This is an example of a simple client application which uses this library.
File: [basic](./examples/basic/main.go)
+#### Set custom user agent
+
+This example illustrates setting a custom user agent.
+
+File: [custom-user-agent](./examples/custom-user-agent/main.go)
+
#### Add an Action
This example illustrates adding an [`OpenUri Action`][msgcard-ref-actions] to
diff --git a/doc.go b/doc.go
index 81ce0f1..5492584 100644
--- a/doc.go
+++ b/doc.go
@@ -35,6 +35,8 @@ FEATURES
• Support for overriding the default http.Client
+• Support for overriding the default project-specific user agent
+
USAGE
diff --git a/examples/custom-user-agent/main.go b/examples/custom-user-agent/main.go
new file mode 100644
index 0000000..aa936f3
--- /dev/null
+++ b/examples/custom-user-agent/main.go
@@ -0,0 +1,52 @@
+// Copyright 2021 Adam Chalkley
+//
+// https://github.com/atc0005/go-teams-notify
+//
+// Licensed under the MIT License. See LICENSE file in the project root for
+// full license information.
+
+/*
+
+This is an example of a simple client application which uses this library.
+
+Of note:
+
+- default timeout
+- custom user agent
+- 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
+
+*/
+
+package main
+
+import (
+ goteamsnotify "github.com/atc0005/go-teams-notify/v2"
+)
+
+func main() {
+ _ = sendTheMessage()
+}
+
+func sendTheMessage() error {
+ // init the client
+ mstClient := goteamsnotify.NewClient()
+
+ // override the project-specific default user agent
+ mstClient.SetUserAgent("go-teams-notify-example/1.0")
+
+ // 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 " +
+ "
* this list itself
* **bold**
* *italic*
* ***bolditalic***"
+ msgCard.ThemeColor = "#DF813D"
+
+ // send
+ return mstClient.Send(webhookUrl, msgCard)
+}
diff --git a/send.go b/send.go
index a53567e..dfb954e 100644
--- a/send.go
+++ b/send.go
@@ -69,6 +69,14 @@ const ExpectedWebhookURLResponseText string = "1"
// before it times out and is cancelled.
const DefaultWebhookSendTimeout = 5 * time.Second
+// DefaultUserAgent is the project-specific user agent used when submitting
+// messages unless overridden by client code. This replaces the Go default
+// user agent value of "Go-http-client/1.1".
+//
+// The major.minor numbers reflect when this project first diverged from the
+// "upstream" or parent project.
+const DefaultUserAgent string = "go-teams-notify/2.2"
+
// ErrWebhookURLUnexpected is returned when a provided webhook URL does
// not match a set of confirmed webhook URL patterns.
var ErrWebhookURLUnexpected = errors.New("webhook URL does not match one of expected patterns")
@@ -90,6 +98,7 @@ type API interface {
SendWithContext(ctx context.Context, webhookURL string, webhookMessage MessageCard) error
SendWithRetry(ctx context.Context, webhookURL string, webhookMessage MessageCard, retries int, retriesDelay int) error
SetHTTPClient(httpClient *http.Client) API
+ SetUserAgent(userAgent string) API
SkipWebhookURLValidationOnSend(skip bool) API
AddWebhookURLValidationPatterns(patterns ...string) API
ValidateWebhook(webhookURL string) error
@@ -97,6 +106,7 @@ type API interface {
type teamsClient struct {
httpClient *http.Client
+ userAgent string
webhookURLValidationPatterns []string
skipWebhookURLValidation bool
}
@@ -142,6 +152,14 @@ func (c *teamsClient) SetHTTPClient(httpClient *http.Client) API {
return c
}
+// SetUserAgent accepts a custom user agent string. This custom user agent is
+// used when submitting messages to Microsoft Teams.
+func (c *teamsClient) SetUserAgent(userAgent string) API {
+ c.userAgent = userAgent
+
+ return c
+}
+
func (c *teamsClient) AddWebhookURLValidationPatterns(patterns ...string) API {
c.webhookURLValidationPatterns = append(c.webhookURLValidationPatterns, patterns...)
return c
@@ -190,6 +208,14 @@ func (c teamsClient) SendWithContext(ctx context.Context, webhookURL string, web
req, _ := http.NewRequestWithContext(ctx, http.MethodPost, webhookURL, webhookMessageBuffer)
req.Header.Add("Content-Type", "application/json;charset=utf-8")
+ // If provided, override the project-specific user agent with custom value.
+ switch {
+ case c.userAgent != "":
+ req.Header.Set("User-Agent", c.userAgent)
+ default:
+ req.Header.Set("User-Agent", DefaultUserAgent)
+ }
+
// do the request
res, err := c.httpClient.Do(req)
if err != nil {