Updates to PubSub Messages and IRC for Multi-Month Subscription Gifting

Today Twitch announced Multi-Month Subscription Gifting. With this new feature, viewers can gift a subscription for multiple months (e.g. 3, 6, or 12) to individual recipients in a single transaction. As a result, we’ve updated the “Channel Subscriptions” PubSub topic to include new fields in the messages you receive and added an IRC USERNOTICE message parameter for subscriptions.

What’s new?

The new fields in the PubSub message object for “Channel Subscriptions” are:

  • is_gift – Always present in the message object. The value is set to true if this sub or resub was caused by a gift subscription, false otherwise.
  • multi_month_duration – Always present in the message object. The value is an integer set to the duration of the multi-month gift (e.g. 3, 6, 12).

The new message parameter for IRC USERNOTICEs is:

  • msg-params-gift-months – Only sent on subgift and anonsubgift USERNOTICEs. The value is the number of months gifted as part of a single, multi-month gift.

How do I get started?

To learn more about Multi-Month Subscription Gifting, visit the Twitch help article. To get started with the PubSub topic and IRC updates, visit the PubSub and chat documentation pages.

Please feel free to include comments or questions below.

Update: Changed the information for multi_month_duration to state this will always be present in the message object. We previously stated that it was only present during known or anonymous multi-month sub gifting.


A few questions:

  • What number will msg-param-cumulative-months contain?
  • Will there still be monthly anniversary notices?
  • If yes, what will their msg-param-cumulative-months field contain for each month?

Seems that is_gift is coming across as false when it should be true?

{"type":"MESSAGE","data":{"topic":"channel-subscribe-events-v1.10817445","message":"{\"benefit_end_month\":0,\"user_name\":\"REMOVED\",\"display_name\":\"REMOVED\",\"channel_name\":\"itmejp\",\"user_id\":\"REMOVED\",\"channel_id\":\"10817445\",\"recipient_id\":\"REMOVED\",\"recipient_user_name\":\"REMOVED\",\"recipient_display_name\":\"REMOVED\",\"time\":\"2020-07-01T19:43:22.139512197Z\",\"sub_message\":{\"message\":\"\",\"emotes\":null},\"sub_plan\":\"1000\",\"sub_plan_name\":\"itmeJP Sub - RollPlay VODs, No Ads, and more! \",\"months\":9,\"context\":\"subgift\",\"is_gift\":false,\"multi_month_duration\":1}"}}

The team has identified an issue related to is_gift set to false incorrectly and is working to resolve.

msg-param-cumulative-months is based on the tenure of a subscription (i.e. the amount of time someone has been a subscriber), so a multi-month gift will not inflate this number. For example, if I become a new subscriber thanks to the 12-month sub gift, my cumulative months would still be 1.

This also applies to monthly anniversary notices. The message will be based on the tenure of the subscription, not the total number of months someone has been gifted.

1 Like