[eventsub] Add shoutout_received event

Signed-off-by: Knut Ahlers <knut@ahlers.me>

events.go

@@ -32,6 +32,7 @@ var (
 	eventTypePermit             = ptrStr("permit")
 	eventTypeRaid               = ptrStr("raid")
 	eventTypeResub              = ptrStr("resub")
+	eventTypeShoutoutReceived   = ptrStr("shoutout_received")
 	eventTypeSubgift            = ptrStr("subgift")
 	eventTypeSubmysterygift     = ptrStr("submysterygift")
 	eventTypeSub                = ptrStr("sub")
@@ -60,6 +61,7 @@ var (
 		eventTypePermit,
 		eventTypeRaid,
 		eventTypeResub,
+		eventTypeShoutoutReceived,
 		eventTypeSub,
 		eventTypeSubgift,
 		eventTypeSubmysterygift,

pkg/twitch/eventsub.go

@@ -44,13 +44,12 @@ const (
 	// eventSubStatusVerificationFailed   = "webhook_callback_verification_failed"
 
 	EventSubEventTypeChannelFollow                         = "channel.follow"
+	EventSubEventTypeChannelPointCustomRewardRedemptionAdd = "channel.channel_points_custom_reward_redemption.add"
 	EventSubEventTypeChannelRaid                           = "channel.raid"
+	EventSubEventTypeChannelShoutoutReceive                = "channel.shoutout.receive"
 	EventSubEventTypeChannelUpdate                         = "channel.update"
 	EventSubEventTypeStreamOffline                         = "stream.offline"
 	EventSubEventTypeStreamOnline                          = "stream.online"
-
-	EventSubEventTypeChannelPointCustomRewardRedemptionAdd = "channel.channel_points_custom_reward_redemption.add"
-
 	EventSubEventTypeUserAuthorizationRevoke               = "user.authorization.revoke"
 
 	EventSubTopicVersion1    = "1"
@@ -81,6 +80,7 @@ type (
 		RewardID              string `json:"reward_id,omitempty"`
 		ToBroadcasterUserID   string `json:"to_broadcaster_user_id,omitempty"`
 		UserID                string `json:"user_id,omitempty"`
+		ModeratorUserID       string `json:"moderator_user_id,omitempty"`
 	}
 
 	EventSubEventChannelPointCustomRewardRedemptionAdd struct {
@@ -133,6 +133,17 @@ type (
 		Viewers                  int64  `json:"viewers"`
 	}
 
+	EventSubEventShoutoutReceived struct {
+		BroadcasterUserID        string    `json:"broadcaster_user_id"`
+		BroadcasterUserLogin     string    `json:"broadcaster_user_login"`
+		BroadcasterUserName      string    `json:"broadcaster_user_name"`
+		FromBroadcasterUserID    string    `json:"from_broadcaster_user_id"`
+		FromBroadcasterUserLogin string    `json:"from_broadcaster_user_login"`
+		FromBroadcasterUserName  string    `json:"from_broadcaster_user_name"`
+		ViewerCount              int64     `json:"viewer_count"`
+		StartedAt                time.Time `json:"started_at"`
+	}
+
 	EventSubEventStreamOffline struct {
 		BroadcasterUserID    string `json:"broadcaster_user_id"`
 		BroadcasterUserLogin string `json:"broadcaster_user_login"`

pkg/twitch/scopes.go

@@ -19,6 +19,7 @@ const (
 	ScopeModeratorManageShieldMode   = "moderator:manage:shield_mode"
 	ScopeModeratorManageShoutouts    = "moderator:manage:shoutouts"
 	ScopeModeratorReadFollowers      = "moderator:read:followers"
+	ScopeModeratorReadShoutouts      = "moderator:read:shoutouts"
 	ScopeUserManageChatColor         = "user:manage:chat_color"
 
 	// Deprecated v5 scope but used in chat

scopes.go

@@ -12,6 +12,7 @@ var (
 		twitch.ScopeChannelManageVIPS:        "manage VIPs",
 		twitch.ScopeChannelReadRedemptions:   "see channel-point redemptions",
 		twitch.ScopeModeratorReadFollowers:   "see who follows this channel",
+		twitch.ScopeModeratorReadShoutouts:   "see shoutouts received",
 	}
 
 	botDefaultScopes = []string{

twitchWatcher.go

@@ -143,6 +143,13 @@ func (t *twitchWatcher) getTopicRegistrations(userID string) []topicRegistration
 			AnyScope:       true,
 			Hook:           t.handleEventSubChannelPointCustomRewardRedemptionAdd,
 		},
+		{
+			Topic:          twitch.EventSubEventTypeChannelShoutoutReceive,
+			Condition:      twitch.EventSubCondition{BroadcasterUserID: userID, ModeratorUserID: userID},
+			RequiredScopes: []string{twitch.ScopeModeratorManageShoutouts, twitch.ScopeModeratorReadShoutouts},
+			AnyScope:       true,
+			Hook:           t.handleEventSubShoutoutReceived,
+		},
 	}
 }
 
@@ -218,6 +225,25 @@ func (t *twitchWatcher) handleEventSubChannelUpdate(m json.RawMessage) error {
 	return nil
 }
 
+func (t *twitchWatcher) handleEventSubShoutoutReceived(m json.RawMessage) error {
+	var payload twitch.EventSubEventShoutoutReceived
+	if err := json.Unmarshal(m, &payload); err != nil {
+		return errors.Wrap(err, "unmarshalling event")
+	}
+
+	fields := plugins.FieldCollectionFromData(map[string]any{
+		"channel": "#" + payload.FromBroadcasterUserLogin,
+		"from_id": payload.FromBroadcasterUserID,
+		"from":    payload.FromBroadcasterUserLogin,
+		"viewers": payload.ViewerCount,
+	})
+
+	log.WithFields(log.Fields(fields.Data())).Info("Shoutout received")
+	go handleMessage(ircHdl.Client(), nil, eventTypeShoutoutReceived, fields)
+
+	return nil
+}
+
 func (t *twitchWatcher) handleEventSubStreamOnOff(isOnline bool) func(json.RawMessage) error {
 	return func(m json.RawMessage) error {
 		var payload twitch.EventSubEventFollow

wiki/Events.md

@@ -149,6 +149,17 @@ Fields:
 - `subscribed_months` - How long have they been subscribed
 - `username` - The login-name of the user who resubscribed
 
+## `shoutout_received`
+
+The channel received a (Twitch native) shoutout by another channel.
+
+Fields:
+
+- `channel` - The channel the event occurred in
+- `from_id` - The ID of the channel who issued the shoutout
+- `from` - The login-name of the channel who issued the shoutout
+- `viewers` - The amount of viewers the shoutout was shown to
+
 ## `stream_offline`
 
 The channels stream went offline. (This event has some delay to the real category change!)