Revise the `channel.subscription` topics
Request
Organize channel.subscription
topics to allow for alert like notifications to properly be provided. What displays in chat should be able to be mimicked via EventSub topics without having active tracking or additional api calls; Provide missing data where needed; Create new topics to fill in the gaps.
Current Scenarios
Brand New Subscriber: If a user subscribes for the first time in the channel, we get an alert as soon as they sub. This is incidental that it works properly for stream based alerts, as we are actually receiving the payment transaction rather than the in chat event.
Prime Gaming Resubscriber: If someone resubscribes with Prime Gaming, we get not only the channel.subscription.message
when they decide to share the message in chat, but also the channel.subscribe
event as they are technically a NEW subscriber when they first click the button to resubscribe. As it was explained to me, this is because the subscription lapses usually before they are able to share the renew event in chat. So we get the event for subscription start, as well as the message event when they do decide to share it. Without active tracking up to days before the event looking for channel.subscription.end
there is no way to properly react to the subscription alerts in a stateless manner.
User Gifts a Sub: We receive a channel.subscription.gift
event which is expected, but have no way to link to who gave which sub nor which channel.subscription.gift
event was its pair. Explained more thoroughly here: https://twitch.uservoice.com/forums/310213-developers/suggestions/43813413-provide-a-gift-event-id-in-the-channel-subscribe
User updates/upgrades their subscription: Currently in the case of PubSub no notification is sent for someone continuing their subscription from a gift or at times changing their tier to higher/lower. Data inconclusive of what happens in EventSub. https://twitch.uservoice.com/forums/310213-developers/suggestions/42454273-subscriber-upgrades
User resubscribes automatically, but never shares: It is perfectly fine for a user to not share their resubscription event in chat as often times it is automatic when they do renew; however, for metrics such as goals or otherwise this data is crucial for accurate tracking. Explained more by Barry: https://twitch.uservoice.com/forums/310213-developers/suggestions/42008110-please-provide-an-event-sub-that-emits-resub-paym
Important Notes
The events should be "stateless", meaning that active tracking of subs that expire should not be needed to ensure correct event usage. Otherwise, this requires a server like runtime which defeats the future "transport agnostic" approach and would require a server. Chat like notifications should be able to be built from eventsub without long term tracking, or other API calls; such as listening for subs, cheers, point redeems etc. Out of this list of proposals below, the only events that are intended to be used in an alert/stateless like environment are channel.subscription.message
, channel.subscription.gift
, and channel.subscription.update
. While the others can be used, the data would not be as transparent as to where it came from as it isn't provided in chat which may confuse viewers if used in that fashion.
Proposal
channel.subscribe Changes
channel.subscribe
would becomechannel.subscription.begin
(or.start
) to fall inline with other EventSub topics as well as to give a more granular expression of what it reacts to.- Subscriptions starting up, that either are new or have lapsed in the channel, would be signaled here. In theory this would present no change to the current implementation, but should be documented that this should be used for metrics rather than alerts.
duration_months
for multi month subs could be useful here to determine if a "long" term sub ended.- Gifter info to provide better metric data (more than just
is_gift
), would allow better understanding of retention.
channel.subscription.message Changes
channel.subscription.message
provide a mimicked data stream of what would appear in chat, meaning re-subscriptions or new subscriptions. The documentation would be also need to be changed to reflect this.- New Subscriptions
- A "default" message object would be provided, meaning that the
message.text
would be an empty string (not null) and themessage.emote
array would be an Array.empty cumulative_months
as well asstreak_months
would be 0.
- A "default" message object would be provided, meaning that the
- Gifting info would also be needed
is_gift
:boolean - Indicates if the subscription was a gift. Default: falseis_anonmyous
:boolean - Indicates if the gifter was anonymous. Default: falsegifter_user_id
:string - User id of the gifter. Default: string.emptygifter_user_login
:string - User login of the gifter. Default: string.emptygifter_user_name
:string - User name of the gifter. Default: string.emptygift_subscription_id
:string/Guid - Id associated with thechannel.subscription.gift
event. Default: string.empty
channel.subcription.end | Changes
channel.subscription.end
is for expiring subscriptions. This in theory should provide no change per se in use, but data such as what was documented in the "channel.subscription.begin
changes" would be beneficial here as well.
channel.subscription.gift | Changes
- When referencing the change mentioned earlier providing the gift info, there was mention of a
gift_subscription_id
. This id would either be the event id or a new field in thechannel.subscription.gift
event calledgift_id
. Ideally a new field should not be needed as the id should be the event itself, but it depends on the infrastructure packing this together. Also explained in https://twitch.uservoice.com/forums/310213-developers/suggestions/43813413-provide-a-gift-event-id-in-the-channel-subscribe
channel.subscription.update | New Topic
- New topic for subscription changes such as tiers or gift continuations who don't drop from a previous tenure. https://twitch.uservoice.com/forums/310213-developers/suggestions/42454273-subscriber-upgrades
channel.subscription.progress | New Topic
- New topic for subscription tenure metrics. This is mentioned in Barry's User Voice (link provided) which would be useful for metrics along side
channel.subscription.begin
andchannel.subscription.end
for users who don't share their resub in chat. https://twitch.uservoice.com/forums/310213-developers/suggestions/42008110-please-provide-an-event-sub-that-emits-resub-paym
channel.subscription.{all}
- Transaction method to allow understanding how a sub was acquired and react appropriately. In the past
Prime
was utilized as a tier of sub in places such as PubSub, but this has been pointed out to not necessarily be the case.is_prime
is too rigid and ignores other acquisitions such as iOS tokens. Instead a data point oftranscation_type
may be more idealistic. https://twitch.uservoice.com/forums/310213-developers/suggestions/42012043-add-is-prime-to-subscription-events
Relevant User Voice Topics
- https://twitch.uservoice.com/forums/310213-developers/suggestions/43813413-provide-a-gift-event-id-in-the-channel-subscribe
- https://twitch.uservoice.com/forums/310213-developers/suggestions/43241439-channel-subscriptions-to-include-who-gave-the-gift
- https://twitch.uservoice.com/forums/310213-developers/suggestions/42454273-subscriber-upgrades
- https://twitch.uservoice.com/forums/310213-developers/suggestions/42008110-please-provide-an-event-sub-that-emits-resub-paym
- https://twitch.uservoice.com/forums/310213-developers/suggestions/42012043-add-is-prime-to-subscription-events
