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.
FAQ
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 :tmi.twitch.tv 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
See https://dev.twitch.tv/docs/v5/reference/users/#check-user-subscription-by-channel.
Checks if a specified user is subscribed to a specified channel.
Required authentication scope: user_subscriptions
URL: GET https://api.twitch.tv/kraken/users/<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": "https://static-cdn.jtvnw.net/jtv_user_pictures/forstycup-profile_image-940fb4ca1e5949c0-300x300.png",
"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": "https://static-cdn.jtvnw.net/jtv_user_pictures/forstycup-channel_offline_image-f7274322063da225-1920x1080.png",
"views": 5705
},
"created_at": "2017-04-08T19:54:24Z"
}
Get Channel Subscribers
See https://dev.twitch.tv/docs/v5/reference/channels/#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 https://api.twitch.tv/kraken/channels/<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": "https://static-cdn.jtvnw.net/jtv_user_pictures/mr_woodchuck-profile_image-a8b10154f47942bc-300x300.jpeg",
"name": "mr_woodchuck",
"type": "staff",
"updated_at": "2017-04-06T00:14:13Z"
}
},
. . .
]
}
Check Channel Subscription by User
See https://dev.twitch.tv/docs/v5/reference/channels/#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 https://api.twitch.tv/kraken/channels/<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": "https://static-cdn.jtvnw.net/jtv_user_pictures/tww2-profile_image-6af5324eddee1468-300x300.png",
"name": "tww2",
"type": "staff",
"updated_at": "2017-04-06T03:31:55Z"
}
}