Subscriptions Beta Changes

Hey, devs!

As you may have seen, we announced a new subscriptions beta that is coming up. With that, we’ve made some changes to the developer platform to allow for integrations with the new subscriptions.


How does this affect notifications of subscriptions?
Initial subscriptions and resubscriptions are exactly the same now. That is, both are sent over USERNOTICE.

NOTE: First-time subs will show up immediately over USERNOTICE and PubSub. Resubs still require that a user press the button to share their sub. It is possible the user never clicks the button.

Why am I seeing two subscription messages in chat?
The two messages are a side-effect of supporting backwards compatibility for integrations. We’re still sending twitchnotify AND USERNOTICE until bots have a chance to move over. We’re working to set a removal date ASAP.

Chat Changes

With this release, twitchnotify is deprecated. It will be removed at a later date, to be announced on May 24, 2017.

All subscriptions and resubscriptions will be sent as a USERNOTICE.

NOTE: During the deprecation period, you will see both twitchnotify and USERNOTICE messages. Your code must handle this accordingly.

USERNOTICE messages will contain the following new IRC tags related to subscription plans:

msg-id — Contains the type of subscription displayed by this USERNOTICE. Valid values: sub, resub.
msg-param-sub-plan — Identifies the type of subscription plan being used. Valid values: Prime, 1000, 2000, 3000.
msg-param-sub-plan-name — Contains the name of the subscription plan.

Example Message

@badges=staff/1,broadcaster/1,turbo/1;color=#008000;display-name=TWITCH_UserName;emotes=;mod=0;msg-id=sub/resub;msg-param-months=6;room-id=1337;subscriber=1;msg-param-sub-plan=Prime/1000/2000/3000;msg-param-sub-plan-name=Channel\sSubscription\s(display_name);system-msg=TWITCH_UserName\shas\ssubscribed\sfor\s6\smonths!;login=twitch_username;turbo=1;user-id=1337;user-type=staff USERNOTICE #channel :Great stream -- keep it up!

PubSub Changes

With the release of subscription plans, we will add a PubSub topic for subscriptions. This will allow you to listen for subscription events over a WebSocket rather than listening on IRC or polling the API. The topic is:

channel-subscribe-events-v1.<channel ID>

Required scope: channel_subscriptions.

