feat: add threaded messages as an slack option

Signed-off-by: Santiago Fernández Núñez <santiago.nunez@nubank.com.br>
Made-with: Cursor

Author: santiagofn

config/config_test.go

@@ -1072,13 +1072,58 @@ func TestSlackBothAppTokenAndAPIURL(t *testing.T) {
 	}
 }
 
-func TestSlackUpdateMessageWebhookURL(t *testing.T) {
+func TestSlackUpdateStrategyWebhookURL(t *testing.T) {
 	_, err := LoadFile("testdata/conf.slack-update-message-and-webhook.yml")
 	if err == nil {
-		t.Fatalf("Expected an error parsing %s: %s", "testdata/conf.slack-update-message-and-webhook", err)
+		t.Fatal("Expected an error")
 	}
-	if err.Error() != "update_message can only be used with bot tokens. api_url must be set to https://slack.com/api/chat.postMessage" {
-		t.Errorf("Expected: %s\nGot: %s", "update_message can only be used with bot tokens. api_url must be set to https://slack.com/api/chat.postMessage", err.Error())
+	expected := `message_strategy "update" requires a bot token; api_url must be https://slack.com/api/chat.postMessage`
+	if err.Error() != expected {
+		t.Errorf("Expected: %s\nGot: %s", expected, err.Error())
+	}
+}
+
+func TestSlackThreadStrategyWebhookURL(t *testing.T) {
+	_, err := LoadFile("testdata/conf.slack-thread-message-and-webhook.yml")
+	if err == nil {
+		t.Fatal("Expected an error")
+	}
+	expected := `message_strategy "thread" requires a bot token; api_url must be https://slack.com/api/chat.postMessage`
+	if err.Error() != expected {
+		t.Errorf("Expected: %s\nGot: %s", expected, err.Error())
+	}
+}
+
+func TestSlackThreadedOptionsWithoutThreadStrategy(t *testing.T) {
+	_, err := LoadFile("testdata/conf.slack-thread-resolve-emoji-without-thread-message.yml")
+	if err == nil {
+		t.Fatal("Expected an error")
+	}
+	expected := `threaded_options requires message_strategy to be "thread"`
+	if err.Error() != expected {
+		t.Errorf("Expected: %s\nGot: %s", expected, err.Error())
+	}
+}
+
+func TestSlackThreadedOptionsUpdateParentWithoutThreadStrategy(t *testing.T) {
+	_, err := LoadFile("testdata/conf.slack-thread-update-parent-without-thread-message.yml")
+	if err == nil {
+		t.Fatal("Expected an error")
+	}
+	expected := `threaded_options requires message_strategy to be "thread"`
+	if err.Error() != expected {
+		t.Errorf("Expected: %s\nGot: %s", expected, err.Error())
+	}
+}
+
+func TestSlackResolveColorWithoutSummaryHeader(t *testing.T) {
+	_, err := LoadFile("testdata/conf.slack-resolve-color-without-summary-header.yml")
+	if err == nil {
+		t.Fatal("Expected an error")
+	}
+	expected := `threaded_options.summary_header requires use_summary_header to be enabled`
+	if err.Error() != expected {
+		t.Errorf("Expected: %s\nGot: %s", expected, err.Error())
 	}
 }
 

config/notifiers.go

@@ -520,6 +520,45 @@ func (c *SlackField) UnmarshalYAML(unmarshal func(any) error) error {
 	return nil
 }
 
+// SlackMessageStrategy controls how subsequent notifications for the same
+// alert group are delivered to Slack.
+type SlackMessageStrategy string
+
+const (
+	// SlackMessageStrategyNew sends each notification as a separate message (default).
+	SlackMessageStrategyNew SlackMessageStrategy = "new"
+	// SlackMessageStrategyUpdate updates the original message in-place.
+	SlackMessageStrategyUpdate SlackMessageStrategy = "update"
+	// SlackMessageStrategyThread sends subsequent notifications as threaded replies.
+	SlackMessageStrategyThread SlackMessageStrategy = "thread"
+)
+
+// SlackThreadedOptions configures thread-specific behavior when message_strategy is "thread".
+type SlackThreadedOptions struct {
+	// ResolveEmoji is the emoji name (without colons) to react with on the
+	// original thread message when all alerts in the group are resolved.
+	// Requires the bot token to have reactions:write scope.
+	ResolveEmoji string `yaml:"resolve_emoji,omitempty" json:"resolve_emoji,omitempty"`
+
+	// UseSummaryHeader controls whether the thread parent is a lightweight
+	// auto-updated summary (true, default) or the first actual alert message
+	// (false). When true, all alert content is posted as replies and the parent
+	// is continuously updated with the transition title and color.
+	UseSummaryHeader *bool `yaml:"use_summary_header,omitempty" json:"use_summary_header,omitempty"`
+
+	// SummaryHeader holds options for summary-header mode only (see UseSummaryHeader).
+	SummaryHeader *SlackThreadSummaryHeaderOptions `yaml:"summary_header,omitempty" json:"summary_header,omitempty"`
+}
+
+// SlackThreadSummaryHeaderOptions configures fields that only apply when
+// message_strategy is "thread" and use_summary_header is true (the lightweight
+// parent summary mode).
+type SlackThreadSummaryHeaderOptions struct {
+	// ResolveColor overrides the parent summary attachment color when the alert
+	// group resolves. Supports Go templates.
+	ResolveColor string `yaml:"resolve_color,omitempty" json:"resolve_color,omitempty"`
+}
+
 // SlackConfig configures notifications via Slack.
 type SlackConfig struct {
 	amcommoncfg.NotifierConfig `yaml:",inline" json:",inline"`
@@ -555,10 +594,19 @@ type SlackConfig struct {
 	MrkdwnIn    []string       `yaml:"mrkdwn_in,omitempty" json:"mrkdwn_in,omitempty"`
 	Actions     []*SlackAction `yaml:"actions,omitempty" json:"actions,omitempty"`
 
+	// MessageStrategy controls how subsequent notifications for the same alert
+	// group are delivered: "new" (default), "update" (edit in-place), or "thread"
+	// (threaded replies). "update" and "thread" require a bot token.
+	MessageStrategy SlackMessageStrategy `yaml:"message_strategy,omitempty" json:"message_strategy,omitempty"`
+
 	// UpdateMessage enables updating existing Slack messages instead of creating new ones.
-	// Requires bot token with chat:write scope. Webhook URLs do not support updates.
+	// Deprecated: use message_strategy: update instead. If true, message_strategy must
+	// be unset or "update"; when message_strategy is unset it is treated as "update".
+	UpdateMessage bool `yaml:"update_message,omitempty" json:"update_message,omitempty"`
 
-	UpdateMessage bool `yaml:"update_message" json:"update_message,omitempty"`
+	// ThreadedOptions configures thread-specific behavior.
+	// Only valid when message_strategy is "thread".
+	ThreadedOptions *SlackThreadedOptions `yaml:"threaded_options,omitempty" json:"threaded_options,omitempty"`
 	// Timeout is the maximum time allowed to invoke the slack. Setting this to 0
 	// does not impose a timeout.
 	Timeout time.Duration `yaml:"timeout" json:"timeout"`
@@ -582,13 +630,69 @@ func (c *SlackConfig) UnmarshalYAML(unmarshal func(any) error) error {
 		return errors.New("at most one of api_url/api_url_file & app_token/app_token_file must be configured")
 	}
 
-	if c.UpdateMessage && c.APIURL.String() != "https://slack.com/api/chat.postMessage" {
-		return errors.New("update_message can only be used with bot tokens. api_url must be set to https://slack.com/api/chat.postMessage")
+	if c.UpdateMessage {
+		if c.MessageStrategy != "" && c.MessageStrategy != SlackMessageStrategyUpdate {
+			return fmt.Errorf("update_message: true is incompatible with message_strategy %q; omit message_strategy or set message_strategy: \"update\"", c.MessageStrategy)
+		}
+		if c.MessageStrategy == "" {
+			c.MessageStrategy = SlackMessageStrategyUpdate
+		}
+	}
+	if c.MessageStrategy == "" {
+		c.MessageStrategy = SlackMessageStrategyNew
+	}
+
+	switch c.MessageStrategy {
+	case SlackMessageStrategyNew:
+		// no extra requirements
+	case SlackMessageStrategyUpdate, SlackMessageStrategyThread:
+		if c.APIURL == nil && c.APIURLFile == "" {
+			return fmt.Errorf("message_strategy %q requires api_url or api_url_file", c.MessageStrategy)
+		}
+		if c.APIURL != nil && c.APIURL.String() != "https://slack.com/api/chat.postMessage" {
+			return fmt.Errorf("message_strategy %q requires a bot token; api_url must be https://slack.com/api/chat.postMessage", c.MessageStrategy)
+		}
+	default:
+		return fmt.Errorf("unknown message_strategy %q; must be \"new\", \"update\", or \"thread\"", c.MessageStrategy)
+	}
+
+	if c.ThreadedOptions != nil {
+		if c.MessageStrategy != SlackMessageStrategyThread {
+			return errors.New("threaded_options requires message_strategy to be \"thread\"")
+		}
+		if c.ThreadedOptions.UseSummaryHeader != nil && !*c.ThreadedOptions.UseSummaryHeader && c.ThreadedOptions.SummaryHeader != nil {
+			return errors.New("threaded_options.summary_header requires use_summary_header to be enabled")
+		}
 	}
 
 	return nil
 }
 
+// UseSummaryHeaderInThread returns true when the thread parent should be a lightweight
+// auto-updated summary. Returns true by default (nil or explicit true).
+func (c *SlackConfig) UseSummaryHeaderInThread() bool {
+	if c.ThreadedOptions == nil || c.ThreadedOptions.UseSummaryHeader == nil {
+		return true
+	}
+	return *c.ThreadedOptions.UseSummaryHeader
+}
+
+// HasStrategyThatUpdatesParent reports whether message_strategy uses nflog to tie
+// multiple notifications to one Slack message or thread.
+func (c *SlackConfig) HasStrategyThatUpdatesParent() bool {
+	return c.HasUpdateStrategy() || c.HasThreadStrategy()
+}
+
+// HasUpdateStrategy is true when message_strategy is "update" (chat.update in place).
+func (c *SlackConfig) HasUpdateStrategy() bool {
+	return c.MessageStrategy == SlackMessageStrategyUpdate
+}
+
+// HasThreadStrategy is true when message_strategy is "thread" (threaded replies).
+func (c *SlackConfig) HasThreadStrategy() bool {
+	return c.MessageStrategy == SlackMessageStrategyThread
+}
+
 // IncidentioConfig configures notifications via incident.io.
 type IncidentioConfig struct {
 	amcommoncfg.NotifierConfig `yaml:",inline" json:",inline"`

config/testdata/conf.slack-resolve-color-without-summary-header.yml

@@ -0,0 +1,18 @@
+route:
+  receiver: 'slack-notifications'
+  group_by: [alertname]
+receivers:
+  - name: 'slack-notifications'
+    slack_configs:
+      - channel: '#alerts1'
+        text: 'test'
+        send_resolved: true
+        api_url: 'https://slack.com/api/chat.postMessage'
+        http_config:
+          authorization:
+            credentials: 'xoxb-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX'
+        message_strategy: thread
+        threaded_options:
+          use_summary_header: false
+          summary_header:
+            resolve_color: '#AAAAAA'

config/testdata/conf.slack-thread-message-and-webhook.yml

@@ -0,0 +1,11 @@
+route:
+  receiver: 'slack-notifications'
+  group_by: [alertname]
+receivers:
+  - name: 'slack-notifications'
+    slack_configs:
+      - channel: '#alerts1'
+        text: 'test'
+        send_resolved: true
+        api_url: 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX'
+        message_strategy: thread

config/testdata/conf.slack-thread-resolve-emoji-without-thread-message.yml

@@ -0,0 +1,15 @@
+route:
+  receiver: 'slack-notifications'
+  group_by: [alertname]
+receivers:
+  - name: 'slack-notifications'
+    slack_configs:
+      - channel: '#alerts1'
+        text: 'test'
+        send_resolved: true
+        api_url: 'https://slack.com/api/chat.postMessage'
+        http_config:
+          authorization:
+            credentials: 'xoxb-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX'
+        threaded_options:
+          resolve_emoji: 'white_check_mark'

config/testdata/conf.slack-thread-update-parent-without-thread-message.yml

@@ -0,0 +1,15 @@
+route:
+  receiver: 'slack-notifications'
+  group_by: [alertname]
+receivers:
+  - name: 'slack-notifications'
+    slack_configs:
+      - channel: '#alerts1'
+        text: 'test'
+        send_resolved: true
+        api_url: 'https://slack.com/api/chat.postMessage'
+        http_config:
+          authorization:
+            credentials: 'xoxb-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX'
+        threaded_options:
+          resolve_emoji: 'white_check_mark'

config/testdata/conf.slack-update-message-and-webhook.yml

@@ -10,4 +10,4 @@ receivers:
         send_resolved: true
         # trying to use webhook urls with update_message
         api_url: 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX'
-        update_message: true
+        message_strategy: update

docs/configuration.md

@@ -1662,9 +1662,42 @@ fields:
 # NOTE: This will have no effect if set higher than the group_interval.
 [ timeout: <duration> | default = 0s ]
 
-# Enables updating existing Slack messages instead of creating new ones on alert state change.
-# Webhook URLs do not support updates.
-[ update_message: <boolean> | default = false ]
+# Controls how subsequent notifications for the same alert group are delivered.
+# "new" (default): each notification is a separate message.
+# "update": subsequent notifications update the original message in-place.
+# "thread": subsequent notifications are sent as threaded replies.
+# "update" and "thread" require api_url set to https://slack.com/api/chat.postMessage.
+[ message_strategy: <string> | default = "new" ]
+
+# Limitation for "thread" (and "update"): thread metadata (for example the parent
+# message timestamp and channel id) is written to the notification log only after
+# the integration returns success for the entire notification attempt. If Slack
+# accepts an earlier API call in the same attempt but a later call fails and retries
+# are exhausted, the next flush may not see stored thread state and can open a new
+# thread in the channel, leaving the previous thread without further updates.
+
+# Options for threaded message behavior. Only valid when message_strategy is "thread".
+threaded_options:
+  # When true (default), the thread parent is a lightweight auto-updated summary
+  # header and all alert content is posted as replies. When false, the first
+  # alert message IS the thread parent and subsequent alerts are threaded replies.
+  [ use_summary_header: <boolean> | default = true ]
+
+  # Emoji name (without colons) to react with on the parent thread message
+  # when all alerts in the group are resolved (e.g. "white_check_mark").
+  # Requires the bot token to have reactions:write scope.
+  [ resolve_emoji: <string> ]
+
+  # Options that only apply when use_summary_header is true (default).
+  [ summary_header: <summary_header_thread_config> ]
+```
+
+##### `<summary_header_thread_config>`
+
+```yaml
+# Overrides the parent summary attachment color when all alerts resolve.
+# Supports Go templates.
+[ resolve_color: <tmpl_string> ]
 ```
 
 #### `<action_config>` (Slack)