twitch-api

    0.5.0 • 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

    Install

    npm i twitch-api

    DownloadsWeekly Downloads

    8

    Version

    0.5.0

    License

    MIT

    Last publish

    Collaborators

    • avatar