Example Message

   "type": "MESSAGE",
   "data": {
      "topic": "channel-subscribe-events-v1.44322889",
      "message": {
         "user_name": "dallas",
         "display_name": "こんにちは", 
         "channel_name": "twitch",
         "user_id": "44322889",
         "channel_id": "12826",
         "time": "2015-12-19T16:39:57-08:00",
         "sub_plan": "Prime"/"1000"/"2000"/"3000",
         "sub_plan_name": "Mr_Woodchuck - Channel Subscription (mr_woodchuck)",
         "months": 9,
         "context": "sub"/"resub",
         "sub_message": {
            "message": "A Twitch baby is born! KappaHD",
            "emotes": [
               "start": 23,
               "end": 7,
               "id": 2867

REST API Changes

Three REST endpoints are affected. Their responses will be augmented with subscription plan information

Check User Subscription by Channel


Checks if a specified user is subscribed to a specified channel.

Required authentication scope: user_subscriptions

URL: GET<user ID>/subscriptions/<channel ID>

    "_id": "ac2f1248993eaf97e71721458bd88aae66c92330",
    "sub_plan": "3000",
    "sub_plan_name": "Channel Subscription (forstycup) - $X.XX Sub",
    "channel": {
        "_id": "19571752",
        "broadcaster_language": "en",
        "created_at": "2011-01-16T04:35:51Z",
        "display_name": "forstycup",
        "followers": 397,
        "game": "Final Fantasy XV",
        "language": "en",
        "logo": "",
        "mature": true,
        "name": "forstycup",
        "partner": true,
        "profile_banner": null,
        "profile_banner_background_color": null,
        "status": "[Blind] Moar Sidequests! Let's explore.",
        "updated_at": "2017-04-06T09:00:41Z",
        "url": "http://localhost:3000/forstycup",
        "video_banner": "",
        "views": 5705
    "created_at": "2017-04-08T19:54:24Z"

Get Channel Subscribers


Gets a list of users subscribed to a specified channel, sorted by the date when they subscribed.

Required authentication scope: channel_subscriptions

URL: GET<channel ID>/subscriptions

    "_total": 4,
    "subscriptions": [
            "_id": "e5e2ddc37e74aa9636625e8d2cc2e54648a30418",
            "created_at": "2016-04-06T04:44:31Z",
            "sub_plan": "1000",
            "sub_plan_name": "Channel Subscription (mr_woodchuck)",
            "user": {
                "_id": "89614178",
                "bio": "Twitch staff member who is a heimerdinger main on the road to diamond.",
                "created_at": "2015-04-26T18:45:34Z",
                "display_name": "Mr_Woodchuck",
                "logo": "",
                "name": "mr_woodchuck",
                "type": "staff",
                "updated_at": "2017-04-06T00:14:13Z"
    . . .

Check Channel Subscription by User


Checks if a specified channel has a specified user subscribed to it.

Required authentication scope: channel_check_subscription

URL: GET<channel ID>/subscriptions/<user ID>

    "_id": "8bded3af51046d2d365279fe92a976b6a4ceb006",
    "created_at": "2017-04-08T19:15:39Z",
    "sub_plan": "3000",
    "sub_plan_name": "Channel Subscription (mr_woodchuck) - $X.XX Sub",
    "user": {
        "_id": "13405587",
        "bio": "Software Engineer at Twitch and casual speedrunner. I play video games!",
        "created_at": "2010-06-27T05:33:45Z",
        "display_name": "TWW2",
        "logo": "",
        "name": "tww2",
        "type": "staff",
        "updated_at": "2017-04-06T03:31:55Z"

For those that uses mIRC for welcoming subs & re-subs in chat, I’ve made an example script with every single sub and re-sub situations possible for the new Subscriptions Beta system.

For “_total” under Get Channel Subscribers, will that be for the total number of users that are subscribed or the total number of subscriptions considered by Twitch?

1 Like

Ayyy, no more hacky twitchnotify parsing for new subscriptions!

1 Like

When users get the exclusive channel emotes for subscribing at a higher rate, will those emotes have their own set number (emoticon_set)? Or will the API change for the emotes also?


1 Like

Will the system-msg contain info about what plan it is (like it mentions Twitch Prime already)? I’m only using it for displaying it to the user and wondering if I need to add that info myself from the tags.

@zapdos26 The total value hasn’t changed. It is a count of the subscriptions.

@scottrc Looking into this and will get back to you ASAP.

@tduva The text should mention the current tier and/or Prime. I’d highly recommend using the tag since that will save you from text changes. We know those happen. :stuck_out_tongue:

@DallasNChains According to the blog it says that a $9.99 will count as two subs and $24.99 subscription will count as six subs (in terms of count towards getting emotes). Previously the total value I thought was calculated by the total number of subscriptions. With the addition of these new tiers, does the total count remain the number of people subscribed to the channel or does it change to the amount of subscriptions that count towards these emote limits? And if possible, will you guys add the other piece of info that the _total is not?

$9.99 and $24.99 emote tiers each have their own emoticon_set values. So you if sub to the highest tier you will have three emoticon_sets assigned to you from the single subscription to use all the emotes.

1 Like

So, the sub beta system has rolled out in a few channels I have mIRC in. But apparently, the msg-param-sub-plan and msg-param-sub-plan-name tags does not exist even though a few people re-subbed with the $9.99 and $24.99 plans and there’s something like just\ssubscribed\swith\sa\s$9.99\ssub. in the system-msg tag. Is that meant to happen or just the tags are not added yet?

@zapdos26 It is the number of people subscribed to the channel and not the subscriber “score” (number + extra). We’re looking into adding the total “score” to the API.

@Jacky1356400 All of the developer parts should be going live soon! They’re not fully live yet.

Ah I see. :thumbsup:

Thanks :slight_smile:

This may warrant a separate thread, but I seem to be getting some inconsistencies with the subscription notifications in chat.

Most of the time I am getting a USERNOTICE as expected, however sometimes I appear to only be getting a twitchnotify PRIV message.
And, to that end, I get seemingly redundant yet different messages in chat, which I think may be tied to the larger issue on hand. The messages are:
username just subscribed!
username just subscribed with a $4.99 sub!

Because some subscription events seem to be missing USERNOTICE tags, it makes parsing the subscription event on the basis of USERNOTICE (instead of say twitchnotify) fairly inconsistent.

Perhaps I’m overlooking or not understanding something though.

1 Like

Yeah @swiftyspiffy I am getting the same problem too.
Seems like USERNOTICE events only fires up on a re-sub but not new sub as intended.

1 Like

@swiftyspiffy @Jacky1356400 I think the system hasn’t been clearly explained, which is causing confusion. I’ve gotten a few questions about this since our release. :slight_smile:

New subs work just like resubs now. The USERNOTICE and PubSub will only show up when the user presses the button to share their sub. It is possible the user never clicks the button.

The two messages are a side-effect of supporting backwards compatibility for integrations. We’re still sending twitchnotify AND USERNOTICE until bots have a chance to move over. We’re working to set a removal date ASAP.

Hope that helps!

So, say if there’s a new sub, twitchnotify still fires up a notification of the person just subscribed and if the person presses the share button, notification fires up again but in USERNOTICE. I think that’s right?

That’s correct, @Jacky1356400. That’s why we want to remove twitchnotify ASAP so that devs aren’t getting double messages. :slight_smile:

1 Like

Alright thanks.

That makes a lot of sense. So a quick follow up on that. The twitchnotify is not optional. When someone subscribes for the first time, that message is sent no matter what. The USERNOTICE is entirely optional. Is this correct?