twitch-api

Module for easily using all twitch.tv API v3 endpoints in nodejs

Installation

npm install twitch-api

Usage

Follow the Authorization Code Flow that you can find in the official twitch.tv API v3 documentation:

1. Send the user you'd like to authenticate to twitch.tv's authentication URL (you can get this URL using the convenience method getAuthorizationUrl once the module is initiallized)
2. If the user authorizes your application, she will be redirected to https://[your registered redirect URI]/?code=[CODE]. There you can get the code you need to get the user's access token.

Step 1: Initialization

var TwitchApi = require('twitch-api');
var twitch = new TwitchApi({
    clientId: 'your client id',
    clientSecret: 'your client secret',
    redirectUri: 'same redirectUri that you have configured on your app',
    scopes: [array of scopes you want access to]
  });

Step 2: Get the user's access token

twitch.getAccessToken(code, function(err, body){
    if (err){
      console.log(err);
    } else {
      /*
      * body = {
      *   access_token: 'your authenticated user access token',
      *   scopes: [array of granted scopes]
      * }
      */
    }
});

Once you have your user's access token, you can use it to query any authenticated resource the user has (and has granted you) access to.

Methods

requestCallback (Callback)

The callback that will handle the response

Params

Name	Type	Optional	Description
err	Object	False	In request produces an error, it will be stored in this parameter. null if the request was successful
body	Object	False	The body of the response if the request was successful

getAuthorizationUrl (Function)

Returns the full URL to which you must send your user in order to authorize your application

var getauthorizationurl = getAuthorizationUrl();

Returns

Name	Type	Description
return	String	The the full URL to which you must send your user for authorization

getAccessToken (Function)

Requests Twitch.tv for an accessCode for your authorized user

getAccessToken(code, callback);

Params

Name	Type	Optional	Description
code	String	False	The code that twitch.tv's API sent in the redirection URI parameters when the user authorized your application
callback	requestCallback	False	The callback that will manage the response

refreshAccessToken (Function)

Requests Twitch.tv for an accessCode for using your refresh token

refreshAccessToken(refreshToken, callback);

Params

Name	Type	Optional	Description
refreshToken	String	False	The code that twitch.tv's API sent in the getAccessToken response
callback	requestCallback	False	The callback that will manage the response

getBlocks (Function)

Get user's block list

API endpoint: GET /users/:user/blocks

getBlocks(user, accessToken, [parameters], callback);

Params

Name	Type	Optional	Description
user	String	False	The user name of wich you want to get the block list, authenticated by accesToken
accessToken	String	False	The token representing the authenticated user
parameters	Object	True	The parameters of the API endpoint
callback	requestCallback	False	The callback that will manage the response

addBlock (Function)

Add target to user's block list

API endpoint: PUT /users/:user/blocks/:target

addBlock(user, accessToken, target, callback);

Params

Name	Type	Optional	Description
user	String	False	The user name of the user
accessToken	String	False	The token representing the authenticated user
target	String	False	the user name your user wants to block
callback	requestCallback	False	The callback that will manage the response

removeBlock (Function)

Delete target from user's block list

API endpoint: DELETE /users/:user/blocks/:target

removeBlock(user, accessToken, target, callback);

Params

Name	Type	Optional	Description
user	String	False	The user name of the user
accessToken	String	False	The token representing the authenticated user
target	String	False	the user name your user wants to unblock
callback	requestCallback	False	The callback that will manage the response

getChannel (Function)

Returns a channel object.

API endpoint: GET /channels/:channel/

