@livescale/twitch-api

5.0.4 • Public • Published

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

Package Sidebar

Install

npm i @livescale/twitch-api

Weekly Downloads

1

Version

5.0.4

License

MIT

Unpacked Size

69.2 kB

Total Files

5

Last publish

Collaborators

  • mgara
  • maktouch