Twitch-Helix-API

About

Twitch-Helix-API is a NPM library designed to make use of the Twitch Helix API version easier. It currently covers the following endpoints:

• Get Access Token (Kraken Endpoint)
• Get Games
• Get Streams
• Get Streams Metadata
• Get Users
• Get User Follows
• Update User
• Get Videos

Webhooks are not supported in this library unforuntately.

Issues

If you have a suggestion or have discovered a bug relating to this library, please create an issue here. Ensure you are as descriptive as possible.

Contributions

You may contribute to this library if you wish to. Please create a pull request to do so.

Installation

Install with NPM:

npm install --save twitch-helix-api

Documentation & Usage

Begin by importing the library and setting a Client ID. Example:

var api = require("twitch-helix-api");

api.clientID = "XXXXXXXXXXXXXXXXXXXXX";

Requests

Authentication

Get Access Token

Usage:

api.authentication.getAccessToken({ ... }).then(function(data) {
    ...
});

This request requires you to have already received an authorization code from Twitch. Refer to the Twitch documentation if you do not know how to do this.

You must send all of these parameters in the object:

|Name|Type|Description| |--- |--- |--- | |client_id|string|Your client ID.| |client_secret|string|Your client secret.| |redirect_uri|string|Your registered redirect URI. This must exactly match the redirect URI registered.| |code|string|Your authorization code sent by Twitch.|

You may send these optional parameters in the object:

|Name|Type|Description| |--- |--- |--- | |state|string|Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response.|

Check Token

api.authentication.checkToken({ ... }).then(function(data) {
    ...
});

This request requires you to have an access token.

|Name|Type|Description| |--- |--- |--- | |token|string|Your access token from Twitch.|

Games

Get Games

Usage:

api.games.getGames({ ... }).then(function(data) {
    ...
});

This request accepts no authentication.

This request requires no parameters.

You may send these optional parameters in the object:

|Name|Type|Description| |--- |--- |--- | |id|string|Game ID. At most 100 id values can be specified.| |name|string|Game name. The name must be an exact match. For instance, "Pokemon" will not return a list of Pokemon games; instead, query the specific Pokemon game(s) in which you are interested. At most 100 name values can be specified.|

Streams

Get Streams

Usage:

api.streams.getStreams({ ... }).then(function(data) {
    ...
});

This request accepts no authentication.

This request requires no parameters.

You may send these optional parameters in the object:

|Name|Type|Description| |--- |--- |--- | |after|string|Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.| |before|string|Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response.| |community_id|string|Returns streams in a specified community ID. You can specify up to 100 IDs.| |first|integer|Maximum number of objects to return. Maximum: 100. Default: 20.| |game_id|string|Returns streams broadcasting a specified game ID. You can specify up to 100 IDs.| |language|string|Stream language. You can specify up to 100 languages.| |type|string|Stream type: "all", "live", "vodcast". Default: "all".| |user_id|string|Returns streams broadcast by one or more specified user IDs. You can specify up to 100 IDs.| |user_login|string|Returns streams broadcast by one or more specified user login names. You can specify up to 100 names.|

Get Streams Metadata

Usage:

api.streams.getStreamsMetadata({ ... }).then(function(data) {
    ...    ...
});

This request accepts no authentication.

This request requires no parameters.

You may send these optional parameters in the object:

|Name|Type|Description| |--- |--- |--- | |after|string|Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.| |before|string|Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response.| |community_id|string|Returns streams in a specified community ID. You can specify up to 100 IDs.| |first|integer|Maximum number of objects to return. Maximum: 100. Default: 20.| |game_id|string|Returns streams broadcasting a specified game ID. You can specify up to 100 IDs.| |language|string|Stream language. You can specify up to 100 languages.| |type|string|Stream type: "all", "live", "vodcast". Default: "all".| |user_id|string|Returns streams broadcast by one or more specified user IDs. You can specify up to 100 IDs.| |user_login|string|Returns streams broadcast by one or more specified user login names. You can specify up to 100 names.|

Users

Get Users

Usage:

api.users.getUsers({ ... }).then(function(data) {
    ...
});

This request requires no authentication, but accepts the user:read:email to send en email address.

You must send one or more of these parameters in the object:

|Name|Type|Description| |--- |--- |--- | |ìd|string|User ID. Multiple user IDs can be specified. Limit: 100.| |login|string|User login name. Multiple login names can be specified. Limit: 100.|

This request has no optional parameters.

Get Users Follows

Usage:

api.users.getUsersFollows({ ... }).then(function(data) {
    ...
});

This request accepts no authentication.

You must send one or more of these parameters in the object:

|Name|Type|Description| |--- |--- |--- | |from_id|string|User ID. The request returns information about users who are being followed by the from_id user.| |to_id|string|User ID. The request returns information about users who are following the to_id user.|

You may send these optional parameters in the object:

|Name|Type|Description| |--- |--- |--- | |after|string|Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.| |before|string|Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response.| |first|integer|Maximum number of objects to return. Maximum: 100. Default: 20.|

Update Users

Usage:

api.users.updateUsers({ ... }).then(function(data) {
    ...
});

This request requires authentication. The user:edit scope is required.

You must send one or more of these parameters in the object:

|Name|Type|Description| |--- |--- |--- | |description|string|New user description: used to set the new description for the user.|

This request has no optional parameters.

Videos

Get Videos

Usage:

api.videos.getVideos({ ... }).then(function(data) {
    ...
});

This request accepts no authentication.

You must send one or more of these parameters in the object:

|Name|Type|Description| |--- |--- |--- | |id|string|ID of the video being queried. Limit: 100. If this is specified, you cannot use any of the optional query string parameters below.| |user_id|string|ID of the user who owns the video. Limit 1.| |game_id|string|ID of the game the video is of. Limit 1.|

You may send these optional parameters in the object:

|Name|Type|Description| |--- |--- |--- | |after|string|Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.| |before|string|Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response.| |first|string|Number of values to be returned when getting videos by user or game ID. Limit: 100. Default: 20.| |language|string|Language of the video being queried. Limit: 1.| |period|string|Period during which the video was created. Valid values: "all", "day", "month", and "week". Default: "all".| |sort|string|Sort order of the videos. Valid values: "time", "trending", and "views". Default: "time".| |type|string|Type of video. Valid values: "all", "upload", "archive", and "highlight". Default: "all".|

Responses

All requests made will return a custom payload object containing the data you requested along with other useful information.

Example successful response:

{ 
    code: 200,
    status: "success",
    message: "OK",
    response: ...
}

Example error response:

{
    code: 400,
    status: "bad_request",
    message: ...,
    response: null
}

The message field will describe the exact error you have made.

The response field will contain whatever data Twitch sends as a response to your request.