getChannel(channel, callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
callback	requestCallback	False	The callback that will manage the response

getAuthenticatedUserChannel (Function)

Returns a channel object of authenticated user. Channel object includes stream key.

API endpoint: GET /channel

getAuthenticatedUserChannel(accessToken, callback);

Params

Name	Type	Optional	Description
accessToken	String	False	The token representing the authenticated user
callback	requestCallback	False	The callback that will manage the response

getChannelEditors (Function)

Returns a list of user objects who are editors of channel. The user should be the owner (maybe editor?) of the channel

API endpoint: GET /channels/:channel/editors

getChannelEditors(channel, accessToken, callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
accessToken	String	False	The token representing the authenticated user
callback	requestCallback	False	The callback that will manage the response

updateChannel (Function)

Update channel's status or game.

API endpoint: PUT /channels/:channel/

updateChannel(channel, accessToken, channelOptions, callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
accessToken	String	False	The token representing the authenticated user
channelOptions	Object	False	The options you want to change in JSON format
channelOptions.channel	JSON	False	The real options are wrapped here
channelOptions.channel.status	String	False	The new status of the channel
channelOptions.channel.game	String	False	The new game of the channel
channelOptions.channel.delay	Number	False	The delay of the channel
callback	requestCallback	False	The callback that will manage the response

resetStreamKey (Function)

Resets channel's stream key.

API endpoint: DELETE /channels/:channel/stream_key

resetStreamKey(channel, accessToken, callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
accessToken	String	False	The token representing the authenticated user
callback	requestCallback	False	The callback that will manage the response

startCommercial (Function)

Start commercial on channel.

API endpoint: POST /channels/:channel/commercial

startCommercial(channel, accessToken, [parameters], callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
accessToken	String	False	The token representing the authenticated user
parameters	Object	True	The parameters of the request
parameters.length	Number	True	The length of the commercial break in seconds. One of 30, 60, 90, 120, 150 or 180. Defaults to 30.
callback	requestCallback	False	The callback that will manage the response

getChannelTeams (Function)

Returns a list of team objects channel belongs to.

API endpoint: GET /channels/:channel/teams

getChannelTeams(channel, callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
callback	requestCallback	False	The callback that will manage the response

getChannelChat (Function)

Returns a links object to all other chat endpoints.

API endpoint: GET /chat/:channel

getChannelChat(channel, callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
callback	requestCallback	False	The callback that will manage the response

getEmoticons (Function)

Returns a list of all emoticon objects for Twitch.

API endpoint: GET /chat/emoticons

getEmoticons(callback);

Params

Name	Type	Optional	Description
callback	requestCallback	False	The callback that will manage the response

getChannelBadges (Function)

Returns a list of chat badges that can be used in the channel's chat.

API endpoint: GET /chat/:channel/badges

getChannelBadges(channel, callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
callback	requestCallback	False	The callback that will manage the response

getChannelFollows (Function)

Returns a list of follow objects.

API endpoint: GET /channels/:channel/follows

getChannelFollows(channel, [parameters], callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
parameters	Object	True	The parameters of the request
parameters.limit	Number	True	Maximum number of follow objects. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
parameters.direction	String	True	Creation date sorting direction. Defaults to desc. Valid values are asc and desc.
callback	requestCallback	False	The callback that will manage the response

getUserFollowedChannels (Function)

Returns a list of follow objects

API endpoint: GET /users/:user/follows/channels

getUserFollowedChannels(user, [parameters], callback);

Params

Name	Type	Optional	Description
user	String	False	The user name
parameters	Object	True	The parameters of the request
parameters.limit	Number	True	Maximum number of follow objects. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
parameters.direction	String	True	Creation date sorting direction. Defaults to desc. Valid values are asc and desc.
parameters.sortby	String	True	Sort key. Defaults to created_at. Valid values are created_at, last_broadcast, and login. Defaults to desc. Valid values are asc and desc.
callback	requestCallback	False	The callback that will manage the response

getUserFollowsChannel (Function)

Returns a follow object if user is following channel, 404 otherwise.

API endpoint: GET /users/:user/follows/channels/:target

getUserFollowsChannel(user, channel, callback);

Params

Name	Type	Optional	Description
user	String	False	The user name
channel	String	False	The channel name
callback	requestCallback	False	The callback that will manage the response

userFollowChannel (Function)

Adds user to channel's followers.

API endpoint: PUT /users/:user/follows/channels/:target

userFollowChannel(user, channel, accessToken, [parameters], callback);

Params

Name	Type	Optional	Description
user	String	False	The user name
channel	String	False	The channel name
accessToken	String	False	The token representing the authenticated user
parameters	Object	True	The parameters of the request
parameters.notifications	boolean	True	Whether user should receive notifications when channel goes live. Defaults to false.
callback	requestCallback	False	The callback that will manage the response

userUnfollowChannel (Function)

Removes user from channel's followers.

API endpoint: DELETE /users/:user/follows/channels/:target

userUnfollowChannel(user, channel, accessToken, callback);

Params

Name	Type	Optional	Description
user	String	False	The user name
channel	String	False	The channel name
accessToken	String	False	The token representing the authenticated user
callback	requestCallback	False	The callback that will manage the response

getTopGames (Function)

Returns a list of games objects sorted by number of current viewers on Twitch, most popular first.

API endpoint: GET /games/top

getTopGames([parameters], callback);

Params

Name	Type	Optional	Description
parameters	Object	True	The parameters of the request
parameters.limit	Number	True	Maximum number of games. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
callback	requestCallback	False	The callback that will manage the response

getIngests (Function)

Returns a list of ingest objects.

API endpoint: GET /ingests/

getIngests(callback);

Params

Name	Type	Optional	Description
callback	requestCallback	False	The callback that will manage the response

getRoot (Function)

Basic information about the API and authentication status. If you are accessToken is provided, the response includes the status of your token and links to other related resources.

API endpoint: GET /

getRoot([accessToken], callback);

Params

Name	Type	Optional	Description
accessToken	String	True	The token representing the authenticated user
callback	requestCallback	False	The callback that will manage the response

searchChannels (Function)

Returns a list of channel objects matching the search query.

API endpoint: GET /search/channels

searchChannels(parameters, callback);

Params

Name	Type	Optional	Description
parameters	Object	False	The parameters of the request
parameters.query	String	False	Search query. The field can also be parameters.q
parameters.limit	Number	True	Maximum number of channel objects. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
callback	requestCallback	False	The callback that will manage the response

searchStreams (Function)

Returns a list of stream objects matching the search query.

API endpoint: GET /search/streams

searchStreams(parameters, callback);

Params

Name	Type	Optional	Description
parameters	Object	False	The parameters of the request
parameters.query	String	False	Search query. The field can also be parameters.q
parameters.limit	Number	True	Maximum number of stream objects. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
parameters.hls	boolean	True	If set to true, only returns streams using HLS. If set to false, only returns streams that are non-HLS.
callback	requestCallback	False	The callback that will manage the response

searchGames (Function)

Returns a list of game objects matching the search query.

API endpoint: GET /search/games

searchGames(parameters, callback);

Params

Name	Type	Optional	Description
parameters	Object	False	The parameters of the request
parameters.query	String	False	Search query. The field can also be parameters.q
parameters.type	String	False	Only accepts suggest: Suggests a list of games similar to query
parameters.live	boolean	True	If true, only returns games that are live on at least one channel.
callback	requestCallback	False	The callback that will manage the response

getChannelStream (Function)

Returns a stream object if live.

API endpoint: GET /streams/:channel/

getChannelStream(channel, callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
callback	requestCallback	False	The callback that will manage the response

getStreams (Function)

Returns a list of stream objects that are queried by a number of parameters sorted by number of viewers descending.

API endpoint: GET /streams

getStreams([parameters], callback);

Params

Name	Type	Optional	Description
parameters	Object	True	The parameters of the request
parameters.game	String	True	Streams categorized under game.
parameters.channel	String	True	Streams from a comma separated list of channels.
parameters.limit	Number	True	Maximum number of streams. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
parameters.client_id	String	True	Only shows streams from applications of client_id.
callback	requestCallback	False	The callback that will manage the response

getFeaturedStreams (Function)

Returns a list of featured (promoted) stream objects.

API endpoint: GET /streams/featured

getFeaturedStreams([parameters], callback);

Params

Name	Type	Optional	Description
parameters	Object	True	The parameters of the request
parameters.limit	Number	True	Maximum number of streams. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
callback	requestCallback	False	The callback that will manage the response

getStreamsSummary (Function)

Returns a summary of current streams.

API endpoint: GET /streams/summary

getStreamsSummary([parameters], callback);

Params

Name	Type	Optional	Description
parameters	Object	True	The parameters of the request
parameters.game	String	True	Streams categorized under game.
callback	requestCallback	False	The callback that will manage the response

getChannelSubscriptions (Function)

Returns a list of subscription objects sorted by subscription relationship creation date which contain users subscribed to channel.

API endpoint: GET /channels/:channel/subscriptions

getChannelSubscriptions(channel, accessToken, [parameters]);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
accessToken	String	False	The token representing the authenticated user
parameters	Object	True	The parameters of the request
parameters.limit	Number	True	Maximum number of subscription objects. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
parameters.direction	String	True	Creation date sorting direction. Defaults to asc. Valid values are asc and desc.

getUserSubscriptionToChannel (Function)

Returns a subscription object which includes the user if that user is subscribed. Requires authentication for channel. The authenticated user must be the owner of the channel

API endpoint: GET /channels/:channel/subscriptions/:user

getUserSubscriptionToChannel(user, channel, accessToken, callback);

Params

Name	Type	Optional	Description
user	String	False	The user name
channel	String	False	The channel name
accessToken	String	False	The token representing the authenticated user
callback	requestCallback	False	The callback that will manage the response

getChannelSubscriptionOfUser (Function)

Returns a channel object that user subscribes to. user must be authenticated by accessToken.

API endpoint: GET /users/:user/subscriptions/:channel

getChannelSubscriptionOfUser(user, channel, accessToken, callback);

Params

Name	Type	Optional	Description
user	String	False	The user name
channel	String	False	The channel name
accessToken	String	False	The token representing the authenticated user
callback	requestCallback	False	The callback that will manage the response

getTeams (Function)

Returns a list of active teams.

API endpoint: GET /teams/

getTeams([parameters], callback);

Params

Name	Type	Optional	Description
parameters	Object	True	The parameters of the request
parameters.limit	Number	True	Maximum number of teams. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
callback	requestCallback	False	The callback that will manage the response

getTeam (Function)

Returns a team object for team.

API endpoint: GET /teams/:team/

getTeam(team, callback);

Params

Name	Type	Optional	Description
team	String	False	The team name
callback	requestCallback	False	The callback that will manage the response

getUser (Function)

Returns a user object.

API endpoint: GET /users/:user

getUser(user, callback);

Params

Name	Type	Optional	Description
user	String	False	The user name of the user
callback	requestCallback	False	The callback that will manage the response

getAuthenticatedUser (Function)

Returns a user object that represents the user authenticated by accessToken . API endpoint: GET /user

getAuthenticatedUser(accessToken, callback);

Params

Name	Type	Optional	Description
accessToken	String	False	The token representing the authenticated user
callback	requestCallback	False	The callback that will manage the response

getAuthenticatedUserFollowedStreams (Function)

Returns a list of stream objects that the authenticated user is following.

API endpoint: GET /streams/followed

getAuthenticatedUserFollowedStreams(accessToken, [parameters], callback);

Params

Name	Type	Optional	Description
accessToken	String	False	The token representing the authenticated user
parameters	Object	True	The parameters of the request
parameters.limit	Number	True	Maximum number of streams. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
parameters.stream_type	String	True	Only shows streams from a certain type. Permitted values: all, playlist, live
callback	requestCallback	False	The callback that will manage the response

getAuthenticatedUserFollowedVideos (Function)

Returns a list of video objects from channels that the authenticated user is following.

API endpoint: GET /videos/followed

getAuthenticatedUserFollowedVideos(accessToken, [parameters], callback);

Params

Name	Type	Optional	Description
accessToken	String	False	The token representing the authenticated user
parameters	Object	True	The parameters of the request
parameters.limit	Number	True	Maximum number of videos. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
callback	requestCallback	False	The callback that will manage the response

getVideo (Function)

Returns a video object.

API endpoint: GET /videos/:id

getVideo(videoId, callback);

Params

Name	Type	Optional	Description
videoId	String	False	The id of the video
callback	requestCallback	False	The callback that will manage the response

getTopVideos (Function)

Returns a list of videos created in a given time period sorted by number of views, most popular first.

API endpoint: GET /videos/top

getTopVideos([parameters], callback);

Params

Name	Type	Optional	Description
parameters	Object	True	The parameters of the request
parameters.limit	Number	True	Maximum number of videos. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
parameters.game	String	True	Returns only videos from game.
parameters.period	String	True	Returns only videos created in time period. Valid values are week, month, or all. Defaults to week.
callback	requestCallback	False	The callback that will manage the response

getChannelVideos (Function)

Returns a list of videos ordered by time of creation, starting with the most recent from channel.

API endpoint: GET /channels/:channel/videos

getChannelVideos(channel, [parameters], callback);

Params

Name	Type	Optional	Description
channel	String	False	The channel name
parameters	Object	True	The parameters of the request
parameters.limit	Number	True	Maximum number of videos. Maximum is 100, defaults to 25
parameters.offset	Number	True	Follow object offset for pagination. Defaults to 0
parameters.broadcasts	boolean	True	Returns only broadcasts when true, only highlights when false. Defaults to false.
parameters.hls	boolean	True	If set to true, only returns streams using HLS. If set to false, only returns streams that are non-HLS.
callback	requestCallback	False	The callback that will manage the response