Twitch API Reference
Resource | Endpoint | Description |
---|---|---|
Ads | Start Commercial | Starts a commercial on the specified channel. |
Ads | Get Ad Schedule | Returns ad schedule related information. |
Ads | Snooze Next Ad | Pushes back the timestamp of the upcoming automatic mid-roll ad by 5 minutes. |
Analytics | Get Extension Analytics | Gets an analytics report for one or more extensions. |
Analytics | Get Game Analytics | Gets an analytics report for one or more games. |
Bits | Get Bits Leaderboard | Gets the Bits leaderboard for the authenticated broadcaster. |
Bits | Get Cheermotes | Gets a list of Cheermotes that users can use to cheer Bits. |
Bits | Get Extension Transactions | Gets an extension’s list of transactions. |
Channels | Get Channel Information | Gets information about one or more channels. |
Channels | Modify Channel Information | Updates a channel’s properties. |
Channels | Get Channel Editors | Gets the broadcaster’s list editors. |
Channels | Get Followed Channels | Gets a list of broadcasters that the specified user follows. You can also use this endpoint to see whether a user follows a specific broadcaster. |
Channels | Get Channel Followers | Gets a list of users that follow the specified broadcaster. You can also use this endpoint to see whether a specific user follows the broadcaster. |
Channel Points | Create Custom Rewards | Creates a Custom Reward in the broadcaster’s channel. |
Channel Points | Delete Custom Reward | Deletes a custom reward that the broadcaster created. |
Channel Points | Get Custom Reward | Gets a list of custom rewards that the specified broadcaster created. |
Channel Points | Get Custom Reward Redemption | Gets a list of redemptions for a custom reward. |
Channel Points | Update Custom Reward | Updates a custom reward. |
Channel Points | Update Redemption Status | Updates a redemption’s status. |
Charity | Get Charity Campaign | Gets information about the broadcaster’s active charity campaign. |
Charity | Get Charity Campaign Donations | Gets the list of donations that users have made to the broadcaster’s active charity campaign. |
Chat | Get Chatters | Gets the list of users that are connected to the broadcaster’s chat session. |
Chat | Get Channel Emotes | Gets the broadcaster’s list of custom emotes. |
Chat | Get Global Emotes | Gets all global emotes. |
Chat | Get Emote Sets | Gets emotes for one or more specified emote sets. |
Chat | Get Channel Chat Badges | Gets the broadcaster’s list of custom chat badges. |
Chat | Get Global Chat Badges | Gets Twitch’s list of chat badges. |
Chat | Get Chat Settings | Gets the broadcaster’s chat settings. |
Chat | Get Shared Chat Session | NEW Retrieves the active shared chat session for a channel. |
Chat | Get User Emotes | NEW Retrieves emotes available to the user across all channels. |
Chat | Update Chat Settings | Updates the broadcaster’s chat settings. |
Chat | Send Chat Announcement | Sends an announcement to the broadcaster’s chat room. |
Chat | Send a Shoutout | Sends a Shoutout to the specified broadcaster. |
Chat | Send Chat Message | NEW Sends a message to the broadcaster’s chat room. |
Chat | Get User Chat Color | Gets the color used for the user’s name in chat. |
Chat | Update User Chat Color | Updates the color used for the user’s name in chat. |
Clips | Create Clip | Creates a clip from the broadcaster’s stream. |
Clips | Get Clips | Gets one or more video clips. |
Conduits | Get Conduits | NEW Gets the conduits for a client ID. |
Conduits | Create Conduits | NEW Creates a new conduit. |
Conduits | Update Conduits | NEW Updates a conduit’s shard count. |
Conduits | Delete Conduit | NEW Deletes a specified conduit. |
Conduits | Get Conduit Shards | NEW Gets a lists of all shards for a conduit. |
Conduits | Update Conduit Shards | NEW Updates shard(s) for a conduit. |
CCLs | Get Content Classification Labels | Gets information about Twitch content classification labels. |
Entitlements | Get Drops Entitlements | Gets an organization’s list of entitlements that have been granted to a game, a user, or both. |
Entitlements | Update Drops Entitlements | Updates the Drop entitlement’s fulfillment status. |
Extensions | Get Extension Configuration Segment | Gets the specified configuration segment from the specified extension. |
Extensions | Set Extension Configuration Segment | Updates a configuration segment. |
Extensions | Set Extension Required Configuration | Updates the extension’s required_configuration string. |
Extensions | Send Extension PubSub Message | Sends a message to one or more viewers. |
Extensions | Get Extension Live Channels | Gets a list of broadcasters that are streaming live and have installed or activated the extension. |
Extensions | Get Extension Secrets | Gets an extension’s list of shared secrets. |
Extensions | Create Extension Secret | Creates a shared secret used to sign and verify JWT tokens. |
Extensions | Send Extension Chat Message | Sends a message to the specified broadcaster’s chat room. |
Extensions | Get Extensions | Gets information about an extension. |
Extensions | Get Released Extensions | Gets information about a released extension. |
Extensions | Get Extension Bits Products | Gets the list of Bits products that belongs to the extension. |
Extensions | Update Extension Bits Product | Adds or updates a Bits product that the extension created. |
EventSub | Create EventSub Subscription | Creates an EventSub subscription. |
EventSub | Delete EventSub Subscription | Deletes an EventSub subscription. |
EventSub | Get EventSub Subscriptions | Gets a list of EventSub subscriptions that the client in the access token created. |
Games | Get Top Games | Gets information about all broadcasts on Twitch. |
Games | Get Games | Gets information about specified games. |
Goals | Get Creator Goals | Gets the broadcaster’s list of active goals. |
Guest Star | Get Channel Guest Star Settings | BETA Gets the channel settings for configuration of the Guest Star feature for a particular host. |
Guest Star | Update Channel Guest Star Settings | BETA Mutates the channel settings for configuration of the Guest Star feature for a particular host. |
Guest Star | Get Guest Star Session | BETA Gets information about an ongoing Guest Star session for a particular channel. |
Guest Star | Create Guest Star Session | BETA Programmatically creates a Guest Star session on behalf of the broadcaster. |
Guest Star | End Guest Star Session | BETA Programmatically ends a Guest Star session on behalf of the broadcaster. |
Guest Star | Get Guest Star Invites | BETA Provides the caller with a list of pending invites to a Guest Star session. |
Guest Star | Send Guest Star Invite | BETA Sends an invite to a specified guest on behalf of the broadcaster for a Guest Star session in progress. |
Guest Star | Delete Guest Star Invite | BETA Revokes a previously sent invite for a Guest Star session. |
Guest Star | Assign Guest Star Slot | BETA Allows a previously invited user to be assigned a slot within the active Guest Star session. |
Guest Star | Update Guest Star Slot | BETA Allows a user to update the assigned slot for a particular user within the active Guest Star session. |
Guest Star | Delete Guest Star Slot | BETA Allows a caller to remove a slot assignment from a user participating in an active Guest Star session. |
Guest Star | Update Guest Star Slot Settings | BETA Allows a user to update slot settings for a particular guest within a Guest Star session. |
Hype Train | Get Hype Train Events | Gets information about the broadcaster’s current or most recent Hype Train event. |
Moderation | Check AutoMod Status | Checks whether AutoMod would flag the specified message for review. |
Moderation | Manage Held AutoMod Messages | Allow or deny the message that AutoMod flagged for review. |
Moderation | Get AutoMod Settings | Gets the broadcaster’s AutoMod settings. |
Moderation | Update AutoMod Settings | Updates the broadcaster’s AutoMod settings. |
Moderation | Get Banned Users | Gets all users that the broadcaster banned or put in a timeout. |
Moderation | Ban User | Bans a user from participating in a broadcaster’s chat room or puts them in a timeout. |
Moderation | Unban User | Removes the ban or timeout that was placed on the specified user. |
Moderation | Get Unban Requests | NEW Gets a list of unban requests for a broadcaster’s channel. |
Moderation | Resolve Unban Requests | NEW Resolves an unban request by approving or denying it. |
Moderation | Get Blocked Terms | Gets the broadcaster’s list of non-private, blocked words or phrases. |
Moderation | Add Blocked Term | Adds a word or phrase to the broadcaster’s list of blocked terms. |
Moderation | Remove Blocked Term | Removes the word or phrase from the broadcaster’s list of blocked terms. |
Moderation | Delete Chat Messages | Removes a single chat message or all chat messages from the broadcaster’s chat room. |
Moderation | Get Moderated Channels | Gets a list of channels that the specified user has moderator privileges in. |
Moderation | Get Moderators | Gets all users allowed to moderate the broadcaster’s chat room. |
Moderation | Add Channel Moderator | Adds a moderator to the broadcaster’s chat room. |
Moderation | Remove Channel Moderator | Removes a moderator from the broadcaster’s chat room. |
Moderation | Get VIPs | Gets a list of the broadcaster’s VIPs. |
Moderation | Add Channel VIP | Adds the specified user as a VIP in the broadcaster’s channel. |
Moderation | Remove Channel VIP | Removes the specified user as a VIP in the broadcaster’s channel. |
Moderation | Update Shield Mode Status | Activates or deactivates the broadcaster’s Shield Mode. |
Moderation | Get Shield Mode Status | Gets the broadcaster’s Shield Mode activation status. |
Moderation | Warn Chat User | NEW Warns a user in the specified broadcaster’s chat room, preventing them from chat interaction until the warning is acknowledged. |
Polls | Get Polls | Gets a list of polls that the broadcaster created. |
Polls | Create Poll | Creates a poll that viewers in the broadcaster’s channel can vote on. |
Polls | End Poll | End an active poll. |
Predictions | Get Predictions | Gets a list of Channel Points Predictions that the broadcaster created. |
Predictions | Create Prediction | Create a Channel Points Prediction. |
Predictions | End Prediction | Locks, resolves, or cancels a Channel Points Prediction. |
Raids | Start a raid | Raid another channel by sending the broadcaster’s viewers to the targeted channel. |
Raids | Cancel a raid | Cancel a pending raid. |
Schedule | Get Channel Stream Schedule | Gets the broadcaster’s streaming schedule. |
Schedule | Get Channel iCalendar | Gets the broadcaster’s streaming schedule as an iCalendar. |
Schedule | Update Channel Stream Schedule | Updates the broadcaster’s schedule settings, such as scheduling a vacation. |
Schedule | Create Channel Stream Schedule Segment | Adds a single or recurring broadcast to the broadcaster’s streaming schedule. |
Schedule | Update Channel Stream Schedule Segment | Updates a scheduled broadcast segment. |
Schedule | Delete Channel Stream Schedule Segment | Deletes a broadcast from the broadcaster’s streaming schedule. |
Search | Search Categories | Gets the games or categories that match the specified query. |
Search | Search Channels | Gets the channels that match the specified query and have streamed content within the past 6 months. |
Streams | Get Stream Key | Gets the channel’s stream key. |
Streams | Get Streams | Gets a list of all streams. |
Streams | Get Followed Streams | Gets the list of broadcasters that the user follows and that are streaming live. |
Streams | Create Stream Marker | Adds a marker to a live stream. |
Streams | Get Stream Markers | Gets a list of markers from the user’s most recent stream or from the specified VOD/video. |
Subscriptions | Get Broadcaster Subscriptions | Gets a list of users that subscribe to the specified broadcaster. |
Subscriptions | Check User Subscription | Checks whether the user subscribes to the broadcaster’s channel. |
Tags | Get All Stream Tags | Gets the list of all stream tags that Twitch defines. You can also filter the list by one or more tag IDs. |
Tags | Get Stream Tags | Gets the list of stream tags that the broadcaster or Twitch added to their channel. |
Teams | Get Channel Teams | Gets the list of Twitch teams that the broadcaster is a member of. |
Teams | Get Teams | Gets information about the specified Twitch team. |
Users | Get Users | Gets information about one or more users. |
Users | Update User | Updates the user’s information. |
Users | Get User Block List | Gets the list of users that the broadcaster has blocked. |
Users | Block User | Blocks the specified user from interacting with or having contact with the broadcaster. |
Users | Unblock User | Removes the user from the broadcaster’s list of blocked users. |
Users | Get User Extensions | Gets a list of all extensions (both active and inactive) that the broadcaster has installed. |
Users | Get User Active Extensions | Gets the active extensions that the broadcaster has installed for each configuration. |
Users | Update User Extensions | Updates an installed extension’s information. |
Videos | Get Videos | Gets information about one or more published videos. |
Videos | Delete Videos | Deletes one or more videos. |
Whispers | Send Whisper | Sends a whisper message to the specified user. |
Start Commercial
✎Starts a commercial on the specified channel.
NOTE: Only partners and affiliates may run commercials and they must be streaming live at the time.
NOTE: Only the broadcaster may start a commercial; the broadcaster’s editors and moderators may not start commercials on behalf of the broadcaster.
Authorization
Requires a user access token that includes the channel:edit:commercial scope.
URL
POST https://api.twitch.tv/helix/channels/commercial
Request Body
Field | Type | Description |
---|---|---|
broadcaster_id | String | The ID of the partner or affiliate broadcaster that wants to run the commercial. This ID must match the user ID found in the OAuth token. |
length | Integer | The length of the commercial to run, in seconds. Twitch tries to serve a commercial that’s the requested length, but it may be shorter or longer. The maximum length you should request is 180 seconds. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | An array that contains a single object with the status of your start commercial request. |
length | Integer | The length of the commercial you requested. If you request a commercial that’s longer than 180 seconds, the API uses 180 seconds. |
message | String | A message that indicates whether Twitch was able to serve an ad. |
retry_after | Integer | The number of seconds you must wait before running another commercial. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully started the commercial. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
429 Too Many Requests |
|
Example Request
This request starts a commercial.
curl -X POST 'https://api.twitch.tv/helix/channels/commercial' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{
"broadcaster_id": "41245072",
"length": 60
}'
Example Response
{
"data": [
{
"length" : 60,
"message" : "",
"retry_after" : 480
}
]
}
Get Ad Schedule
✎This endpoint returns ad schedule related information, including snooze, when the last ad was run, when the next ad is scheduled, and if the channel is currently in pre-roll free time. Note that a new ad cannot be run until 8 minutes after running a previous ad.
Authorization
Requires a user access token that includes the channel:read:ads scope. The user_id
in the user access token must match the broadcaster_id
.
URL
GET https://api.twitch.tv/helix/channels/ads
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | Provided broadcaster_id must match the user_id in the auth token. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains information related to the channel’s ad schedule. |
snooze_count | Integer | The number of snoozes available for the broadcaster. |
snooze_refresh_at | String | The UTC timestamp when the broadcaster will gain an additional snooze, in RFC3339 format. |
next_ad_at | String | The UTC timestamp of the broadcaster’s next scheduled ad, in RFC3339 format. Empty if the channel has no ad scheduled or is not live. |
duration | Integer | The length in seconds of the scheduled upcoming ad break. |
last_ad_at | String | The UTC timestamp of the broadcaster’s last ad-break, in RFC3339 format. Empty if the channel has not run an ad or is not live. |
preroll_free_time | Integer | The amount of pre-roll free time remaining for the channel in seconds. Returns 0 if they are currently not pre-roll free. |
Response Codes
Code | Description |
---|---|
200 OK | Returns the ad schedule information for the channel. |
400 Bad Request | The broadcaster ID is not valid. |
500 Internal Server Error |
Example Request
Snooze the next ad.
curl -X GET 'https://api.twitch.tv/helix/channels/ads?broadcaster_id=123' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"next_ad_at" : "2023-08-01T23:08:18+00:00",
"last_ad_at" : "2023-08-01T23:08:18+00:00",
"duration" : "60",
"preroll_free_time" : "90",
"snooze_count" : "1",
"snooze_refresh_at" : "2023-08-01T23:08:18+00:00",
},
],
}
Snooze Next Ad
✎If available, pushes back the timestamp of the upcoming automatic mid-roll ad by 5 minutes. This endpoint duplicates the snooze functionality in the creator dashboard’s Ads Manager.
Authorization
Requires a user access token that includes the channel:manage:ads scope. The user_id
in the user access token must match the broadcaster_id
.
URL
POST https://api.twitch.tv/helix/channels/ads/schedule/snooze
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | Provided broadcaster_id must match the user_id in the auth token. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains information about the channel’s snoozes and next upcoming ad after successfully snoozing. |
snooze_count | Integer | The number of snoozes available for the broadcaster. |
snooze_refresh_at | String | The UTC timestamp when the broadcaster will gain an additional snooze, in RFC3339 format. |
next_ad_at | String | The UTC timestamp of the broadcaster’s next scheduled ad, in RFC3339 format. |
Response Codes
Code | Description |
---|---|
200 OK | User’s next ad is successfully snoozed. Their snooze_count is decremented and snooze_refresh_time and next_ad_at are both updated. |
400 Bad Request |
|
429 Too Many Requests | Channel has no snoozes left. |
500 Internal Server Error |
Example Request
Snooze the next ad.
curl -X POST 'https://api.twitch.tv/helix/channels/ads/schedule/snooze?broadcaster_id=123' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"snooze_count" : "1",
"snooze_refresh_at" : "2023-08-01T23:08:18+00:00",
"next_ad_at" : "2023-08-01T23:08:18+00:00",
},
],
}
Get Extension Analytics
✎Gets an analytics report for one or more extensions. The response contains the URLs used to download the reports (CSV files). Learn More
Authorization
Requires a user access token that includes the analytics:read:extensions scope.
URL
GET https://api.twitch.tv/helix/analytics/extensions
Request Query Parameters
Name | Type | Required? | Description |
---|---|---|---|
extension_id | String | No | The extension's client ID. If specified, the response contains a report for the specified extension. If not specified, the response includes a report for each extension that the authenticated user owns. |
type | String | No | The type of analytics report to get. Possible values are:
|
started_at | String | No | The reporting window's start date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z). The start date must be on or after January 31, 2018. If you specify an earlier date, the API ignores it and uses January 31, 2018. If you specify a start date, you must specify an end date. If you don't specify a start and end date, the report includes all available data since January 31, 2018. The report contains one row of data for each day in the reporting window. |
ended_at | String | No | The reporting window's end date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-27T00:00:00Z). The report is inclusive of the end date. Specify an end date only if you provide a start date. Because it can take up to two days for the data to be available, you must specify an end date that's earlier than today minus one to two days. If not, the API ignores your end date and uses an end date that is today minus one to two days. |
first | Integer | No | The maximum number of report URLs to return per page in the response. The minimum page size is 1 URL per page and the maximum is 100 URLs per page. The default is 20. NOTE: While you may specify a maximum value of 100, the response will contain at most 20 URLs per page. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More This parameter is ignored if the extension_id parameter is set. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list of reports. The reports are returned in no particular order; however, the data within each report is in ascending order by date (newest first). The report contains one row of data per day of the reporting window; the report contains rows for only those days that the extension was used. The array is empty if there are no reports. |
extension_id | String | An ID that identifies the extension that the report was generated for. |
URL | String | The URL that you use to download the report. The URL is valid for 5 minutes. |
type | String | The type of report. |
date_range | Object | The reporting window’s start and end dates, in RFC3339 format. |
started_at | String | The reporting window’s start date. |
ended_at | String | The reporting window’s end date. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster's analytics reports. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
Example Request
Gets the URLs for all reports for all extensions of the authenticated client. The request was issued on June 1, 2018.
curl -X GET 'https://api.twitch.tv/helix/analytics/extensions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"extension_id": "efgh",
"URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/dynamic/LoL%20ADC...",
"type": "overview_v2",
"date_range": {
"started_at": "2018-03-01T00:00:00Z",
"ended_at": "2018-06-01T00:00:00Z"
}
},
...
],
"pagination": {"cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"}
}
Get Game Analytics
✎Gets an analytics report for one or more games. The response contains the URLs used to download the reports (CSV files). Learn more
Authorization
Requires a user access token that includes the analytics:read:games scope.
URL
GET https://api.twitch.tv/helix/analytics/games
Request Query Parameters
Name | Type | Required? | Description |
---|---|---|---|
game_id | String | No | The game’s client ID. If specified, the response contains a report for the specified game. If not specified, the response includes a report for each of the authenticated user’s games. |
type | String | No | The type of analytics report to get. Possible values are:
|
started_at | String | No | The reporting window’s start date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z). If you specify a start date, you must specify an end date. The start date must be within one year of today’s date. If you specify an earlier date, the API ignores it and uses a date that’s one year prior to today’s date. If you don’t specify a start and end date, the report includes all available data for the last 365 days from today. The report contains one row of data for each day in the reporting window. |
ended_at | String | No | The reporting window’s end date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z). The report is inclusive of the end date. Specify an end date only if you provide a start date. Because it can take up to two days for the data to be available, you must specify an end date that’s earlier than today minus one to two days. If not, the API ignores your end date and uses an end date that is today minus one to two days. |
first | Integer | No | The maximum number of report URLs to return per page in the response. The minimum page size is 1 URL per page and the maximum is 100 URLs per page. The default is 20. NOTE: While you may specify a maximum value of 100, the response will contain at most 20 URLs per page. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More This parameter is ignored if game_id parameter is set. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list of reports. The reports are returned in no particular order; however, the data within each report is in ascending order by date (newest first). The report contains one row of data per day of the reporting window; the report contains rows for only those days that the game was used. A report is available only if the game was broadcast for at least 5 hours over the reporting period. The array is empty if there are no reports. |
game_id | String | An ID that identifies the game that the report was generated for. |
URL | String | The URL that you use to download the report. The URL is valid for 5 minutes. |
type | String | The type of report. |
date_range | Object | The reporting window’s start and end dates, in RFC3339 format. |
started_at | String | The reporting window’s start date. |
ended_at | String | The reporting window’s end date. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s analytics reports. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
Example Request
Gets the URL for a downloadable CSV report for game ID 493057, covering the period January 1, 2018 through March 1, 2018.
curl -X GET 'https://api.twitch.tv/helix/analytics/games?game_id=493057&started_at=2018-01-01T00:00:00Z&ended_at=2018-03-01T00:00:00Z' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"game_id" : "493057",
"URL" : "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/games/66170/overview/15183...",
"type" : "overview_v2",
"date_range" : {
"started_at" : "2018-01-01T00:00:00Z",
"ended_at" : "2018-03-01T00:00:00Z"
}
}
]
}
Example Request
Gets the first 5 URLs for all reports for all games of the authenticated client. The request was issued on June 14, 2018.
curl -X GET 'https://api.twitch.tv/helix/analytics/games?first=5' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"game_id": "9821",
"URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/games/9821/overview/152642...",
"type" : "overview_v2",
"date_range" : {
"started_at" : "2018-03-13T00:00:00Z",
"ended_at" : "2018-06-13T00:00:00Z"
}
},
...
],
"pagination": {"cursor": "eyJiIjpudWxsLJxhIjoiIn0gf5"}
}
Get Bits Leaderboard
✎Gets the Bits leaderboard for the authenticated broadcaster.
Authorization
Requires a user access token that includes the bits:read scope.
URL
GET https://api.twitch.tv/helix/bits/leaderboard
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
count | Integer | No | The number of results to return. The minimum count is 1 and the maximum is 100. The default is 10. |
period | String | No | The time period over which data is aggregated (uses the PST time zone). Possible values are:
|
started_at | String | No | The start date, in RFC3339 format, used for determining the aggregation period. Specify this parameter only if you specify the period query parameter. The start date is ignored if period is all. Note that the date is converted to PST before being used, so if you set the start time to 2022-01-01T00:00:00.0Z and period to month, the actual reporting period is December 2021, not January 2022. If you want the reporting period to be January 2022, you must set the start time to 2022-01-01T08:00:00.0Z or 2022-01-01T00:00:00.0-08:00 .If your start date uses the ‘+’ offset operator (for example, 2022-01-01T00:00:00.0+05:00 ), you must URL encode the start date. |
user_id | String | No | An ID that identifies a user that cheered bits in the channel. If count is greater than 1, the response may include users ranked above and below the specified user. To get the leaderboard’s top leaders, don’t specify a user ID. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list of leaderboard leaders. The leaders are returned in rank order by how much they’ve cheered. The array is empty if nobody has cheered bits. |
user_id | String | An ID that identifies a user on the leaderboard. |
user_login | String | The user’s login name. |
user_name | String | The user’s display name. |
rank | Integer | The user’s position on the leaderboard. |
score | Integer | The number of Bits the user has cheered. |
date_range | Object | The reporting window’s start and end dates, in RFC3339 format. The dates are calculated by using the started_at and period query parameters. If you don’t specify the started_at query parameter, the fields contain empty strings. |
started_at | String | The reporting window’s start date. |
ended_at | String | The reporting window’s end date. |
total | Integer | The number of ranked users in data . This is the value in the count query parameter or the total number of entries on the leaderboard, whichever is less. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s Bits leaderboard. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
Example Request
Gets information about the authenticated broadcaster’s top two Bits leaderboard entries for the specified week.
curl -X GET 'https://api.twitch.tv/helix/bits/leaderboard?count=2&period=week&started_at=2018-02-05T08%3A00%3A00Z' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"user_id": "158010205",
"user_login": "tundracowboy",
"user_name": "TundraCowboy",
"rank": 1,
"score": 12543
},
{
"user_id": "7168163",
"user_login": "topramens",
"user_name": "Topramens",
"rank": 2,
"score": 6900
}
],
"date_range": {
"started_at": "2018-02-05T08:00:00Z",
"ended_at": "2018-02-12T08:00:00Z"
},
"total": 2
}
Get Cheermotes
✎Gets a list of Cheermotes that users can use to cheer Bits in any Bits-enabled channel’s chat room. Cheermotes are animated emotes that viewers can assign Bits to.
URL
GET https://api.twitch.tv/helix/bits/cheermotes
Authorization
Requires an app access token or user access token.
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | No | The ID of the broadcaster whose custom Cheermotes you want to get. Specify the broadcaster’s ID if you want to include the broadcaster’s Cheermotes in the response (not all broadcasters upload Cheermotes). If not specified, the response contains only global Cheermotes. If the broadcaster uploaded Cheermotes, the type field in the response is set to channel_custom. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of Cheermotes. The list is in ascending order by the order field’s value. |
prefix | String | The name portion of the Cheermote string that you use in chat to cheer Bits. The full Cheermote string is the concatenation of {prefix} + {number of Bits}. For example, if the prefix is “Cheer” and you want to cheer 100 Bits, the full Cheermote string is Cheer100. When the Cheermote string is entered in chat, Twitch converts it to the image associated with the Bits tier that was cheered. |
tiers | Object[] | A list of tier levels that the Cheermote supports. Each tier identifies the range of Bits that you can cheer at that tier level and an image that graphically identifies the tier level. |
min_bits | Integer | The minimum number of Bits that you must cheer at this tier level. The maximum number of Bits that you can cheer at this level is determined by the required minimum Bits of the next tier level minus 1. For example, if min_bits is 1 and min_bits for the next tier is 100, the Bits range for this tier level is 1 through 99. The minimum Bits value of the last tier is the maximum number of Bits you can cheer using this Cheermote. For example, 10000. |
id | String | The tier level. Possible tiers are:
|
color | String | The hex code of the color associated with this tier level (for example, #979797). |
images | Dictionary | The animated and static image sets for the Cheermote. The dictionary of images is organized by theme, format, and size. The theme keys are dark and light. Each theme is a dictionary of formats: animated and static. Each format is a dictionary of sizes: 1, 1.5, 2, 3, and 4. The value of each size contains the URL to the image. |
can_cheer | Boolean | A Boolean value that determines whether users can cheer at this tier level. |
show_in_bits_card | Boolean | A Boolean value that determines whether this tier level is shown in the Bits card. Is true if this tier level is shown in the Bits card. |
type | String | The type of Cheermote. Possible values are:
|
order | Integer | The order that the Cheermotes are shown in the Bits card. The numbers may not be consecutive. For example, the numbers may jump from 1 to 7 to 13. The order numbers are unique within a Cheermote type (for example, global_first_party) but may not be unique amongst all Cheermotes in the response. |
last_updated | String | The date and time, in RFC3339 format, when this Cheermote was last updated. |
is_charitable | Boolean | A Boolean value that indicates whether this Cheermote provides a charitable contribution match during charity campaigns. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the Cheermotes. |
401 Unauthorized |
|
Example Requests
Gets a list of all global Cheermotes.
curl -X GET 'https://api.twitch.tv/helix/bits/cheermotes' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Gets a list of all global Cheermotes and any Cheermotes that the broadcaster has uploaded.
curl -X GET 'https://api.twitch.tv/helix/bits/cheermotes?broadcaster_id=41245072' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"prefix": "Cheer",
"tiers": [
{
"min_bits": 1,
"id": "1",
"color": "#979797",
"images": {
"dark": {
"animated": {
"1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/1.gif",
"1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/1.5.gif",
"2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/2.gif",
"3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/3.gif",
"4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/4.gif"
},
"static": {
"1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/1.png",
"1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/1.5.png",
"2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/2.png",
"3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/3.png",
"4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/4.png"
}
},
"light": {
"animated": {
"1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/1.gif",
"1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/1.5.gif",
"2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/2.gif",
"3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/3.gif",
"4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/4.gif"
},
"static": {
"1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/1.png",
"1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/1.5.png",
"2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/2.png",
"3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/3.png",
"4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/4.png"
}
}
},
"can_cheer": true,
"show_in_bits_card": true
}
...
],
"type": "global_first_party",
"order": 1,
"last_updated": "2018-05-22T00:06:04Z",
"is_charitable": false
},
...
]
}
Get Extension Transactions
✎Gets an extension’s list of transactions. A transaction records the exchange of a currency (for example, Bits) for a digital product.
Authorization
Requires an app access token.
URL
GET https://api.twitch.tv/helix/extensions/transactions
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
extension_id | String | Yes | The ID of the extension whose list of transactions you want to get. |
id | String | No | A transaction ID used to filter the list of transactions. Specify this parameter for each transaction you want to get. For example, id=1234&id=5678 . You may specify a maximum of 100 IDs. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of transactions. |
id | String | An ID that identifies the transaction. |
timestamp | String | The UTC date and time (in RFC3339 format) of the transaction. |
broadcaster_id | String | The ID of the broadcaster that owns the channel where the transaction occurred. |
broadcaster_login | String | The broadcaster’s login name. |
broadcaster_name | String | The broadcaster’s display name. |
user_id | String | The ID of the user that purchased the digital product. |
user_login | String | The user’s login name. |
user_name | String | The user’s display name. |
product_type | String | The type of transaction. Possible values are:
|
product_data | Object | Contains details about the digital product. |
sku | String | An ID that identifies the digital product. |
domain | String | Set to twitch.ext. + <the extension's ID> . |
cost | Object | Contains details about the digital product’s cost. |
amount | Integer | The amount exchanged for the digital product. |
type | String | The type of currency exchanged. Possible values are:
|
inDevelopment | Boolean | A Boolean value that determines whether the product is in development. Is true if the digital product is in development and cannot be exchanged. |
displayName | String | The name of the digital product. |
expiration | String | This field is always empty since you may purchase only unexpired products. |
broadcast | Boolean | A Boolean value that determines whether the data was broadcast to all instances of the extension. Is true if the data was broadcast to all instances. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of transactions. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
Example Request
curl -X GET
'https://api.twitch.tv/helix/extensions/transactions?extension_id=1234' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "74c52265-e214-48a6-91b9-23b6014e8041",
"timestamp": "2019-01-28T04:15:53.325Z",
"broadcaster_id": "439964613",
"broadcaster_login": "chikuseuma",
"broadcaster_name": "chikuseuma",
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok",
"product_type": "BITS_IN_EXTENSION",
"product_data": {
"domain": "twitch.ext.uo6dggojyb8d6soh92zknwmi5ej1q2",
"sku": "testSku100",
"cost": {
"amount": 100,
"type": "bits"
},
"inDevelopment": false,
"displayName": "Test Product 100",
"expiration": "",
"broadcast": false
}
},
{
"id": "8d303dc6-a460-4945-9f48-59c31d6735cb",
"timestamp": "2019-01-18T09:10:13.397Z",
"broadcaster_id": "439964613",
"broadcaster_login": "chikuseuma",
"broadcaster_name": "chikuseuma",
"user_id": "439966926",
"user_login": "liscuit",
"user_name": "liscuit",
"product_type": "BITS_IN_EXTENSION",
"product_data": {
"domain": "twitch.ext.uo6dggojyb8d6soh92zknwmi5ej1q2",
"sku": "testSku200",
"cost": {
"amount": 200,
"type": "bits"
},
"inDevelopment": false,
"displayName": "Test Product 200",
"expiration": "",
"broadcast": false
}
},
...
],
"pagination": {
"cursor": "cursorString"
}
}
Get Channel Information
✎Gets information about one or more channels.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/channels
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose channel you want to get. To specify more than one ID, include this parameter for each broadcaster you want to get. For example, broadcaster_id=1234&broadcaster_id=5678 . You may specify a maximum of 100 IDs. The API ignores duplicate IDs and IDs that are not found. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains information about the specified channels. The list is empty if the specified channels weren’t found. |
broadcaster_id | String | An ID that uniquely identifies the broadcaster. |
broadcaster_login | String | The broadcaster’s login name. |
broadcaster_name | String | The broadcaster’s display name. |
broadcaster_language | String | The broadcaster’s preferred language. The value is an ISO 639-1 two-letter language code (for example, en for English). The value is set to “other” if the language is not a Twitch supported language. |
game_name | String | The name of the game that the broadcaster is playing or last played. The value is an empty string if the broadcaster has never played a game. |
game_id | String | An ID that uniquely identifies the game that the broadcaster is playing or last played. The value is an empty string if the broadcaster has never played a game. |
title | String | The title of the stream that the broadcaster is currently streaming or last streamed. The value is an empty string if the broadcaster has never streamed. |
delay | Unsigned Integer | The value of the broadcaster’s stream delay setting, in seconds. This field’s value defaults to zero unless 1) the request specifies a user access token, 2) the ID in the broadcaster_id query parameter matches the user ID in the access token, and 3) the broadcaster has partner status and they set a non-zero stream delay value. |
tags | String[] | The tags applied to the channel. |
content_classification_labels | String[] | The CCLs applied to the channel. |
is_branded_content | Boolean | Boolean flag indicating if the channel has branded content. |
Response Codes
HTTP Code | Description |
---|---|
200 OK | Successfully retrieved the list of channels. |
400 Bad Request |
|
401 Unauthorized |
|
429 Too Many Requests |
|
500 Internal Server Error |
Example Request
Gets information about the TwitchDev channel.
curl -X GET 'https://api.twitch.tv/helix/channels?broadcaster_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"broadcaster_id": "141981764",
"broadcaster_login": "twitchdev",
"broadcaster_name": "TwitchDev",
"broadcaster_language": "en",
"game_id": "509670",
"game_name": "Science & Technology",
"title": "TwitchDev Monthly Update // May 6, 2021",
"delay": 0,
"tags": ["DevsInTheKnow"],
"content_classification_labels": ["Gambling", "DrugsIntoxication", "MatureGame"],
"is_branded_content": false
}
]
}
Modify Channel Information
✎Updates a channel’s properties.
Authorization
Requires a user access token that includes the channel:manage:broadcast scope.
URL
PATCH https://api.twitch.tv/helix/channels
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose channel you want to update. This ID must match the user ID in the user access token. |
Request Body
All fields are optional, but you must specify at least one field.
Field | Type | Required? | Description |
---|---|---|---|
game_id | String | No | The ID of the game that the user plays. The game is not updated if the ID isn’t a game ID that Twitch recognizes. To unset this field, use “0” or “” (an empty string). |
broadcaster_language | String | No | The user’s preferred language. Set the value to an ISO 639-1 two-letter language code (for example, en for English). Set to “other” if the user’s preferred language is not a Twitch supported language. The language isn’t updated if the language code isn’t a Twitch supported language. |
title | String | No | The title of the user’s stream. You may not set this field to an empty string. |
delay | Integer | No | The number of seconds you want your broadcast buffered before streaming it live. The delay helps ensure fairness during competitive play. Only users with Partner status may set this field. The maximum delay is 900 seconds (15 minutes). |
tags | String[] | No | A list of channel-defined tags to apply to the channel. To remove all tags from the channel, set tags to an empty array. Tags help identify the content that the channel streams. Learn More A channel may specify a maximum of 10 tags. Each tag is limited to a maximum of 25 characters and may not be an empty string or contain spaces or special characters. Tags are case insensitive. For readability, consider using camelCasing or PascalCasing. |
content_classification_labels | Label[] | No | List of labels that should be set as the Channel’s CCLs. |
id | string | Yes | ID of the Content Classification Labels that must be added/removed from the channel. Can be one of the following values:
|
is_enabled | boolean | Yes | Boolean flag indicating whether the label should be enabled (true) or disabled for the channel. |
is_branded_content | Boolean | No | Boolean flag indicating if the channel has branded content. |
Response Codes
HTTP Code | Description |
---|---|
204 No Content | Successfully updated the channel’s properties. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
409 Too Many Requests | User set the Branded Content flag too frequently |
500 Internal server error |
Example Request
curl -X PATCH 'https://api.twitch.tv/helix/channels?broadcaster_id=41245072' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{"game_id":"33214", "title":"there are helicopters in the game? REASON TO PLAY FORTNITE found", "broadcaster_language":"en", "tags":["LevelingUp"]}'
Set CCLs for a Channel
curl -X PATCH
'https://api.twitch.tv/helix/channels?broadcaster_id=41245072' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{
“game_id”: “SomeGameID”,
“content_classification_labels”: [
{“id”: “Gambling”, “is_enabled”: true}, // adds this label
{“id”: “DrugsIntoxication”, “is_enabled”: false} // removes this label
],
“is_branded_content”: true
}'
Get Channel Editors
✎Gets the broadcaster’s list editors.
Authorization
Requires a user access token that includes the channel:read:editors scope.
URL
GET https://api.twitch.tv/helix/channels/editors
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that owns the channel. This ID must match the user ID in the access token. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list of users that are editors for the specified broadcaster. The list is empty if the broadcaster doesn’t have editors. |
user_id | String | An ID that uniquely identifies a user with editor permissions. |
user_name | String | The user’s display name. |
created_at | String | The date and time, in RFC3339 format, when the user became one of the broadcaster’s editors. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster's list of editors. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Gets the list of editors for TwitchDev.
curl -X GET 'https://api.twitch.tv/helix/channels/editors?broadcaster_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
Example Response
{
"data": [
{
"user_id": "182891647",
"user_name": "mauerbac",
"created_at": "2019-02-15T21:19:50.380833Z"
},
{
"user_id": "135093069",
"user_name": "BlueLava",
"created_at": "2018-03-07T16:28:29.872937Z"
}
]
}
Get Followed Channels
✎Gets a list of broadcasters that the specified user follows. You can also use this endpoint to see whether a user follows a specific broadcaster.
Authorization
Requires a user access token that includes the user:read:follows scope.
URL
GET https://api.twitch.tv/helix/channels/followed
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
user_id | String | Yes | A user’s ID. Returns the list of broadcasters that this user follows. This ID must match the user ID in the user OAuth token. |
broadcaster_id | String | No | A broadcaster’s ID. Use this parameter to see whether the user follows this broadcaster. If specified, the response contains this broadcaster if the user follows them. If not specified, the response contains all broadcasters that the user follows. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read more. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of broadcasters that the user follows. The list is in descending order by followed_at (with the most recently followed broadcaster first). The list is empty if the user doesn’t follow anyone. |
broadcaster_id | String | An ID that uniquely identifies the broadcaster that this user is following. |
broadcaster_login | String | The broadcaster’s login name. |
broadcaster_name | String | The broadcaster’s display name. |
followed_at | String | The UTC timestamp when the user started following the broadcaster. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read more. |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
total | Integer | The total number of broadcasters that the user follows. As someone pages through the list, the number may change as the user follows or unfollows broadcasters. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster's list of followers. |
400 Bad Request | Possible reasons:
|
401 Unauthorized | Possible reasons:
|
Example Request
Gets the list of broadcasters that the specified user follows.
curl -X GET 'https://api.twitch.tv/helix/channels/followed?user_id=123456' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'
Example Response
{
"total": 8
"data": [
{
"broadcaster_id": "11111",
"broadcaster_login": "userloginname",
"broadcaster_name": "UserDisplayName",
"followed_at": "2022-05-24T22:22:08Z",
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
}
}
Example Request
Checks whether the specified user follows the specified broadcaster.
curl -X GET 'https://api.twitch.tv/helix/channels/followed?user_id=123456&broadcaster_id=654321' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'
Example Response
The data
field is not an empty array, which means that the user does follow the specified broadcaster.
{
"total": 8
"data": [
{
"broadcaster_id": "654321",
"broadcaster_login": "basketweaver101",
"broadcaster_name": "BasketWeaver101",
"followed_at": "2022-05-24T22:22:08Z",
}
],
"pagination": {}
}
Get Channel Followers
✎Gets a list of users that follow the specified broadcaster. You can also use this endpoint to see whether a specific user follows the broadcaster.
Authorization
- Requires a user access token that includes the moderator:read:followers scope.
- The ID in the broadcaster_id query parameter must match the user ID in the access token or the user ID in the access token must be a moderator for the specified broadcaster.
This endpoint will return specific follower information only if both of the above are true. If a scope is not provided or the user isn’t the broadcaster or a moderator for the specified channel, only the total follower count will be included in the response.
URL
GET https://api.twitch.tv/helix/channels/followers
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
user_id | String | No | A user’s ID. Use this parameter to see whether the user follows this broadcaster. If specified, the response contains this user if they follow the broadcaster. If not specified, the response contains all users that follow the broadcaster. Using this parameter requires both a user access token with the moderator:read:followers scope and the user ID in the access token match the broadcaster_id or be the user ID for a moderator of the specified broadcaster. |
broadcaster_id | String | Yes | The broadcaster’s ID. Returns the list of users that follow this broadcaster. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read more. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of users that follow the specified broadcaster. The list is in descending order by followed_at (with the most recent follower first). The list is empty if nobody follows the broadcaster, the specified user_id isn’t in the follower list, the user access token is missing the moderator:read:followers scope, or the user isn’t the broadcaster or moderator for the channel. |
followed_at | String | The UTC timestamp when the user started following the broadcaster. |
user_id | String | An ID that uniquely identifies the user that’s following the broadcaster. |
user_login | String | The user’s login name. |
user_name | String | The user’s display name. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read more. |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
total | Integer | The total number of users that follow this broadcaster. As someone pages through the list, the number of users may change as users follow or unfollow the broadcaster. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s list of followers. |
400 Bad Request | Possible reasons:
|
401 Unauthorized | Possible reasons:
|
Example Request
Gets the list of users that follow the specified broadcaster.
curl -X GET 'https://api.twitch.tv/helix/channels/followers?broadcaster_id=123456' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'
Example Response
{
"total": 8
"data": [
{
"user_id": "11111",
"user_name": "UserDisplayName",
"user_login": "userloginname",
"followed_at": "2022-05-24T22:22:08Z",
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
}
}
Example Request
Checks whether the specified user follows the specified broadcaster.
curl -X GET 'https://api.twitch.tv/helix/channels/followers?broadcaster_id=123456&user_id=654321' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'
Example Response
The data
field is an empty array, which means the user doesn’t follow the specified broadcaster.
{
"total": 8
"data": [],
"pagination": {}
}
Create Custom Rewards
✎Creates a Custom Reward in the broadcaster’s channel. The maximum number of custom rewards per channel is 50, which includes both enabled and disabled rewards.
Authorization
Requires a user access token that includes the channel:manage:redemptions scope.
URL
POST https://api.twitch.tv/helix/channel_points/custom_rewards
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster to add the custom reward to. This ID must match the user ID found in the OAuth token. |
Request Body
Field | Type | Required? | Description |
---|---|---|---|
title | String | Yes | The custom reward’s title. The title may contain a maximum of 45 characters and it must be unique amongst all of the broadcaster’s custom rewards. |
cost | Int64 | Yes | The cost of the reward, in Channel Points. The minimum is 1 point. |
prompt | String | No | The prompt shown to the viewer when they redeem the reward. Specify a prompt if is_user_input_required is true. The prompt is limited to a maximum of 200 characters. |
is_enabled | Boolean | No | A Boolean value that determines whether the reward is enabled. Viewers see only enabled rewards. The default is true. |
background_color | String | No | The background color to use for the reward. Specify the color using Hex format (for example, #9147FF). |
is_user_input_required | Boolean | No | A Boolean value that determines whether the user needs to enter information when redeeming the reward. See the prompt field. The default is false. |
is_max_per_stream_enabled | Boolean | No | A Boolean value that determines whether to limit the maximum number of redemptions allowed per live stream (see the max_per_stream field). The default is false. |
max_per_stream | Integer | No | The maximum number of redemptions allowed per live stream. Applied only if is_max_per_stream_enabled is true. The minimum value is 1. |
is_max_per_user_per_stream_enabled | Boolean | No | A Boolean value that determines whether to limit the maximum number of redemptions allowed per user per stream (see the max_per_user_per_stream field). The default is false. |
max_per_user_per_stream | Integer | No | The maximum number of redemptions allowed per user per stream. Applied only if is_max_per_user_per_stream_enabled is true. The minimum value is 1. |
is_global_cooldown_enabled | Boolean | No | A Boolean value that determines whether to apply a cooldown period between redemptions (see the global_cooldown_seconds field for the duration of the cooldown period). The default is false. |
global_cooldown_seconds | Integer | No | The cooldown period, in seconds. Applied only if the is_global_cooldown_enabled field is true. The minimum value is 1; however, the minimum value is 60 for it to be shown in the Twitch UX. |
should_redemptions_skip_request_queue | Boolean | No | A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process. The default is false. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the single custom reward you created. |
broadcaster_id | String | The ID that uniquely identifies the broadcaster. |
broadcaster_login | String | The broadcaster’s login name. |
broadcaster_name | String | The broadcaster’s display name. |
id | String | The ID that uniquely identifies this custom reward. |
title | String | The title of the reward. |
prompt | String | The prompt shown to the viewer when they redeem the reward if user input is required (see the is_user_input_required field). |
cost | Integer | The cost of the reward in Channel Points. |
image | Object | A set of custom images for the reward. This field is set to null if the broadcaster didn’t upload images. |
url_1x | String | The URL to a small version of the image. |
url_2x | String | The URL to a medium version of the image. |
url_4x | String | The URL to a large version of the image. |
default_image | Object | A set of default images for the reward. |
url_1x | String | The URL to a small version of the image. |
url_2x | String | The URL to a medium version of the image. |
url_4x | String | The URL to a large version of the image. |
background_color | String | The background color to use for the reward. The color is in Hex format (for example, #00E5CB). |
is_enabled | Boolean | A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren’t shown to the user. |
is_user_input_required | Boolean | A Boolean value that determines whether the user must enter information when redeeming the reward. Is true if the reward requires user input. |
max_per_stream_setting | Object | The settings used to determine whether to apply a maximum to the number to the redemptions allowed per live stream. |
is_enabled | Boolean | A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit. |
max_per_stream | Int64 | The maximum number of redemptions allowed per live stream. |
max_per_user_per_stream_setting | Object | The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream. |
is_enabled | Boolean | A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit. |
max_per_user_per_stream | Int64 | The maximum number of redemptions allowed per user per live stream. |
global_cooldown_setting | Object | The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown. |
is_enabled | Boolean | A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled. |
global_cooldown_seconds | Int64 | The cooldown period, in seconds. |
is_paused | Boolean | A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can’t redeem paused rewards. |
is_in_stock | Boolean | A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can’t redeem out of stock rewards. |
should_redemptions_skip_request_queue | Boolean | A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is UNFULFILLED and follows the normal request queue process. |
redemptions_redeemed_current_stream | Integer | The number of redemptions redeemed during the current live stream. The number counts against the max_per_stream_setting limit. This field is null if the broadcaster’s stream isn’t live or max_per_stream_setting isn’t enabled. |
cooldown_expires_at | String | The timestamp of when the cooldown period expires. Is null if the reward isn’t in a cooldown state (see the global_cooldown_setting field). |
Response Codes
HTTP Code | Description |
---|---|
200 OK | Successfully created the custom reward. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
500 Internal Server Error |
Example Request
Creates a custom reward.
curl -X POST 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
"title":"game analysis 1v1",
"cost":50000
}'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "afaa7e34-6b17-49f0-a19a-d1e76eaaf673",
"image": null,
"background_color": "#00E5CB",
"is_enabled": true,
"cost": 50000,
"title": "game analysis 1v1",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": false,
"max_per_stream": 0
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": true,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": false,
"redemptions_redeemed_current_stream": null,
"cooldown_expires_at": null
}
]
}
Delete Custom Reward
✎Deletes a custom reward that the broadcaster created.
The app used to create the reward is the only app that may delete it. If the reward’s redemption status is UNFULFILLED at the time the reward is deleted, its redemption status is marked as FULFILLED.
Authorization
Requires a user access token that includes the channel:manage:redemptions scope.
URL
DELETE https://api.twitch.tv/helix/channel_points/custom_rewards
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that created the custom reward. This ID must match the user ID found in the OAuth token. |
id | String | Yes | The ID of the custom reward to delete. |
Response Codes
HTTP Code | Description |
---|---|
204 No Content | Successfully deleted the custom reward. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
500 Internal Server Error |
Example Request
Deletes the specified custom reward.
curl -X DELETE 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=b045196d-9ce7-4a27-a9b9-279ed341ab28' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Get Custom Reward
✎Gets a list of custom rewards that the specified broadcaster created.
NOTE: A channel may offer a maximum of 50 rewards, which includes both enabled and disabled rewards.
Authorization
Requires a user access token that includes the channel:read:redemptions or channel:manage:redemptions scope.
URL
GET https://api.twitch.tv/helix/channel_points/custom_rewards
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose custom rewards you want to get. This ID must match the user ID found in the OAuth token. |
id | String | No | A list of IDs to filter the rewards by. To specify more than one ID, include this parameter for each reward you want to get. For example, id=1234&id=5678 . You may specify a maximum of 50 IDs.Duplicate IDs are ignored. The response contains only the IDs that were found. If none of the IDs were found, the response is 404 Not Found. |
only_manageable_rewards | Boolean | No | A Boolean value that determines whether the response contains only the custom rewards that the app may manage (the app is identified by the ID in the Client-Id header). Set to true to get only the custom rewards that the app may manage. The default is false. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list of custom rewards. The list is in ascending order by id . If the broadcaster hasn’t created custom rewards, the list is empty. |
broadcaster_id | String | The ID that uniquely identifies the broadcaster. |
broadcaster_login | String | The broadcaster’s login name. |
broadcaster_name | String | The broadcaster’s display name. |
id | String | The ID that uniquely identifies this custom reward. |
title | String | The title of the reward. |
prompt | String | The prompt shown to the viewer when they redeem the reward if user input is required (see the is_user_input_required field). |
cost | Integer | The cost of the reward in Channel Points. |
image | Object | A set of custom images for the reward. This field is null if the broadcaster didn’t upload images. |
url_1x | String | The URL to a small version of the image. |
url_2x | String | The URL to a medium version of the image. |
url_4x | String | The URL to a large version of the image. |
default_image | Object | A set of default images for the reward. |
url_1x | String | The URL to a small version of the image. |
url_2x | String | The URL to a medium version of the image. |
url_4x | String | The URL to a large version of the image. |
background_color | String | The background color to use for the reward. The color is in Hex format (for example, #00E5CB). |
is_enabled | Boolean | A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren’t shown to the user. |
is_user_input_required | Boolean | A Boolean value that determines whether the user must enter information when redeeming the reward. Is true if the user is prompted. |
max_per_stream_setting | Object | The settings used to determine whether to apply a maximum to the number of redemptions allowed per live stream. |
is_enabled | Boolean | A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit. |
max_per_stream | Int64 | The maximum number of redemptions allowed per live stream. |
max_per_user_per_stream_setting | Object | The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream. |
is_enabled | Boolean | A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit. |
max_per_user_per_stream | Int64 | The maximum number of redemptions allowed per user per live stream. |
global_cooldown_setting | Object | The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown. |
is_enabled | Boolean | A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled. |
global_cooldown_seconds | Int64 | The cooldown period, in seconds. |
is_paused | Boolean | A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can’t redeem paused rewards. |
is_in_stock | Boolean | A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can’t redeem out of stock rewards. |
should_redemptions_skip_request_queue | Boolean | A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process. |
redemptions_redeemed_current_stream | Integer | The number of redemptions redeemed during the current live stream. The number counts against the max_per_stream_setting limit. This field is null if the broadcaster’s stream isn’t live or max_per_stream_setting isn’t enabled. |
cooldown_expires_at | String | The timestamp of when the cooldown period expires. Is null if the reward isn’t in a cooldown state. See the global_cooldown_setting field. |
Response Codes
HTTP Code | Meaning |
---|---|
200 OK | Successfully retrieved the broadcaster’s list of custom rewards. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
500 Internal Server Error |
Example Request
Gets the broadcaster’s list of custom rewards.
curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"image": null,
"background_color": "#00E5CB",
"is_enabled": true,
"cost": 50000,
"title": "game analysis",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": false,
"max_per_stream": 0
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": true,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": false,
"redemptions_redeemed_current_stream": null,
"cooldown_expires_at": null
}
]
}
Example Request
Gets the list of custom rewards that the calling Client ID can manage.
curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&only_manageable_rewards=true'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_id": "274637212",
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"image": null,
"background_color": "#00E5CB",
"is_enabled": true,
"cost": 50000,
"title": "game analysis",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": false,
"max_per_stream": 0
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": true,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": false,
"redemptions_redeemed_current_stream": null,
"cooldown_expires_at": null
}
]
}
Example Request
Gets the specified custom reward.
curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_id": "274637212",
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"image": null,
"background_color": "#00E5CB",
"is_enabled": true,
"cost": 50000,
"title": "game analysis",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": false,
"max_per_stream": 0
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": true,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": false,
"redemptions_redeemed_current_stream": null,
"cooldown_expires_at": null
}
]
}
Get Custom Reward Redemption
✎Gets a list of redemptions for the specified custom reward. The app used to create the reward is the only app that may get the redemptions.
Authorization
Requires a user access token that includes the channel:read:redemptions or channel:manage:redemptions scope.
URL
GET https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that owns the custom reward. This ID must match the user ID found in the user OAuth token. |
reward_id | String | Yes | The ID that identifies the custom reward whose redemptions you want to get. |
status | String | Yes | The status of the redemptions to return. The possible case-sensitive values are:
NOTE: Canceled and fulfilled redemptions are returned for only a few days after they’re canceled or fulfilled. |
id | String | No | A list of IDs to filter the redemptions by. To specify more than one ID, include this parameter for each redemption you want to get. For example, id=1234&id=5678 . You may specify a maximum of 50 IDs.Duplicate IDs are ignored. The response contains only the IDs that were found. If none of the IDs were found, the response is 404 Not Found. |
sort | String | No | The order to sort redemptions by. The possible case-sensitive values are:
|
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read more |
first | Integer | No | The maximum number of redemptions to return per page in the response. The minimum page size is 1 redemption per page and the maximum is 50. The default is 20. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of redemptions for the specified reward. The list is empty if there are no redemptions that match the redemption criteria. |
broadcaster_id | String | The ID that uniquely identifies the broadcaster. |
broadcaster_login | String | The broadcaster’s login name. |
broadcaster_name | string | The broadcaster’s display name. |
id | String | The ID that uniquely identifies this redemption. |
user_login | String | The user’s login name. |
user_id | String | The ID that uniquely identifies the user that redeemed the reward. |
user_name | String | The user’s display name. |
user_input | String | The text the user entered at the prompt when they redeemed the reward; otherwise, an empty string if user input was not required. |
status | String | The state of the redemption. Possible values are:
|
redeemed_at | String | The date and time of when the reward was redeemed, in RFC3339 format. |
reward | Object | The reward that the user redeemed. |
id | String | The ID that uniquely identifies the redeemed reward. |
title | String | The reward’s title. |
prompt | String | The prompt displayed to the viewer if user input is required. |
cost | Int64 | The reward’s cost, in Channel Points. |
Response Codes
HTTP Code | Description |
---|---|
200 Ok | Successfully retrieved the list of redeemed custom rewards. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
500 Internal Server Error |
Example Request
Gets the list of redemptions that were canceled for the specified reward.
curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&status=CANCELED' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
"user_login": "torpedo09",
"user_id": "274637212",
"user_name": "torpedo09",
"user_input": "",
"status": "CANCELED",
"redeemed_at": "2020-07-01T18:37:32Z",
"reward": {
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"title": "game analysis",
"prompt": "",
"cost": 50000
}
}
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6Ik1UZG1ZVEprWmpFdFlXUTNOaTAwT0RBMExXSm1ZVFV0WVRRd1pXWTJNMlZtWlRZelgxOHlNREl3TFRBM0xUQXhWREU0T2pNM09qTXlMakl6TXpFeU56RTFOMW89In19"
}
}
Example Request
Gets redemptions by ID.
curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&id=17fa2df1-ad76-4804-bfa5-a40ef63efe63' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
"user_id": "274637212",
"user_name": "torpedo09",
"user_input": "",
"status": "CANCELED",
"redeemed_at": "2020-07-01T18:37:32Z",
"reward": {
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"title": "game analysis",
"prompt": "",
"cost": 50000
}
}
]
}
Update Custom Reward
✎Updates a custom reward. The app used to create the reward is the only app that may update the reward.
Authorization
Requires a user access token that includes the channel:manage:redemptions scope.
URL
PATCH https://api.twitch.tv/helix/channel_points/custom_rewards
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that’s updating the reward. This ID must match the user ID found in the OAuth token. |
id | String | Yes | The ID of the reward to update. |
Request Body
The body of the request should contain only the fields you’re updating.
Field | Type | Required? | Description |
---|---|---|---|
title | String | No | The reward’s title. The title may contain a maximum of 45 characters and it must be unique amongst all of the broadcaster’s custom rewards. |
prompt | String | No | The prompt shown to the viewer when they redeem the reward. Specify a prompt if is_user_input_required is true. The prompt is limited to a maximum of 200 characters. |
cost | Int64 | No | The cost of the reward, in channel points. The minimum is 1 point. |
background_color | String | No | The background color to use for the reward. Specify the color using Hex format (for example, \#00E5CB). |
is_enabled | Boolean | No | A Boolean value that indicates whether the reward is enabled. Set to true to enable the reward. Viewers see only enabled rewards. |
is_user_input_required | Boolean | No | A Boolean value that determines whether users must enter information to redeem the reward. Set to true if user input is required. See the prompt field. |
is_max_per_stream_enabled | Boolean | No | A Boolean value that determines whether to limit the maximum number of redemptions allowed per live stream (see the max_per_stream field). Set to true to limit redemptions. |
max_per_stream | Int64 | No | The maximum number of redemptions allowed per live stream. Applied only if is_max_per_stream_enabled is true. The minimum value is 1. |
is_max_per_user_per_stream_enabled | Boolean | No | A Boolean value that determines whether to limit the maximum number of redemptions allowed per user per stream (see max_per_user_per_stream ). The minimum value is 1. Set to true to limit redemptions. |
max_per_user_per_stream | Int64 | No | The maximum number of redemptions allowed per user per stream. Applied only if is_max_per_user_per_stream_enabled is true. |
is_global_cooldown_enabled | Boolean | No | A Boolean value that determines whether to apply a cooldown period between redemptions. Set to true to apply a cooldown period. For the duration of the cooldown period, see global_cooldown_seconds . |
global_cooldown_seconds | Int64 | No | The cooldown period, in seconds. Applied only if is_global_cooldown_enabled is true. The minimum value is 1; however, for it to be shown in the Twitch UX, the minimum value is 60. |
is_paused | Boolean | No | A Boolean value that determines whether to pause the reward. Set to true to pause the reward. Viewers can’t redeem paused rewards.. |
should_redemptions_skip_request_queue | Boolean | No | A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process. |
Response Body
Parameter | Type | Description |
---|---|---|
data | Object[] | The list contains the single reward that you updated. |
broadcaster_id | String | The ID that uniquely identifies the broadcaster. |
broadcaster_login | String | The broadcaster’s login name. |
broadcaster_name | String | The broadcaster’s display name. |
id | String | The ID that uniquely identifies this custom reward. |
title | String | The title of the reward. |
prompt | String | The prompt shown to the viewer when they redeem the reward if user input is required. See the is_user_input_required field. |
cost | Int64 | The cost of the reward in Channel Points. |
image | Object | A set of custom images for the reward. This field is null if the broadcaster didn’t upload images. |
url_1x | String | The URL to a small version of the image. |
url_2x | String | The URL to a medium version of the image. |
url_4x | String | The URL to a large version of the image. |
default_image | Object | A set of default images for the reward. |
url_1x | String | The URL to a small version of the image. |
url_2x | String | The URL to a medium version of the image. |
url_4x | String | The URL to a large version of the image. |
background_color | String | The background color to use for the reward. The color is in Hex format (for example, #00E5CB). |
is_enabled | Boolean | A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren’t shown to the user. |
is_user_input_required | Boolean | A Boolean value that determines whether the user must enter information when they redeem the reward. Is true if the user is prompted. |
max_per_stream_setting | Object | The settings used to determine whether to apply a maximum to the number of redemptions allowed per live stream. |
is_enabled | Boolean | A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit. |
max_per_stream | Int64 | The maximum number of redemptions allowed per live stream. |
max_per_user_per_stream_setting | Object | The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream. |
is_enabled | Boolean | A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit. |
max_per_user_per_stream | Int64 | The maximum number of redemptions allowed per user per live stream. |
global_cooldown_setting | Object | The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown. |
is_enabled | Boolean | A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled. |
global_cooldown_seconds | Int64 | The cooldown period, in seconds. |
is_paused | Boolean | A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can’t redeem paused rewards. |
is_in_stock | Boolean | A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can’t redeem out of stock rewards. |
should_redemptions_skip_request_queue | Boolean | A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process. |
redemptions_redeemed_current_stream | Integer | The number of redemptions redeemed during the current live stream. The number counts against the max_per_stream_setting limit. This field is null if the broadcaster’s stream isn’t live or max_per_stream_setting isn’t enabled. |
cooldown_expires_at | String | The timestamp of when the cooldown period expires. Is null if the reward isn’t in a cooldown state. See the global_cooldown_setting field. |
Response Codes
HTTP Code | Description |
---|---|
200 OK | Successfully updated the custom reward. |
400 Bad Request | ul>title must contain a minimum of 1 character and a maximum of 45 characters.title must be unique amongst all of the broadcaster's custom rewards.cost field must contain a minimum of 1 point.prompt field is limited to a maximum of 200 characters.is_max_per_stream_enabled is true, the minimum value for max_per_stream is 1.is_max_per_user_per_stream_enabled is true, the minimum value for max_per_user_per_stream is 1.is_global_cooldown_enabled is true, the minimum value for global_cooldown_seconds is 1 and the maximum is 604800. |
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
500 Internal Server Error |
Example Request
Disables the specified custom reward.
curl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
"is_enabled": false
}'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"image": null,
"background_color": "#00E5CB",
"is_enabled": false,
"cost": 30000,
"title": "game analysis 2v2",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": true,
"max_per_stream": 60
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": false,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": true,
"redemptions_redeemed_current_stream": 60,
"cooldown_expires_at": null
}
]
}
Example Request
Updates the reward’s title.
curl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
"title": "game analysis 2v2"
}'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"image": null,
"background_color": "",
"is_enabled": false,
"cost": 30000,
"title": "game analysis 2v2",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": true,
"max_per_stream": 60
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": true,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": true,
"redemptions_redeemed_current_stream": 60,
"cooldown_expires_at": null
}
]
}
Update Redemption Status
✎Updates a redemption’s status. You may update a redemption only if its status is UNFULFILLED. The app used to create the reward is the only app that may update the redemption.
Authorization
Requires a user access token that includes the channel:manage:redemptions scope.
URL
PATCH https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
id | String | Yes | A list of IDs that identify the redemptions to update. To specify more than one ID, include this parameter for each redemption you want to update. For example, id=1234&id=5678 . You may specify a maximum of 50 IDs. |
broadcaster_id | String | Yes | The ID of the broadcaster that’s updating the redemption. This ID must match the user ID in the user access token. |
reward_id | String | Yes | The ID that identifies the reward that’s been redeemed. |
Request Body
Field | Type | Required? | Description |
---|---|---|---|
status | String | Yes | The status to set the redemption to. Possible values are:
|
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list contains the single redemption that you updated. |
broadcaster_id | String | The ID that uniquely identifies the broadcaster. |
broadcaster_login | String | The broadcaster’s login name. |
broadcaster_name | String | The broadcaster’s display name. |
id | String | The ID that uniquely identifies this redemption.. |
user_id | String | The ID of the user that redeemed the reward. |
user_name | String | The user’s display name. |
user_login | String | The user’s login name. |
reward | Object | An object that describes the reward that the user redeemed. |
id | String | The ID that uniquely identifies the reward. |
title | String | The reward’s title. |
prompt | String | The prompt displayed to the viewer if user input is required. |
cost | Int64 | The reward’s cost, in Channel Points. |
user_input | String | The text that the user entered at the prompt when they redeemed the reward; otherwise, an empty string if user input was not required. |
status | String | The state of the redemption. Possible values are:
|
redeemed_at | String | The date and time of when the reward was redeemed, in RFC3339 format. |
Response Codes
HTTP Code | Description |
---|---|
200 OK | Successfully updated the redemption’s status. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
500 Internal Server Error |
Example Request
Updates a redemption’s status.
curl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&id=17fa2df1-ad76-4804-bfa5-a40ef63efe63' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
"status": "CANCELED"
}'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
"user_id": "274637212",
"user_name": "torpedo09",
"user_login": "torpedo09",
"user_input": "",
"status": "CANCELED",
"redeemed_at": "2020-07-01T18:37:32Z",
"reward": {
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"title": "game analysis",
"prompt": "",
"cost": 50000
}
}
]
}
Get Charity Campaign
✎Gets information about the charity campaign that a broadcaster is running. For example, the campaign’s fundraising goal and the current amount of donations.
To receive events when progress is made towards the campaign’s goal or the broadcaster changes the fundraising goal, subscribe to the channel.charity_campaign.progress subscription type.
Authorization
Requires a user access token that includes the channel:read:charity scope.
URL
GET https://api.twitch.tv/helix/charity/campaigns
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that’s currently running a charity campaign. This ID must match the user ID in the access token. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the charity campaign that the broadcaster is currently running. The list is empty if the broadcaster is not running a charity campaign; the campaign information is not available after the campaign ends. |
id | String | An ID that identifies the charity campaign. |
broadcaster_id | String | An ID that identifies the broadcaster that’s running the campaign. |
broadcaster_login | String | The broadcaster’s login name. |
broadcaster_name | String | The broadcaster’s display name. |
charity_name | String | The charity’s name. |
charity_description | String | A description of the charity. |
charity_logo | String | A URL to an image of the charity’s logo. The image’s type is PNG and its size is 100px X 100px. |
charity_website | String | A URL to the charity’s website. |
current_amount | Object | The current amount of donations that the campaign has received. |
value | Integer | The monetary amount. The amount is specified in the currency’s minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, value is set to 550. |
decimal_places | Integer | The number of decimal places used by the currency. For example, USD uses two decimal places. Use this number to translate value from minor units to major units by using the formula:value / 10^decimal_places |
currency | String | The ISO-4217 three-letter currency code that identifies the type of currency in value . |
target_amount | Object | The campaign’s fundraising goal. This field is null if the broadcaster has not defined a fundraising goal. |
value | Integer | The monetary amount. The amount is specified in the currency’s minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, value is set to 550. |
decimal_places | Integer | The number of decimal places used by the currency. For example, USD uses two decimal places. Use this number to translate value from minor units to major units by using the formula:value / 10^decimal_places |
currency | String | The ISO-4217 three-letter currency code that identifies the type of currency in value . |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved information about the broadcaster’s active charity campaign. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request
Gets the broadcaster’s active charity campaign.
curl -X GET 'https://api.twitch.tv/helix/charity/campaigns?broadcaster_id=123456' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'
Example Response
{
"data": [
{
"id": "123-abc-456-def",
"broadcaster_id": "123456",
"broadcaster_name": "SunnySideUp",
"broadcaster_login": "sunnysideup",
"charity_name": "Example name",
"charity_description": "Example description",
"charity_logo": "https://abc.cloudfront.net/ppgf/1000/100.png",
"charity_website": "https://www.example.com",
"current_amount": {
"value": 86000,
"decimal_places": 2,
"currency": "USD"
},
"target_amount": {
"value": 1500000,
"decimal_places": 2,
"currency": "USD"
}
}
]
}
Get Charity Campaign Donations
✎Gets the list of donations that users have made to the broadcaster’s active charity campaign.
To receive events as donations occur, subscribe to the channel.charity_campaign.donate subscription type.
Authorization
Requires a user access token that includes the channel:read:charity scope.
URL
GET https://api.twitch.tv/helix/charity/donations
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that’s currently running a charity campaign. This ID must match the user ID in the access token. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the donations that users have made to the broadcaster’s charity campaign. The list is empty if the broadcaster is not currently running a charity campaign; the donation information is not available after the campaign ends. |
id | String | An ID that identifies the donation. The ID is unique across campaigns. |
campaign_id | String | An ID that identifies the charity campaign that the donation applies to. |
user_id | String | An ID that identifies a user that donated money to the campaign. |
user_login | String | The user’s login name. |
user_name | String | The user’s display name. |
amount | Object | An object that contains the amount of money that the user donated. |
value | Integer | The monetary amount. The amount is specified in the currency’s minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, value is set to 550. |
decimal_places | Integer | The number of decimal places used by the currency. For example, USD uses two decimal places. Use this number to translate value from minor units to major units by using the formula:value / 10^decimal_places |
currency | String | The ISO-4217 three-letter currency code that identifies the type of currency in value . |
pagination | Object | An object that contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of donations that users contributed to the broadcaster’s charity campaign. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request
Gets the broadcaster’s active charity campaign.
curl -X GET 'https://api.twitch.tv/helix/charity/donations?broadcaster_id=123456' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'
Example Response
{
"data": [
{
"id": "a1b2c3-aabb-4455-d1e2f3",
"campaign_id": "123-abc-456-def",
"user_id": "5678",
"user_login": "cool_user",
"user_name": "Cool_User",
"amount": {
"value": 500,
"decimal_places": 2,
"currency": "USD"
}
},
{
"id": "z1y2x3-ccdd-6677-d1e2f3",
"campaign_id": "123-abc-456-def",
"user_id": "8765",
"user_login": "cool_user2",
"user_name": "Cool_User2",
"amount": {
"value": 10000,
"decimal_places": 2,
"currency": "USD"
}
},
. . .
],
"pagination" : {
"cursor" : "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
}
}
Get Chatters
✎Gets the list of users that are connected to the broadcaster’s chat session.
NOTE: There is a delay between when users join and leave a chat and when the list is updated accordingly.
To determine whether a user is a moderator or VIP, use the Get Moderators and Get VIPs endpoints. You can check the roles of up to 100 users.
Authorization
Requires a user access token that includes the moderator:read:chatters scope.
URL
GET https://api.twitch.tv/helix/chat/chatters
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose list of chatters you want to get. |
moderator_id | String | Yes | The ID of the broadcaster or one of the broadcaster’s moderators. This ID must match the user ID in the user access token. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 1,000. The default is 100. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of users that are connected to the broadcaster’s chat room. The list is empty if no users are connected to the chat room. |
user_id | String | The ID of a user that’s connected to the broadcaster’s chat room. |
user_login | String | The user’s login name. |
user_name | String | The user’s display name. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
total | Integer | The total number of users that are connected to the broadcaster’s chat room. As you page through the list, the number of users may change as users join and leave the chat room. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s list of chatters. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request
Gets the list of users that are connected to the specified broadcaster’s chat room.
curl -X GET 'https://api.twitch.tv/helix/chat/chatters?broadcaster_id=123456&moderator_id=654321' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'
Example Response
{
"data": [
{
"user_id": "128393656",
"user_login": "smittysmithers",
"user_name": "smittysmithers"
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
},
"total": 8
}
Get Channel Emotes
✎Gets the broadcaster’s list of custom emotes. Broadcasters create these custom emotes for users who subscribe to or follow the channel or cheer Bits in the channel’s chat window. Learn More
For information about the custom emotes, see subscriber emotes, Bits tier emotes, and follower emotes.
NOTE: With the exception of custom follower emotes, users may use custom emotes in any Twitch chat.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/chat/emotes
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | An ID that identifies the broadcaster whose emotes you want to get. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of emotes that the specified broadcaster created. If the broadcaster hasn't created custom emotes, the list is empty. |
id | String | An ID that identifies this emote. |
name | String | The name of the emote. This is the name that viewers type in the chat window to get the emote to appear. |
images | Object | The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background. NOTE: You should use the templated URL in the template field to fetch the image instead of using these URLs. |
url_1x | String | A URL to the small version (28px x 28px) of the emote. |
url_2x | String | A URL to the medium version (56px x 56px) of the emote. |
url_4x | String | A URL to the large version (112px x 112px) of the emote. |
tier | String | The subscriber tier at which the emote is unlocked. This field contains the tier information only if emote_type is set to subscriptions , otherwise, it's an empty string. |
emote_type | String | The type of emote. The possible values are:
|
emote_set_id | String | An ID that identifies the emote set that the emote belongs to. |
format | String[] | The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only static . But if the emote is available as a static PNG and an animated GIF, the array contains static and animated . The possible formats are:
|
scale | String[] | The sizes that the emote is available in. For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0. Possible sizes are:
|
theme_mode | String[] | The background themes that the emote is available in. Possible themes are:
|
template | String | A templated URL. Use the values from the id , format , scale , and theme_mode fields to replace the like-named placeholder strings in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote. For information about what the template looks like and how to use it to fetch emotes, see Emote CDN URL format. You should use this template instead of using the URLs in the images object. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved broadcaster's list of custom emotes. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Gets custom emotes that the TwitchDev channel created.
curl -X GET 'https://api.twitch.tv/helix/chat/emotes?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
# Twitch CLI example that gets the custom emotes for the specified channel.
twitch api get /chat/emotes -q broadcaster_id=141981764
Example Response
{
"data": [
{
"id": "304456832",
"name": "twitchdevPitchfork",
"images": {
"url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/1.0",
"url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/2.0",
"url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/3.0"
},
"tier": "1000",
"emote_type": "subscriptions",
"emote_set_id": "301590448",
"format": [
"static"
],
"scale": [
"1.0",
"2.0",
"3.0"
],
"theme_mode": [
"light",
"dark"
]
},
...
{
"id": "emotesv2_4c3b4ed516de493bbcd2df2f5d450f49",
"name": "twitchdevHyperPitchfork",
"images": {
"url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/1.0",
"url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/2.0",
"url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/3.0"
},
"tier": "1000",
"emote_type": "subscriptions",
"emote_set_id": "318939165",
"format": [
"static",
"animated"
],
"scale": [
"1.0",
"2.0",
"3.0"
],
"theme_mode": [
"light",
"dark"
]
},
],
"template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}
Get Global Emotes
✎Gets the list of global emotes. Global emotes are Twitch-created emotes that users can use in any Twitch chat.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/chat/emotes/global
Request Query Parameters
None
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of global emotes. |
id | String | An ID that identifies this emote. |
name | String | The name of the emote. This is the name that viewers type in the chat window to get the emote to appear. |
images | Object | The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background. NOTE: You should use the templated URL in the template field to fetch the image instead of using these URLs. |
url_1x | String | A URL to the small version (28px x 28px) of the emote. |
url_2x | String | A URL to the medium version (56px x 56px) of the emote. |
url_4x | String | A URL to the large version (112px x 112px) of the emote. |
format | String[] | The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only static . But if the emote is available as a static PNG and an animated GIF, the array contains static and animated . The possible formats are:
|
scale | String[] | The sizes that the emote is available in. For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0. Possible sizes are:
|
theme_mode | String[] | The background themes that the emote is available in. Possible themes are:
|
template | String | A templated URL. Use the values from the id , format , scale , and theme_mode fields to replace the like-named placeholder strings in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote. For information about what the template looks like and how to use it to fetch emotes, see Emote CDN URL format. You should use this template instead of using the URLs in the images object. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved Twitch's list of global emotes. |
401 Unauthorized |
|
Example Request
Gets all global emotes.
curl -X GET 'https://api.twitch.tv/helix/chat/emotes/global' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
# Twitch CLI example that gets all global emotes.
twitch api get /chat/emotes/global
Example Response
{
"data": [
{
"id": "196892",
"name": "TwitchUnity",
"images": {
"url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/1.0",
"url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/2.0",
"url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/3.0"
},
"format": [
"static"
],
"scale": [
"1.0",
"2.0",
"3.0"
],
"theme_mode": [
"light",
"dark"
]
},
...
],
"template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}
Get Emote Sets
✎Gets emotes for one or more specified emote sets.
An emote set groups emotes that have a similar context. For example, Twitch places all the subscriber emotes that a broadcaster uploads for their channel in the same emote set.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/chat/emotes/set
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
emote_set_id | String | Yes | An ID that identifies the emote set to get. Include this parameter for each emote set you want to get. For example, emote_set_id=1234&emote_set_id=5678 . You may specify a maximum of 25 IDs. The response contains only the IDs that were found and ignores duplicate IDs.To get emote set IDs, use the Get Channel Emotes API. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of emotes found in the specified emote sets. The list is empty if none of the IDs were found. The list is in the same order as the set IDs specified in the request. Each set contains one or more emoticons. |
id | String | An ID that uniquely identifies this emote. |
name | String | The name of the emote. This is the name that viewers type in the chat window to get the emote to appear. |
images | Object | The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background. NOTE: You should use the templated URL in the template field to fetch the image instead of using these URLs. |
url_1x | String | A URL to the small version (28px x 28px) of the emote. |
url_2x | String | A URL to the medium version (56px x 56px) of the emote. |
url_4x | String | A URL to the large version (112px x 112px) of the emote. |
emote_type | String | The type of emote. The possible values are:
|
emote_set_id | String | An ID that identifies the emote set that the emote belongs to. |
owner_id | String | The ID of the broadcaster who owns the emote. |
format | String[] | The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only static . But if the emote is available as a static PNG and an animated GIF, the array contains static and animated . The possible formats are:
|
scale | String[] | The sizes that the emote is available in. For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0. Possible sizes are:
|
theme_mode | String[] | The background themes that the emote is available in. Possible themes are:
|
template | string | A templated URL. Use the values from the id , format , scale , and theme_mode fields to replace the like-named placeholder strings in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote. For information about what the template looks like and how to use it to fetch emotes, see Emote CDN URL format. You should use this template instead of using the URLs in the images object. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the emotes for the specified emote sets. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Gets the emotes for the TwitchDev subscriber emote set.
curl -X GET 'https://api.twitch.tv/helix/chat/emotes/set?emote_set_id=301590448' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
# Twitch CLI example that gets the emotes for the specified emote set.
twitch api get /chat/emotes/set -q emote_set_id=301590448
Example Response
{
"data": [
{
"id": "304456832",
"name": "twitchdevPitchfork",
"images": {
"url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/1.0",
"url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/2.0",
"url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/3.0"
},
"emote_type": "subscriptions",
"emote_set_id": "301590448",
"owner_id": "141981764",
"format": [
"static"
],
"scale": [
"1.0",
"2.0",
"3.0"
],
"theme_mode": [
"light",
"dark"
]
},
...
],
"template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}
Get Channel Chat Badges
✎Gets the broadcaster’s list of custom chat badges. The list is empty if the broadcaster hasn’t created custom chat badges. For information about custom badges, see subscriber badges and Bits badges.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/chat/badges
Request Query Parameter
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose chat badges you want to get. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of chat badges. The list is sorted in ascending order by set_id , and within a set, the list is sorted in ascending order by id . |
set_id | String | An ID that identifies this set of chat badges. For example, Bits or Subscriber. |
versions | Object[] | The list of chat badges in this set. |
id | String | An ID that identifies this version of the badge. The ID can be any value. For example, for Bits, the ID is the Bits tier level, but for World of Warcraft, it could be Alliance or Horde. |
image_url_1x | String | A URL to the small version (18px x 18px) of the badge. |
image_url_2x | String | A URL to the medium version (36px x 36px) of the badge. |
image_url_4x | String | A URL to the large version (72px x 72px) of the badge. |
title | String | The title of the badge. |
description | String | The description of the badge. |
click_action | String | The action to take when clicking on the badge. Set to null if no action is specified. |
click_url | String | The URL to navigate to when clicking on the badge. Set to null if no URL is specified. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s custom chat badges. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Get the list of custom chat badges that the BlueLava Twitch channel created.
curl -X GET 'https://api.twitch.tv/helix/chat/badges?broadcaster_id=135093069' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"set_id": "bits",
"versions": [
{
"id": "1",
"image_url_1x": "https://static-cdn.jtvnw.net/badges/v1/743a0f3b-84b3-450b-96a0-503d7f4a9764/1",
"image_url_2x": "https://static-cdn.jtvnw.net/badges/v1/743a0f3b-84b3-450b-96a0-503d7f4a9764/2",
"image_url_4x": "https://static-cdn.jtvnw.net/badges/v1/743a0f3b-84b3-450b-96a0-503d7f4a9764/3",
"title": "cheer 1",
"description": "cheer 1"
"click_action": "visit_url",
"click_url": "https://bits.twitch.tv"
}
]
},
{
"set_id": "subscriber",
"versions": [
{
"id": "0",
"image_url_1x": "https://static-cdn.jtvnw.net/badges/v1/eb4a8a4c-eacd-4f5e-b9f2-394348310442/1",
"image_url_2x": "https://static-cdn.jtvnw.net/badges/v1/eb4a8a4c-eacd-4f5e-b9f2-394348310442/2",
"image_url_4x": "https://static-cdn.jtvnw.net/badges/v1/eb4a8a4c-eacd-4f5e-b9f2-394348310442/3",
"title": "Subscriber",
"description": "Subscriber",
"click_action": "subscribe_to_channel",
"click_url": null
},
]
}
]
}
Get Global Chat Badges
✎Gets Twitch’s list of chat badges, which users may use in any channel’s chat room. For information about chat badges, see Twitch Chat Badges Guide.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/chat/badges/global
Request Query Parameters
None
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of chat badges. The list is sorted in ascending order by set_id , and within a set, the list is sorted in ascending order by id . |
set_id | String | An ID that identifies this set of chat badges. For example, Bits or Subscriber. |
versions | Object[] | The list of chat badges in this set. |
id | String | An ID that identifies this version of the badge. The ID can be any value. For example, for Bits, the ID is the Bits tier level, but for World of Warcraft, it could be Alliance or Horde. |
image_url_1x | String | A URL to the small version (18px x 18px) of the badge. |
image_url_2x | String | A URL to the medium version (36px x 36px) of the badge. |
image_url_4x | String | A URL to the large version (72px x 72px) of the badge. |
title | String | The title of the badge. |
description | String | The description of the badge. |
click_action | String | The action to take when clicking on the badge. Set to null if no action is specified. |
click_url | String | The URL to navigate to when clicking on the badge. Set to null if no URL is specified. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of global chat badges. |
401 Unauthorized |
|
Example Request
Gets the list of global chat badges.
curl -X GET 'https://api.twitch.tv/helix/chat/badges/global' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
...
{
"set_id": "vip",
"versions": [
{
"id": "1",
"image_url_1x": "https://static-cdn.jtvnw.net/badges/v1/b817aba4-fad8-49e2-b88a-7cc744dfa6ec/1",
"image_url_2x": "https://static-cdn.jtvnw.net/badges/v1/b817aba4-fad8-49e2-b88a-7cc744dfa6ec/2",
"image_url_4x": "https://static-cdn.jtvnw.net/badges/v1/b817aba4-fad8-49e2-b88a-7cc744dfa6ec/3",
"title": "VIP",
"description": "VIP",
"click_action": "visit_url",
"click_url": "https://help.twitch.tv/customer/en/portal/articles/659115-twitch-chat-badges-guide"
}
]
},
...
]
}
Get Chat Settings
✎Gets the broadcaster’s chat settings.
For an overview of chat settings, see Chat Commands for Broadcasters and Moderators and Moderator Preferences.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/chat/settings
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose chat settings you want to get. |
moderator_id | String | No | The ID of the broadcaster or one of the broadcaster’s moderators. This field is required only if you want to include the non_moderator_chat_delay and non_moderator_chat_delay_duration settings in the response.If you specify this field, this ID must match the user ID in the user access token. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of chat settings. The list contains a single object with all the settings. |
broadcaster_id | String | The ID of the broadcaster specified in the request. |
emote_mode | Boolean | A Boolean value that determines whether chat messages must contain only emotes. Is true if chat messages may contain only emotes; otherwise, false. |
follower_mode | Boolean | A Boolean value that determines whether the broadcaster restricts the chat room to followers only. Is true if the broadcaster restricts the chat room to followers only; otherwise, false. See the follower_mode_duration field for how long users must follow the broadcaster before being able to participate in the chat room. |
follower_mode_duration | Integer | The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. Is null if follower_mode is false. |
moderator_id | String | The moderator’s ID. The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope. |
non_moderator_chat_delay | Boolean | A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room. This gives chat moderators and bots a chance to remove them before viewers can see the message. See the non_moderator_chat_delay_duration field for the length of the delay. Is true if the broadcaster applies a delay; otherwise, false.The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope and the user in the moderator_id query parameter is one of the broadcaster’s moderators. |
non_moderator_chat_delay_duration | Integer | The amount of time, in seconds, that messages are delayed before appearing in chat. Is null if non_moderator_chat_delay is false.The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope and the user in the moderator_id query parameter is one of the broadcaster’s moderators. |
slow_mode | Boolean | A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages. Is true if the broadcaster applies a delay; otherwise, false. See the slow_mode_wait_time field for the delay. |
slow_mode_wait_time | Integer | The amount of time, in seconds, that users must wait between sending messages. Is null if slow_mode is false. |
subscriber_mode | Boolean | A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room. Is true if the broadcaster restricts the chat room to subscribers only; otherwise, false. |
unique_chat_mode | Boolean | A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. Is true if the broadcaster requires unique messages only; otherwise, false. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s chat settings. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
Example Response
{
"data": [
{
"broadcaster_id": "713936733",
"slow_mode": false,
"slow_mode_wait_time": null,
"follower_mode": true,
"follower_mode_duration": 0,
"subscriber_mode": false,
"emote_mode": false,
"unique_chat_mode": false,
"non_moderator_chat_delay": true,
"non_moderator_chat_delay_duration": 4
}
]
}
Get Shared Chat Session
✎NEW Retrieves the active shared chat session for a channel.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/shared_chat/session
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The User ID of the channel broadcaster. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | |
session_id | String | The unique identifier for the shared chat session. |
host_broadcaster_id | String | The User ID of the host channel. |
participants | Object[] | The list of participants in the session. |
broadcaster_id | String | The User ID of the participant channel. |
created_at | String | The UTC date and time (in RFC3339 format) for when the session was created. |
updated_at | String | The UTC date and time (in RFC3339 format) for when the session was last updated. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the shared chat session. Returns an empty array if the broadcaster_id in the request isn’t in a shared chat session. |
400 Bad Request | The ID in the broadcaster_id query parameter is not valid. |
401 Unauthorized |
|
500 Internal Error | Internal Server Error. |
Example Request
curl -X GET 'https://api.twitch.tv/helix/shared_chat/session?broadcaster_id=198704263' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"session_id": "359bce59-fa4e-41a5-bd6f-9bc0c8360485",
"host_broadcaster_id": “198704263”,
"participants": [{
"broadcaster_id": “198704263”
}, {
"broadcaster_id": “487263401”
}],
"created_at": "2024-09-29T19:45:37Z",
"updated_at": "2024-09-29T19:45:37Z"
}
]
}
Get User Emotes
✎NEW Retrieves emotes available to the user across all channels.
Authorization
-
Requires a user access token that includes the user:read:emotes scope.
-
Query parameter
user_id
must match theuser_id
in the user access token.
URL
GET https://api.twitch.tv/helix/chat/emotes/user
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
user_id | String | Yes | The ID of the user. This ID must match the user ID in the user access token. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. |
broadcaster_id | String | No | The User ID of a broadcaster you wish to get follower emotes of. Using this query parameter will guarantee inclusion of the broadcaster’s follower emotes in the response body. Note: If the user specified in user_id is subscribed to the broadcaster specified, their follower emotes will appear in the response body regardless if this query parameter is used. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | |
id | String | An ID that uniquely identifies this emote. |
name | String | The User ID of broadcaster whose channel is receiving the unban request. |
emote_type | String | The type of emote. The possible values are:
|
emote_set_id | String | An ID that identifies the emote set that the emote belongs to. |
owner_id | String | The ID of the broadcaster who owns the emote. |
format | String[] | The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only static. But if the emote is available as a static PNG and an animated GIF, the array contains static and animated.
|
scale | String[] | The sizes that the emote is available in. For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0.
|
theme_mode | String[] | The background themes that the emote is available in.
|
template | String | A templated URL. Uses the values from the id, format, scale, and theme_mode fields to replace the like-named placeholder strings in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote. For information about what the template looks like and how to use it to fetch emotes, see Emote CDN URL format. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. For more information about pagination support, see Twitch API Guide - Pagination. |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the emotes. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/chat/emotes/user?user_id=123456' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'
Example Response
{
"data": [
{
"emote_set_id": "",
"emote_type": "hypetrain",
"format": [
"static"
],
"id": "304420818",
"name": "HypeLol",
"owner_id": "477339272",
"scale": [
"1.0",
"2.0",
"3.0"
],
"theme_mode": [
"light",
"dark"
]
}
],
"template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}",
"pagination": {
"cursor": "eyJiIjpudWxsLJxhIjoiIn0gf5"
}
}
Update Chat Settings
✎Updates the broadcaster’s chat settings.
Authorization
Requires a user access token that includes the moderator:manage:chat_settings scope.
URL
PATCH https://api.twitch.tv/helix/chat/settings
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose chat settings you want to update. |
moderator_id | String | Yes | The ID of a user that has permission to moderate the broadcaster’s chat room, or the broadcaster’s ID if they’re making the update. This ID must match the user ID in the user access token. |
Request Body
All fields are optional. Specify only those fields that you want to update.
To set the slow_mode_wait_time
or follower_mode_duration
field to its default value, set the corresponding slow_mode
or follower_mode
field to true (and don’t include the slow_mode_wait_time
or follower_mode_duration
field).
To set the slow_mode_wait_time
, follower_mode_duration
, or non_moderator_chat_delay_duration
field’s value, you must set the corresponding slow_mode
, follower_mode
, or non_moderator_chat_delay
field to true.
To remove the slow_mode_wait_time
, follower_mode_duration
, or non_moderator_chat_delay_duration
field’s value, set the corresponding slow_mode
, follower_mode
, or non_moderator_chat_delay
field to false (and don’t include the slow_mode_wait_time
, follower_mode_duration
, or non_moderator_chat_delay_duration
field).
Field | Type | Description |
---|---|---|
emote_mode | Boolean | A Boolean value that determines whether chat messages must contain only emotes. Set to true if only emotes are allowed; otherwise, false. The default is false. |
follower_mode | Boolean | A Boolean value that determines whether the broadcaster restricts the chat room to followers only. Set to true if the broadcaster restricts the chat room to followers only; otherwise, false. The default is true. To specify how long users must follow the broadcaster before being able to participate in the chat room, see the follower_mode_duration field. |
follower_mode_duration | Integer | The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. Set only if follower_mode is true. Possible values are: 0 (no restriction) through 129600 (3 months). The default is 0. |
non_moderator_chat_delay | Boolean | A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room. This gives chat moderators and bots a chance to remove them before viewers can see the message. Set to true if the broadcaster applies a delay; otherwise, false. The default is false. To specify the length of the delay, see the non_moderator_chat_delay_duration field. |
non_moderator_chat_delay_duration | Integer | The amount of time, in seconds, that messages are delayed before appearing in chat. Set only if non_moderator_chat_delay is true. Possible values are:
|
slow_mode | Boolean | A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages. Set to true if the broadcaster applies a wait period between messages; otherwise, false. The default is false. To specify the delay, see the slow_mode_wait_time field. |
slow_mode_wait_time | Integer | The amount of time, in seconds, that users must wait between sending messages. Set only if slow_mode is true.Possible values are: 3 (3 second delay) through 120 (2 minute delay). The default is 30 seconds. |
subscriber_mode | Boolean | A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room. Set to true if the broadcaster restricts the chat room to subscribers only; otherwise, false. The default is false. |
unique_chat_mode | Boolean | A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. Set to true if the broadcaster allows only unique messages; otherwise, false. The default is false. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of chat settings. The list contains a single object with all the settings. |
broadcaster_id | String | The ID of the broadcaster specified in the request. |
emote_mode | Boolean | A Boolean value that determines whether chat messages must contain only emotes. Is true if chat messages may contain only emotes; otherwise, false. |
follower_mode | Boolean | A Boolean value that determines whether the broadcaster restricts the chat room to followers only. Is true if the broadcaster restricts the chat room to followers only; otherwise, false. See the follower_mode_duration field for how long users must follow the broadcaster before being able to participate in the chat room. |
follower_mode_duration | Integer | The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. Is null if follower_mode is false. |
moderator_id | String | The moderator’s ID. The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope. |
non_moderator_chat_delay | Boolean | A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room. This gives chat moderators and bots a chance to remove them before viewers can see the message. See the non_moderator_chat_delay_duration field for the length of the delay. Is true if the broadcaster applies a delay; otherwise, false. |
non_moderator_chat_delay_duration | Integer | The amount of time, in seconds, that messages are delayed before appearing in chat. Is null if non_moderator_chat_delay is false. |
slow_mode | Boolean | A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages. Is true if the broadcaster applies a delay; otherwise, false. See the slow_mode_wait_time field for the delay. |
slow_mode_wait_time | Integer | The amount of time, in seconds, that users must wait between sending messages. Is null if slow_mode is false. |
subscriber_mode | Boolean | A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room. Is true if the broadcaster restricts the chat room to subscribers only; otherwise, false. |
unique_chat_mode | Boolean | A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. Is true if the broadcaster requires unique messages only; otherwise, false. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully updated the broadcaster’s chat settings. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request
This example disables follower_mode
by setting it to false.
curl -X PATCH 'https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"follower_mode": false}'
To change a setting’s value, the request must specify the mode field and its corresponding value field. For example, to change the value of slow_mode_wait_time
, the request must also specify slow_mode
even if it’s already true.
curl -X PATCH 'https://https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 8j9yq1kpl92w96trqy7sintbsihdp' \
-H 'Client-Id: 0vql4f5yqu4spo6zrz1pkumcqwa9c' \
-H 'Content-Type: application/json' \
-d '{"slow_mode": true, "slow_mode_wait_time": 10}'
Example Response
{
"data": [
{
"broadcaster_id": "1234",
"moderator_id": "5678",
"slow_mode": true,
"slow_mode_wait_time": 10,
"follower_mode": false,
"follower_mode_duration": null,
"subscriber_mode": false,
"emote_mode": false,
"unique_chat_mode": false,
"non_moderator_chat_delay": false,
"non_moderator_chat_delay_duration": null
}
]
}
Send Chat Announcement
✎Sends an announcement to the broadcaster’s chat room.
Authorization
Requires a user access token that includes the moderator:manage:announcements scope.
URL
POST https://api.twitch.tv/helix/chat/announcements
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that owns the chat room to send the announcement to. |
moderator_id | String | Yes | The ID of a user who has permission to moderate the broadcaster’s chat room, or the broadcaster’s ID if they’re sending the announcement. This ID must match the user ID in the user access token. |
Request Body
Field | Type | Required? | Description |
---|---|---|---|
message | String | Yes | The announcement to make in the broadcaster’s chat room. Announcements are limited to a maximum of 500 characters; announcements longer than 500 characters are truncated. |
color | String | No | The color used to highlight the announcement. Possible case-sensitive values are:
color is set to primary or is not set, the channel’s accent color is used to highlight the announcement (see Profile Accent Color under profile settings, Channel and Videos, and Brand). |
Response Body
None
Response Codes
Code | Description |
---|---|
204 No Content | Successfully sent the announcement. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Sends an announcement to the broadcaster’s chat room.
curl -X POST 'https://api.twitch.tv/helix/chat/announcements?broadcaster_id=11111&moderator_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' \
-H 'Content-Type: application/json' \
-d '{"message":"Hello chat!","color":"purple"}'
Send a Shoutout
✎Sends a Shoutout to the specified broadcaster. Typically, you send Shoutouts when you or one of your moderators notice another broadcaster in your chat, the other broadcaster is coming up in conversation, or after they raid your broadcast.
Twitch’s Shoutout feature is a great way for you to show support for other broadcasters and help them grow. Viewers who do not follow the other broadcaster will see a pop-up Follow button in your chat that they can click to follow the other broadcaster. Learn More
Rate Limits The broadcaster may send a Shoutout once every 2 minutes. They may send the same broadcaster a Shoutout once every 60 minutes.
To receive notifications when a Shoutout is sent or received, subscribe to the channel.shoutout.create and channel.shoutout.receive subscription types. The channel.shoutout.create event includes cooldown periods that indicate when the broadcaster may send another Shoutout without exceeding the endpoint’s rate limit.
Authorization
Requires a user access token that includes the moderator:manage:shoutouts scope.
URL
POST https://api.twitch.tv/helix/chat/shoutouts
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
from_broadcaster_id | String | Yes | The ID of the broadcaster that’s sending the Shoutout. |
to_broadcaster_id | String | Yes | The ID of the broadcaster that’s receiving the Shoutout. |
moderator_id | String | Yes | The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token. |
Response Body
None
Response Codes
Code | Description |
---|---|
204 No Content | Successfully sent the specified broadcaster a Shoutout. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
429 Too Many Requests |
|
Example Request
curl -X POST 'https://api.twitch.tv/helix/chat/shoutouts?from_broadcaster_id=12345&to_broadcaster_id=626262&moderator_id=98765' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Send Chat Message
✎NEW Sends a message to the broadcaster’s chat room.
Authorization
Requires an app access token or user access token that includes the user:write:chat
scope. If app access token used, then additionally requires user:bot
scope from chatting user, and either channel:bot
scope from broadcaster or moderator status.
URL
POST https://api.twitch.tv/helix/chat/messages
Request Body
Field | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose chat room the message will be sent to. |
sender_id | String | Yes | The ID of the user sending the message. This ID must match the user ID in the user access token. |
message | String | Yes | The message to send. The message is limited to a maximum of 500 characters. Chat messages can also include emoticons. To include emoticons, use the name of the emote. The names are case sensitive. Don’t include colons around the name (e.g., :bleedPurple:). If Twitch recognizes the name, Twitch converts the name to the emote before writing the chat message to the chat room |
reply_parent_message_id | String | No | The ID of the chat message being replied to. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | |
message_id | String | The message id for the message that was sent. |
is_sent | Boolean | If the message passed all checks and was sent. |
drop_reason | Object | The reason the message was dropped, if any. |
code | String | Code for why the message was dropped. |
message | String | Message for why the message was dropped. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully sent the specified broadcaster a message. |
400 Bad Request |
|
401 Unauthenticated |
|
403 Forbidden | The sender is not permitted to send chat messages to the broadcaster’s chat room. |
422 Unprocessable Entity | The message is too large. |
Example Request
curl -X POST 'https://api.twitch.tv/helix/chat/messages' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
-d '{
"broadcaster_id": "12826",
"sender_id": "141981764",
"message": "Hello, world! twitchdevHype"
}'
Example Response
{
"data": [
{
"message_id": "abc-123-def",
"is_sent": true
}
]
}
Get User Chat Color
✎Gets the color used for the user’s name in chat.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/chat/color
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
user_id | String | Yes | The ID of the user whose username color you want to get. To specify more than one user, include the user_id parameter for each user to get. For example, &user_id=1234&user_id=5678 . The maximum number of IDs that you may specify is 100.The API ignores duplicate IDs and IDs that weren’t found. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of users and the color code they use for their name. |
user_id | String | An ID that uniquely identifies the user. |
user_login | String | The user’s login name. |
user_name | String | The user’s display name. |
color | String | The Hex color code that the user uses in chat for their name. If the user hasn’t specified a color in their settings, the string is empty. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the chat color used by the specified users. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Gets the chat color code used by the specified users.
curl -X GET 'https://api.twitch.tv/helix/chat/color?user_id=11111&user_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Example Response
{
"data": [
{
"user_id": "11111",
"user_name": "SpeedySpeedster1",
"user_login": "speedyspeedster1",
"color": "#9146FF"
},
{
"user_id": "44444",
"user_name": "SpeedySpeedster2",
"user_login": "speedyspeedster2",
"color": ""
}
]
}
Update User Chat Color
✎Updates the color used for the user’s name in chat.
Authorization
Requires a user access token that includes the user:manage:chat_color scope.
URL
PUT https://api.twitch.tv/helix/chat/color
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
user_id | String | Yes | The ID of the user whose chat color you want to update. This ID must match the user ID in the access token. |
color | String | Yes | The color to use for the user's name in chat. All users may specify one of the following named color values.
|
Response Body
None
Response Codes
Code | Description |
---|---|
204 No Content | Successfully updated the user's chat color. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Uses a named color to change the color that the user uses for their name in chat.
curl -X PUT 'https://api.twitch.tv/helix/chat/color?user_id=123&color=blue' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Uses a color Hex code to change the color that the user uses for their name in chat.
curl -X PUT 'https://api.twitch.tv/helix/chat/color?user_id=123&color=%239146FF' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Create Clip
✎Creates a clip from the broadcaster’s stream.
This API captures up to 90 seconds of the broadcaster’s stream. The 90 seconds spans the point in the stream from when you called the API. For example, if you call the API at the 4:00 minute mark, the API captures from approximately the 3:35 mark to approximately the 4:05 minute mark. Twitch tries its best to capture 90 seconds of the stream, but the actual length may be less. This may occur if you begin capturing the clip near the beginning or end of the stream.
By default, Twitch publishes up to the last 30 seconds of the 90 seconds window and provides a default title for the clip. To specify the title and the portion of the 90 seconds window that’s used for the clip, use the URL in the response’s edit_url
field. You can specify a clip that’s from 5 seconds to 60 seconds in length. The URL is valid for up to 24 hours or until the clip is published, whichever comes first.
Creating a clip is an asynchronous process that can take a short amount of time to complete. To determine whether the clip was successfully created, call Get Clips using the clip ID that this request returned. If Get Clips returns the clip, the clip was successfully created. If after 15 seconds Get Clips hasn’t returned the clip, assume it failed.
Authorization
Requires a user access token that includes the clips:edit scope.
URL
POST https://api.twitch.tv/helix/clips
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose stream you want to create a clip from. |
has_delay | Boolean | No | A Boolean value that determines whether the API captures the clip at the moment the viewer requests it or after a delay. If false (default), Twitch captures the clip at the moment the viewer requests it (this is the same clip experience as the Twitch UX). If true, Twitch adds a delay before capturing the clip (this basically shifts the capture window to the right slightly). |
Response Body
Field | Type | Description |
---|---|---|
edit_url | String | A URL that you can use to edit the clip’s title, identify the part of the clip to publish, and publish the clip. Learn More The URL is valid for up to 24 hours or until the clip is published, whichever comes first. |
id | String | An ID that uniquely identifies the clip. |
Response Codes
Code | Description |
---|---|
202 Accepted | Successfully started the clip process. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
Example Request
curl -X POST 'https://api.twitch.tv/helix/clips?broadcaster_id=44322889' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data":
[{
"id": "FiveWordsForClipSlug",
"edit_url": "http://clips.twitch.tv/FiveWordsForClipSlug/edit"
}]
}
Get Clips
✎Gets one or more video clips that were captured from streams. For information about clips, see How to use clips.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/clips
Request Query Parameters
The id, game_id, and broadcaster_id query parameters are mutually exclusive.
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | An ID that identifies the broadcaster whose video clips you want to get. Use this parameter to get clips that were captured from the broadcaster’s streams. |
game_id | String | Yes | An ID that identifies the game whose clips you want to get. Use this parameter to get clips that were captured from streams that were playing this game. |
id | String | Yes | An ID that identifies the clip to get. To specify more than one ID, include this parameter for each clip you want to get. For example, id=foo&id=bar . You may specify a maximum of 100 IDs. The API ignores duplicate IDs and IDs that aren’t found. |
started_at | String | No | The start date used to filter clips. The API returns only clips within the start and end date window. Specify the date and time in RFC3339 format. |
ended_at | String | No | The end date used to filter clips. If not specified, the time window is the start date plus one week. Specify the date and time in RFC3339 format. |
first | Integer | No | The maximum number of clips to return per page in the response. The minimum page size is 1 clip per page and the maximum is 100. The default is 20. |
before | String | No | The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
is_featured | Boolean | No | A Boolean value that determines whether the response includes featured clips. If true, returns only clips that are featured. If false, returns only clips that aren’t featured. All clips are returned if this parameter is not present. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of video clips. For clips returned by game_id or broadcaster_id, the list is in descending order by view count. For lists returned by id, the list is in the same order as the input IDs. |
id | String | An ID that uniquely identifies the clip. |
url | String | A URL to the clip. |
embed_url | String | A URL that you can use in an iframe to embed the clip (see Embedding Video and Clips). |
broadcaster_id | String | An ID that identifies the broadcaster that the video was clipped from. |
broadcaster_name | String | The broadcaster’s display name. |
creator_id | String | An ID that identifies the user that created the clip. |
creator_name | String | The user’s display name. |
video_id | String | An ID that identifies the video that the clip came from. This field contains an empty string if the video is not available. |
game_id | String | The ID of the game that was being played when the clip was created. |
language | String | The ISO 639-1 two-letter language code that the broadcaster broadcasts in. For example, en for English. The value is other if the broadcaster uses a language that Twitch doesn’t support. |
title | String | The title of the clip. |
view_count | Integer | The number of times the clip has been viewed. |
created_at | String | The date and time of when the clip was created. The date and time is in RFC3339 format. |
thumbnail_url | String | A URL to a thumbnail image of the clip. |
duration | float | The length of the clip, in seconds. Precision is 0.1. |
vod_offset | Integer | The zero-based offset, in seconds, to where the clip starts in the video (VOD). Is null if the video is not available or hasn’t been created yet from the live stream (see video_id ).Note that there’s a delay between when a clip is created during a broadcast and when the offset is set. During the delay period, vod_offset is null. The delay is indeterminant but is typically minutes long. |
is_featured | Boolean | A Boolean value that indicates if the clip is featured or not. |
pagination | Object | The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Set the request’s after or before query parameter to this value depending on whether you’re paging forwards or backwards. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of video clips. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
Example Request
Gets a clip by ID.
curl -X GET 'https://api.twitch.tv/helix/clips?id=AwkwardHelplessSalamanderSwiftRage' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "AwkwardHelplessSalamanderSwiftRage",
"url": "https://clips.twitch.tv/AwkwardHelplessSalamanderSwiftRage",
"embed_url": "https://clips.twitch.tv/embed?clip=AwkwardHelplessSalamanderSwiftRage",
"broadcaster_id": "67955580",
"broadcaster_name": "ChewieMelodies",
"creator_id": "53834192",
"creator_name": "BlackNova03",
"video_id": "205586603",
"game_id": "488191",
"language": "en",
"title": "babymetal",
"view_count": 10,
"created_at": "2017-11-30T22:34:18Z",
"thumbnail_url": "https://clips-media-assets.twitch.tv/157589949-preview-480x272.jpg",
"duration": 60,
"vod_offset": 480,
"is_featured": false
}
]
}
Example Request
Gets the broadcaster’s top 5 clips based on views.
curl -X GET 'https://api.twitch.tv/helix/clips?broadcaster_id=1234&first=5' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "RandomClip1",
"url": "https://clips.twitch.tv/AwkwardHelplessSalamanderSwiftRage",
"embed_url": "https://clips.twitch.tv/embed?clip=RandomClip1",
"broadcaster_id": "1234",
"broadcaster_name": "JJ",
"creator_id": "123456",
"creator_name": "MrMarshall",
"video_id": "",
"game_id": "33103",
"language": "en",
"title": "random1",
"view_count": 10,
"created_at": "2017-11-30T22:34:18Z",
"thumbnail_url": "https://clips-media-assets.twitch.tv/157589949-preview-480x272.jpg",
"duration": 12.9,
"vod_offset": 1957,
"is_featured": true
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjoiIn0"
}
}
Get Conduits
✎NEW Gets the conduits for a client ID.
Authorization
Requires an app access token.
URL
GET https://api.twitch.tv/helix/eventsub/conduits
Response Body
Parameter | Type | Description |
---|---|---|
data | Object[] | List of information about the client’s conduits. |
id | String | Conduit ID. |
shard_count | Integer | Number of shards associated with this conduit. |
Response Codes
Code | Meaning |
---|---|
200 OK | Successfully retrieved conduits. |
401 Unauthenticated | Authorization header required with an app access token. |
Example Request
curl -X GET 'https://api.twitch.tv/helix/eventsub/conduits' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
"shard_count": 15
},
{
"id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
"shard_count": 5
}
]
}
Create Conduits
✎NEW Creates a new conduit.
Authorization
Requires an app access token.
URL
POST https://api.twitch.tv/helix/eventsub/conduits
Request Body
Parameter | Type | Required | Description |
---|---|---|---|
shard_count | Integer | Yes | The number of shards to create for this conduit. |
Response Body
Parameter | Type | Description |
---|---|---|
data | Object[] | List of information about the client’s conduits. |
id | String | Conduit ID. |
shard_count | Integer | Number of shards created for this conduit. |
Response Codes
Code | Meaning |
---|---|
200 OK | Conduit created. |
400 Bad Request | Invalid shard count. |
401 Unauthenticated | Authorization header required with an app access token. |
429 Too Many Requests | Conduit limit reached. |
Example Request
curl -X POST 'https://api.twitch.tv/helix/eventsub/conduits' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{"shard_count": 5}'
Example Response
{
"data": [
{
"id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
"shard_count": 5
}
]
}
Update Conduits
✎NEW Updates a conduit’s shard count. To delete shards, update the count to a lower number, and the shards above the count will be deleted. For example, if the existing shard count is 100, by resetting shard count to 50, shards 50-99 are disabled.
Authorization
Requires an app access token.
URL
PATCH https://api.twitch.tv/helix/eventsub/conduits
Request Body
Parameter | Type | Required | Description |
---|---|---|---|
id | String | Yes | Conduit ID. |
shard_count | Integer | Yes | The new number of shards for this conduit. |
Response Body
Parameter | Type | Description |
---|---|---|
data | Object[] | List of information about the client’s conduits. |
id | String | Conduit ID. |
shard_count | Integer | Number of shards associated with this conduit after the update. |
Response Codes
Code | Meaning |
---|---|
200 OK | Conduit updated. |
400 Bad Request |
|
401 Unauthenticated | Authorization header required with an app access token. |
404 Not Found |
|
Example Request
curl -X PATCH 'https://api.twitch.tv/helix/eventsub/conduits' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"id":"bfcfc993-26b1-b876-44d9-afe75a379dac",
"shard_count":5
}'
Example Response
{
"data": [
{
"id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
"shard_count": 5
}
]
}
Delete Conduit
✎NEW Deletes a specified conduit. Note that it may take some time for Eventsub subscriptions on a deleted conduit to show as disabled when calling Get Eventsub Subscriptions.
Authorization
Requires an app access token.
URL
DELETE https://api.twitch.tv/helix/eventsub/conduits
Request Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | Yes | Conduit ID. |
Response Codes
Code | Meaning |
---|---|
204 No Content | Successfully deleted the conduit. |
400 Bad Request | The id query parameter is required. |
401 Unauthenticated | Authorization header required with an app access token. |
404 Not Found |
|
Example Request
curl -X DELETE 'https://api.twitch.tv/helix/eventsub/conduits?id=bfcfc993-26b1-b876-44d9-afe75a379dac' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Get Conduit Shards
✎NEW Gets a lists of all shards for a conduit.
Authorization
Requires an app access token.
URL
GET https://api.twitch.tv/helix/eventsub/conduits/shards
Request Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
conduit_id | String | Yes | Conduit ID. |
status | String | No | Status to filter by. |
after | String | No | The cursor used to get the next page of results. The pagination object in the response contains the cursor’s value. |
Response Body
Parameter | Type | Description |
---|---|---|
data | Object[] | List of information about a conduit's shards. |
id | String | Shard ID. |
status | String | The shard status. The subscriber receives events only for enabled shards. Possible values are:
|
transport | Object | The transport details used to send the notifications. |
method | String | The transport method. Possible values are:
|
callback | String | The callback URL where the notifications are sent. Included only if method is set to webhook. |
session_id | String | An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket. |
connected_at | String | The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket. |
disconnected_at | String | The UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket. |
pagination | Object | Contains information used to page through a list of results. The object is empty if there are no more pages left to page through. |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Meaning |
---|---|
200 OK | Successfully retrieved shards. |
400 Bad Request | The id query parameter is required. |
401 Unauthenticated | Authorization header required with an app access token. |
404 Not Found |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/eventsub/conduits/shards?conduit_id=bfcfc993-26b1-b876-44d9-afe75a379dac' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "0",
"status": "enabled",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
}
},
{
"id": "1",
"status": "webhook_callback_verification_pending",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback-2.com"
}
},
{
"id": "2",
"status": "enabled",
"transport": {
"method": "websocket",
"session_id": "9fd5164a-a958-4c60-b7f4-6a7202506ca0",
"connected_at": "2020-11-10T14:32:18.730260295Z"
}
},
{
"id": "3",
"status": "enabled",
"transport": {
"method": "websocket",
"session_id": "238b4b08-13f1-4b8f-8d31-56665a7a9d9f",
"connected_at": "2020-11-10T14:32:18.730260295Z"
}
},
{
"id": "4",
"status": "websocket_disconnected",
"transport": {
"method": "websocket",
"session_id": "ad1c9fc3-0d99-4eb7-8a04-8608e8ff9ec9",
"connected_at": "2020-11-10T14:32:18.730260295Z",
"disconnected_at": "2020-11-11T14:32:18.730260295Z"
}
}
],
"pagination": {},
}
Update Conduit Shards
✎NEW Updates shard(s) for a conduit.
NOTE: Shard IDs are indexed starting at 0, so a conduit with a shard_count
of 5 will have shards with IDs 0 through 4.
Authorization
Requires an app access token.
URL
PATCH https://api.twitch.tv/helix/eventsub/conduits/shards
Request Body
Parameter | Type | Required | Description |
---|---|---|---|
conduit_id | String | Yes | Conduit ID. |
shards | Object[] | Yes | List of shards to update. |
id | String | Yes | Shard ID. |
transport | Object | Yes | The transport details that you want Twitch to use when sending you notifications. |
method | String | No | The transport method. Possible values are:
|
callback | String | No | The callback URL where the notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an event.Specify this field only if method is set to webhook.NOTE: Redirects are not followed. |
secret | String | No | The secret used to verify the signature. The secret must be an ASCII string that’s a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.Specify this field only if method is set to webhook. |
session_id | String | No | An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.Specify this field only if method is set to websocket. |
Response Body
Parameter | Type | Description |
---|---|---|
data | Object[] | List of successful shard updates. |
id | String | Shard ID. |
status | String | The shard status. The subscriber receives events only for enabled shards. Possible values are:
|
transport | Object | The transport details used to send the notifications. |
method | String | The transport method. Possible values are:
|
callback | String | The callback URL where the notifications are sent. Included only if method is set to webhook. |
session_id | String | An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket. |
connected_at | String | The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket. |
disconnected_at | String | The UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket. |
errors | Object[] | List of unsuccessful updates. |
id | String | Shard ID. |
message | String | The error that occurred while updating the shard. Possible errors:
|
code | String | Error codes used to represent a specific error condition while attempting to update shards. |
Response Codes
Code | Meaning |
---|---|
202 Accepted | Successfully retrieved shards. |
400 Bad Request | The id query parameter is required. |
401 Unauthenticated | Authorization header required with an app access token. |
404 Not Found |
|
Example Request
curl -X PATCH 'https://api.twitch.tv/helix/eventsub/conduits/shards' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"conduit_id":"bfcfc993-26b1-b876-44d9-afe75a379dac",
"shards": [{
"id": "0",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com",
"secret": "s3cre7"
}
},
{
"id": "1",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback-2.com",
"secret": "s3cre7"
}
},
{
"id": "3",
"transport":{
"method": "webhook",
"callback": "https://this-is-a-callback-3.com"
"secret": "s3cre7"
}
}]
}'
Example Response
{
"data": [
{
"id": "0",
"status": "enabled",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
}
},
{
"id": "1",
"status": "webhook_callback_verification_pending",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback-2.com"
}
}
],
"errors": [
{
"id": "3",
"message": "The shard id is outside the conduit's range",
"code": "invalid_parameter"
}
]
}
Get Content Classification Labels
✎Gets information about Twitch content classification labels.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/content_classification_labels
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
locale | String | No | Locale for the Content Classification Labels. You may specify a maximum of 1 locale. Default: “en-US” Supported locales: "bg-BG", "cs-CZ", "da-DK", "da-DK", "de-DE", "el-GR", "en-GB", "en-US", "es-ES", "es-MX", "fi-FI", "fr-FR", "hu-HU", "it-IT", "ja-JP", "ko-KR", "nl-NL", "no-NO", "pl-PL", "pt-BT", "pt-PT", "ro-RO", "ru-RU", "sk-SK", "sv-SE", "th-TH", "tr-TR", "vi-VN", "zh-CN", "zh-TW" |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains information about the available content classification labels. |
content_classification_labels | Label[] | The list of CCLs available. |
id | String | Unique identifier for the CCL. |
description | String | Localized description of the CCL. |
name | String | Localized name of the CCL. |
Example Request
curl -X GET 'https://api.twitch.tv/helix/content_classification_labels' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"id": "DebatedSocialIssuesAndPolitics",
"description": "Discussions or debates about politics or sensitive social issues such as elections, civic integrity, military conflict, and civil rights in a polarizing manner.",
"name": "Politics and Sensitive Social Issues"
},
{
"id": "DrugsIntoxication",
"description": "Excessive tobacco glorification or promotion, any marijuana consumption/use, legal drug and alcohol induced intoxication, discussions of illegal drugs.",
"name": "Drugs, Intoxication, or Excessive Tobacco Use"
},
{
"id": "Gambling",
"description": "Participating in online or in-person gambling, poker or fantasy sports, that involve the exchange of real money.",
"name": "Gambling"
},
{
"id": "MatureGame",
"description": "Games that are rated Mature or less suitable for a younger audience.",
"name": "Mature-rated game"
},
{
"id": "ProfanityVulgarity",
"description": "Prolonged, and repeated use of obscenities, profanities, and vulgarities, especially as a regular part of speech.",
"name": "Significant Profanity or Vulgarity"
},
{
"id": "SexualThemes",
"description": "Content that focuses on sexualized physical attributes and activities, sexual topics, or experiences.",
"name": "Sexual Themes"
},
{
"id": "ViolentGraphic",
"description": "Simulations and/or depictions of realistic violence, gore, extreme injury, or death.",
"name": "Violent and Graphic Depictions"
}
]
}
Get Drops Entitlements
✎Gets an organization’s list of entitlements that have been granted to a game, a user, or both.
NOTE: Entitlements returned in the response body data are not guaranteed to be sorted by any field returned by the API. To retrieve CLAIMED or FULFILLED entitlements, use the fulfillment_status
query parameter to filter results. To retrieve entitlements for a specific game, use the game_id
query parameter to filter results.
The following table identifies the request parameters that you may specify based on the type of access token used.
Access token type | Parameter | Description |
---|---|---|
App | None | If you don’t specify request parameters, the request returns all entitlements that your organization owns. |
App | user_id | The request returns all entitlements for any game that the organization granted to the specified user. |
App | user_id, game_id | The request returns all entitlements that the specified game granted to the specified user. |
App | game_id | The request returns all entitlements that the specified game granted to all entitled users. |
User | None | If you don’t specify request parameters, the request returns all entitlements for any game that the organization granted to the user identified in the access token. |
User | user_id | Invalid. |
User | user_id, game_id | Invalid. |
User | game_id | The request returns all entitlements that the specified game granted to the user identified in the access token. |
Authorization
Requires an app access token or user access token. The client ID in the access token must own the game.
URL
GET https://api.twitch.tv/helix/entitlements/drops
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
id | String | No | An ID that identifies the entitlement to get. Include this parameter for each entitlement you want to get. For example, id=1234&id=5678 . You may specify a maximum of 100 IDs. |
user_id | String | No | An ID that identifies a user that was granted entitlements. |
game_id | String | No | An ID that identifies a game that offered entitlements. |
fulfillment_status | String | No | The entitlement’s fulfillment status. Used to filter the list to only those with the specified status. Possible values are:
|
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
first | Integer | No | The maximum number of entitlements to return per page in the response. The minimum page size is 1 entitlement per page and the maximum is 1000. The default is 20. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of entitlements. |
id | String | An ID that identifies the entitlement. |
benefit_id | String | An ID that identifies the benefit (reward). |
timestamp | String | The UTC date and time (in RFC3339 format) of when the entitlement was granted. |
user_id | String | An ID that identifies the user who was granted the entitlement. |
game_id | String | An ID that identifies the game the user was playing when the reward was entitled. |
fulfillment_status | String | The entitlement’s fulfillment status. Possible values are:
|
last_updated | String | The UTC date and time (in RFC3339 format) of when the entitlement was last updated. |
pagination | Object | The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Set the request’s after query parameter to this value to page forward through the results. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the entitlements. |
400 Bad Request |
|
401 Unauthorized |
|
403 Fobidden |
|
500 Internal server error |
Example Request
curl -H GET 'helix/entitlements/drops?user_id=25009227&game_id=33214' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "fb78259e-fb81-4d1b-8333-34a06ffc24c0",
"benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
"timestamp": "2019-01-28T04:17:53.325Z",
"user_id": "25009227",
"game_id": "33214",
"fulfillment_status": "CLAIMED",
"last_updated": "2019-01-28T04:17:53.325Z"
},
{
"id": "862750a5-265e-4ab6-9f0a-c64df3d54dd0",
"benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
"timestamp": "2019-01-28T04:16:53.325Z",
"user_id": "25009227",
"game_id": "33214",
"fulfillment_status": "CLAIMED",
"last_updated": "2021-06-15T04:16:53.325Z"
},
{
"id": "d8879baa-3966-4d10-8856-15fdd62cce02",
"benefit_id": "cdfdc5c3-65a2-43bc-8767-fde06eb4ab2c",
"timestamp": "2019-01-28T04:15:53.325Z",
"user_id": "25009227",
"game_id": "33214",
"fulfillment_status": "FULFILLED",
"last_updated": "2019-01-28T04:17:53.325Z"
},
...
],
"pagination": {
"cursor": "eyJiIjpudW..."
}
}
Update Drops Entitlements
✎Updates the Drop entitlement’s fulfillment status.
The following table identifies which entitlements are updated based on the type of access token used.
Access token type | Data that’s updated |
---|---|
App | Updates all entitlements with benefits owned by the organization in the access token. |
User | Updates all entitlements owned by the user in the access token and where the benefits are owned by the organization in the access token. |
Authorization
Requires an app access token or user access token. The client ID in the access token must own the game.
URL
PATCH https://api.twitch.tv/helix/entitlements/drops
Request Body
Field | Type | Required? | Description |
---|---|---|---|
entitlement_ids | String[] | No | A list of IDs that identify the entitlements to update. You may specify a maximum of 100 IDs. |
fulfillment_status | String | No | The fulfillment status to set the entitlements to. Possible values are:
|
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that indicates which entitlements were successfully updated and those that weren’t. |
status | String | A string that indicates whether the status of the entitlements in the ids field were successfully updated. Possible values are:
|
ids | String[] | The list of entitlements that the status in the status field applies to. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully requested the updates. Check the response to determine which updates succeeded. |
400 Bad Request |
|
401 Unauthorized |
|
500 Internal server error |
Example Request
curl -H PATCH 'helix/entitlements/drops' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"fulfillment_status": "FULFILLED",
"entitlement_ids": [
"fb78259e-fb81-4d1b-8333-34a06ffc24c0",
"862750a5-265e-4ab6-9f0a-c64df3d54dd0",
"d8879baa-3966-4d10-8856-15fdd62cce02",
"9a290126-7e3b-4f66-a9ae-551537893b65"
]
}'
Example Response
{
"data": [
{
"status": "SUCCESS",
"ids": [
"fb78259e-fb81-4d1b-8333-34a06ffc24c0", "862750a5-265e-4ab6-9f0a-c64df3d54dd0"
]
},
{
"status": "UNAUTHORIZED",
"ids": [
"d8879baa-3966-4d10-8856-15fdd62cce02"
]
},
{
"status": "UPDATE_FAILED",
"ids": [
"9a290126-7e3b-4f66-a9ae-551537893b65"
]
}
]
}
Get Extension Configuration Segment
✎Gets the specified configuration segment from the specified extension.
Rate Limits: You may retrieve each segment a maximum of 20 times per minute.
Authorization
Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role
, user_id
, and exp
fields (see JWT Schema). The role
field must be set to external.
URL
GET https://api.twitch.tv/helix/extensions/configurations
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | No | The ID of the broadcaster that installed the extension. This parameter is required if you set the segment parameter to broadcaster or developer. Do not specify this parameter if you set segment to global. |
extension_id | String | Yes | The ID of the extension that contains the configuration segment you want to get. |
segment | String | Yes | The type of configuration segment to get. Possible case-sensitive values are:
segment parameter for each segment to get. For example, segment=broadcaster&segment=developer . Ignores duplicate segments. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of requested configuration segments. The list is returned in the same order that you specified the list of segments in the request. |
segment | String | The type of segment. Possible values are:
|
broadcaster_id | String | The ID of the broadcaster that installed the extension. The object includes this field only if the segment query parameter is set to developer or broadcaster. |
content | String | The contents of the segment. This string may be a plain-text string or a string-encoded JSON object. |
version | String | The version number that identifies this definition of the segment’s data. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the configurations. |
400 Bad Request |
|
401 Unauthorized |
|
429 Too many requests |
|
Example Request
Gets the global configuration segment from the specified extension. Because the request gets the global segment, it must not include the broadcaster_id query parameter.
curl -X GET 'https://api.twitch.tv/helix/extensions/configurations?extension_id=<your extension id>&segment=global' \
-H 'Authorization: Bearer <your JWT token>' \
-H 'Client-Id: <your client ID>'
Example Response
The following example shows a global segment that contains a plain-text string in the content
field.
{
"data": [
{
"segment": "global",
"content": "hello config!",
"version": "0.0.1"
}
]
}
The following example shows a global segment that contains a string-encoded JSON object in the content
field.
{
"data": [
{
"segment": "global",
"content": "{\"foo\":\"bar\"}",
"version": "0.0.1"
}
]
}
Set Extension Configuration Segment
✎Updates a configuration segment. The segment is limited to 5 KB. Extensions that are active on a channel do not receive the updated configuration.
Rate Limits: You may update the configuration a maximum of 20 times per minute.
Authorization
Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role
, user_id
, and exp
fields (see JWT Schema). The role
field must be set to external.
URL
PUT https://api.twitch.tv/helix/extensions/configurations
Request Body
Field | Type | Required? | Description |
---|---|---|---|
extension_id | String | Yes | The ID of the extension to update. |
segment | String | Yes | The configuration segment to update. Possible case-sensitive values are:
|
broadcaster_id | String | No | The ID of the broadcaster that installed the extension. Include this field only if the segment is set to developer or broadcaster. |
content | String | No | The contents of the segment. This string may be a plain-text string or a string-encoded JSON object. |
version | String | No | The version number that identifies this definition of the segment’s data. If not specified, the latest definition is updated. |
Response Codes
Code | Description |
---|---|
204 No Content | Successfully updated the configuration. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X PUT 'https://api.twitch.tv/helix/extensions/configurations' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2",
"segment": "global",
"version": "0.0.1",
"content": "hello config!"
}'
Set Extension Required Configuration
✎Updates the extension’s required_configuration string. Use this endpoint if your extension requires the broadcaster to configure the extension before activating it (to require configuration, you must select Custom/My Own Service in Extension Capabilities). For more information, see Required Configurations and Setting Required Configuration.
Authorization
Requires a signed JSON Web Token (JWT) created by an EBS. For signing requirements, see Signing the JWT. The signed JWT must include the role
, user_id
, and exp
fields (see JWT Schema). Set the role
field to external and the user_id
field to the ID of the user that owns the extension.
URL
PUT https://api.twitch.tv/helix/extensions/required_configuration
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that installed the extension on their channel. |
Request Body
Parameter | Type | Required? | Description |
---|---|---|---|
extension_id | String | Yes | The ID of the extension to update. |
extension_version | String | Yes | The version of the extension to update. |
required_configuration | String | Yes | The required_configuration string to use with the extension. |
Response Codes
Code | Description |
---|---|
204 Not Found | Successfully updated the extension’s required_configuration string. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X PUT 'https://api.twitch.tv/helix/extensions/required_configuration?broadcaster_id=274637212' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"required_configuration": "RCS",
"extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2",
"extension_version": "0.0.1"
}'
Send Extension PubSub Message
✎Sends a message to one or more viewers. You can send messages to a specific channel or to all channels where your extension is active. This endpoint uses the same mechanism as the send JavaScript helper function used to send messages.
Rate Limits: You may send a maximum of 100 messages per minute per combination of extension client ID and broadcaster ID.
Authorization
Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role
, user_id
, and exp
fields (see JWT Schema) along with the channel_id
and pubsub_perms
fields. The role
field must be set to external.
To send the message to a specific channel, set the channel_id
field in the JWT to the channel’s ID and set the pubsub_perms.send
array to broadcast.
{
"exp": 1503343947,
"user_id": "27419011",
"role": "external",
"channel_id": "27419011",
"pubsub_perms": {
"send":[
"broadcast"
]
}
}
To send the message to all channels on which your extension is active, set the channel_id
field to all and set the pubsub_perms.send
array to global.
{
"exp": 1503343947,
"user_id": "27419011",
"role": "external",
"channel_id": "all",
"pubsub_perms": {
"send":[
"global"
]
}
}
URL
POST https://api.twitch.tv/helix/extensions/pubsub
Request Body
Field | Type | Required? | Description |
---|---|---|---|
target | String[] | Yes | The target of the message. Possible values are:
is_global_broadcast is true, you must set this field to global. The broadcast and global values are mutually exclusive; specify only one of them. |
broadcaster_id | string | Yes | The ID of the broadcaster to send the message to. Don’t include this field if is_global_broadcast is set to true. |
is_global_broadcast | Boolean | No | A Boolean value that determines whether the message should be sent to all channels where your extension is active. Set to true if the message should be sent to all channels. The default is false. |
message | String | Yes | The message to send. The message can be a plain-text string or a string-encoded JSON object. The message is limited to a maximum of 5 KB. |
Response Codes
Code | Description |
---|---|
204 No Content | Successfully sent the message. |
400 Bad Request |
|
401 Unauthorized |
|
422 Unprocessable Entity |
|
Example Request
curl -X POST 'https://api.twitch.tv/helix/extensions/pubsub' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"message": "hello world!",
"broadcaster_id": "141981764",
"target": ["broadcast"]
}'
Get Extension Live Channels
✎Gets a list of broadcasters that are streaming live and have installed or activated the extension.
It may take a few minutes for the list to include or remove broadcasters that have recently gone live or stopped broadcasting.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/extensions/live
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
extension_id | String | Yes | The ID of the extension to get. Returns the list of broadcasters that are live and that have installed or activated this extension. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20. |
after | String | No | The cursor used to get the next page of results. The pagination field in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of broadcasters that are streaming live and that have installed or activated the extension. |
broadcaster_id | String | The ID of the broadcaster that is streaming live and has installed or activated the extension. |
broadcaster_name | String | The broadcaster’s display name. |
game_name | String | The name of the category or game being streamed. |
game_id | String | The ID of the category or game being streamed. |
title | String | The title of the broadcaster’s stream. May be an empty string if not specified. |
pagination | String | This field contains the cursor used to page through the results. The field is empty if there are no more pages left to page through. Note that this field is a string compared to other endpoints that use a Pagination object. Read More |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of broadcasters. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/extensions/live?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"broadcaster_id": "252766116",
"broadcaster_name": "swoosh_xii",
"game_name": "Tom Clancy's Rainbow Six Siege",
"game_id": "460630",
"title": "[PS4] ITA/ENG UNRANKED CHILLIN' (SUB 1/15) - !instagram !donation !sens !team !youtube"
},
{
"broadcaster_id": "264525686",
"broadcaster_name": "gaddem_",
"game_name": "For Honor",
"game_id": "490382",
"title": "any Kätzchen ? - 680 Rep + > Kompetitive Kitten"
},
{
"broadcaster_id": "264787895",
"broadcaster_name": "LenhadorGameplay",
"game_name": "For Honor",
"game_id": "490382",
"title": "Vazou o novo personagem! *Triste*"
}
],
"pagination": "YVc1emRHRnNiQ015TmpJek5qazVOVHBoYWpKbGRIZDFaR0Z5YjNCMGN6UTJNMkZ1TUdwM2FHWnBZbm8yYW5rNjoy"
}
Get Extension Secrets
✎Gets an extension’s list of shared secrets.
Authorization
Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role
, user_id
, and exp
fields (see JWT Schema). The role
field must be set to external.
URL
GET https://api.twitch.tv/helix/extensions/jwt/secrets
Request Query Paramters
Parameter | Type | Required? | Description |
---|---|---|---|
extension_id | String | Yes | The ID of the extension whose shared secrets you want to get. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of shared secrets that the extension created. |
format_version | Integer | The version number that identifies this definition of the secret’s data. |
secrets | Object[] | The list of secrets. |
content | String | The raw secret that you use with JWT encoding. |
active_at | String | The UTC date and time (in RFC3339 format) that you may begin using this secret to sign a JWT. |
expires_at | String | The UTC date and time (in RFC3339 format) that you must stop using this secret to decode a JWT. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of secrets. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/extensions/jwt/secrets?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"format_version": 1,
"secrets": [
{
"content": "secret",
"active_at": "2021-03-29T06:58:40.858343036Z",
"expires_at": "2121-03-05T06:58:40.858343036Z"
}
]
}
]
}
Create Extension Secret
✎Creates a shared secret used to sign and verify JWT tokens. Creating a new secret removes the current secrets from service. Use this function only when you are ready to use the new secret it returns.
Authorization
Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role
, user_id
, and exp
fields (see JWT Schema). The role
field must be set to external.
URL
POST https://api.twitch.tv/helix/extensions/jwt/secrets
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
extension_id | String | Yes | The ID of the extension to apply the shared secret to. |
delay | Integer | No | The amount of time, in seconds, to delay activating the secret. The delay should provide enough time for instances of the extension to gracefully switch over to the new secret. The minimum delay is 300 seconds (5 minutes). The default is 300 seconds. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the newly added secrets. |
format_version | Integer | The version number that identifies this definition of the secret’s data. |
secrets | Object[] | The list of secrets. |
content | String | The raw secret that you use with JWT encoding. |
active_at | String | The UTC date and time (in RFC3339 format) that you may begin using this secret to sign a JWT. |
expires_at | String | The UTC date and time (in RFC3339 format) that you must stop using this secret to decode a JWT. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully created the new secret. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X POST 'https://api.twitch.tv/helix/extensions/jwt/secrets?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2&delay=600' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"format_version": 1,
"secrets": [
{
"content": "old-secret",
"active_at": "2021-03-29T06:58:40.858343036Z",
"expires_at": "2021-04-22T05:21:54.99261682Z"
},
{
"content": "new-secret",
"active_at": "2021-04-22T04:16:54.996365329Z",
"expires_at": "2121-03-29T04:16:54.996365329Z"
}
]
}
]
}
Send Extension Chat Message
✎Sends a message to the specified broadcaster’s chat room. The extension’s name is used as the username for the message in the chat room. To send a chat message, your extension must enable Chat Capabilities (under your extension’s Capabilities tab).
Rate Limits: You may send a maximum of 12 messages per minute per channel.
Authorization
Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role
and user_id
fields (see JWT Schema). The role
field must be set to external.
URL
POST https://api.twitch.tv/helix/extensions/chat
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that has activated the extension. |
Request Body
Field | Type | Required? | Description |
---|---|---|---|
text | String | Yes | The message. The message may contain a maximum of 280 characters. |
extension_id | String | Yes | The ID of the extension that’s sending the chat message. |
extension_version | String | Yes | The extension’s version number. |
Response Codes
Code | Description |
---|---|
204 No Content | Successfully sent the chat message. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X POST 'https://api.twitch.tv/helix/extensions/chat?broadcaster_id=237757755' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"text": "Hello",
"extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2",
"extension_version": "0.0.9"
}
Get Extensions
✎Gets information about an extension.
Authorization
Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role
field (see JWT Schema), and the role
field must be set to external.
URL
GET https://api.twitch.tv/helix/extensions
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
extension_id | String | Yes | The ID of the extension to get. |
extension_version | String | No | The version of the extension to get. If not specified, it returns the latest, released version. If you don’t have a released version, you must specify a version; otherwise, the list is empty. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the specified extension. |
author_name | String | The name of the user or organization that owns the extension. |
bits_enabled | Boolean | A Boolean value that determines whether the extension has features that use Bits. Is true if the extension has features that use Bits. |
can_install | Boolean | A Boolean value that determines whether a user can install the extension on their channel. Is true if a user can install the extension. Typically, this is set to false if the extension is currently in testing mode and requires users to be allowlisted (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Access). |
configuration_location | String | The location of where the extension’s configuration is stored. Possible values are:
|
description | String | A longer description of the extension. It appears on the details page. |
eula_tos_url | String | A URL to the extension’s Terms of Service. |
has_chat_support | Boolean | A Boolean value that determines whether the extension can communicate with the installed channel’s chat. Is true if the extension can communicate with the channel’s chat room. |
icon_url | String | A URL to the default icon that’s displayed in the Extensions directory. |
icon_urls | map[string]string | A dictionary that contains URLs to different sizes of the default icon. The dictionary’s key identifies the icon’s size (for example, 24x24), and the dictionary’s value contains the URL to the icon. |
id | String | The extension’s ID. |
name | String | The extension’s name. |
privacy_policy_url | String | A URL to the extension’s privacy policy. |
request_identity_link | Boolean | A Boolean value that determines whether the extension wants to explicitly ask viewers to link their Twitch identity. |
screenshot_urls | String[] | A list of URLs to screenshots that are shown in the Extensions marketplace. |
state | String | The extension’s state. Possible values are:
|
subscriptions_support_level | String | Indicates whether the extension can view the user’s subscription level on the channel that the extension is installed on. Possible values are:
|
summary | String | A short description of the extension that streamers see when hovering over the discovery splash screen in the Extensions manager. |
support_email | String | The email address that users use to get support for the extension. |
version | String | The extension’s version number. |
viewer_summary | String | A brief description displayed on the channel to explain how the extension works. |
views | Object | Describes all views-related information such as how the extension is displayed on mobile devices. |
mobile | Object | Describes how the extension is displayed on mobile devices. |
viewer_url | String | The HTML file that is shown to viewers on mobile devices. This page is presented to viewers as a panel behind the chat area of the mobile app. |
panel | Object | Describes how the extension is rendered if the extension may be activated as a panel extension. |
viewer_url | String | The HTML file that is shown to viewers on the channel page when the extension is activated in a Panel slot. |
height | Integer | The height, in pixels, of the panel component that the extension is rendered in. |
can_link_external_content | Boolean | A Boolean value that determines whether the extension can link to non-Twitch domains. |
video_overlay | Object | Describes how the extension is rendered if the extension may be activated as a video-overlay extension. |
viewer_url | String | The HTML file that is shown to viewers on the channel page when the extension is activated on the Video - Overlay slot. |
can_link_external_content | Boolean | A Boolean value that determines whether the extension can link to non-Twitch domains. |
component | Object | Describes how the extension is rendered if the extension may be activated as a video-component extension. |
viewer_url | String | The HTML file that is shown to viewers on the channel page when the extension is activated in a Video - Component slot. |
aspect_ratio_x | Integer | The width value of the ratio (width : height) which determines the extension’s width, and how the extension’s iframe will resize in different video player environments. |
aspect_ratio_y | Integer | The height value of the ratio (width : height) which determines the extension’s height, and how the extension’s iframe will resize in different video player environments. |
autoscale | Boolean | A Boolean value that determines whether to apply CSS zoom. If true, a CSS zoom is applied such that the size of the extension is variable but the inner dimensions are fixed based on Scale Pixels. This allows your extension to render as if it is of fixed width and height. If false, the inner dimensions of the extension iframe are variable, meaning your extension must implement responsiveness. |
scale_pixels | Integer | The base width, in pixels, of the extension to use when scaling (see autoscale ). This value is ignored if autoscale is false. |
target_height | Integer | The height as a percent of the maximum height of a video component extension. Values are between 1% - 100%. |
can_link_external_content | Boolean | A Boolean value that determines whether the extension can link to non-Twitch domains. |
config | Object | Describes the view that is shown to broadcasters while they are configuring your extension within the Extension Manager. |
viewer_url | String | The HTML file shown to broadcasters while they are configuring your extension within the Extension Manager. |
can_link_external_content | Boolean | A Boolean value that determines whether the extension can link to non-Twitch domains. |
allowlisted_config_urls | String[] | Allowlisted configuration URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities). |
allowlisted_panel_urls | String[] | Allowlisted panel URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities). |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of extensions. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/extensions?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2&extension_version=0.0.9' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"author_name": "Twitch Developers",
"bits_enabled": true,
"can_install": false,
"configuration_location": "hosted",
"description": "An extension for testing all the features that we add to extensions",
"eula_tos_url": "",
"has_chat_support": true,
"icon_url": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
"icon_urls": {
"100x100": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
"24x24": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/taskbar905b19da-e7e5-4d8f-beb7-f543a861ac1e",
"300x200": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/discoveryd9545b2c-5474-46d7-a523-1c3835d862ce"
},
"id": "pgn0bjv51epi7eaekt53tovjnc82qo",
"name": "Official Developers Demo",
"privacy_policy_url": "",
"request_identity_link": true,
"screenshot_urls": [
"https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/screenshotbdec475d-3d2f-4378-b334-941dfddc897a"
],
"state": "Released",
"subscriptions_support_level": "optional",
"summary": "Test ALL the extensions features!",
"support_email": "dx-extensions-test-dev@justin.tv",
"version": "0.0.9",
"viewer_summary": "Test ALL the extensions features!",
"views": {
"mobile": {
"viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html"
},
"panel": {
"viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
"height": 300,
"can_link_external_content": false
},
"video_overlay": {
"viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
"can_link_external_content": false
},
"component": {
"viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
"aspect_width": 0,
"aspect_height": 0,
"aspect_ratio_x": 48000,
"aspect_ratio_y": 36000,
"autoscale": true,
"scale_pixels": 1024,
"target_height": 5333,
"size": 0,
"zoom": false,
"zoom_pixels": 0,
"can_link_external_content": false
}
},
"allowlisted_config_urls": [],
"allowlisted_panel_urls": []
}
]
}
Get Released Extensions
✎Gets information about a released extension. Returns the extension if its state
is Released.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/extensions/released
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
extension_id | String | Yes | The ID of the extension to get. |
extension_version | String | No | The version of the extension to get. If not specified, it returns the latest version. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the specified extension. |
author_name | String | The name of the user or organization that owns the extension. |
bits_enabled | Boolean | A Boolean value that determines whether the extension has features that use Bits. Is true if the extension has features that use Bits. |
can_install | Boolean | A Boolean value that determines whether a user can install the extension on their channel. Is true if a user can install the extension. Typically, this is set to false if the extension is currently in testing mode and requires users to be allowlisted (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Access). |
configuration_location | String | The location of where the extension’s configuration is stored. Possible values are:
|
description | String | A longer description of the extension. It appears on the details page. |
eula_tos_url | String | A URL to the extension’s Terms of Service. |
has_chat_support | Boolean | A Boolean value that determines whether the extension can communicate with the installed channel’s chat. Is true if the extension can communicate with the channel’s chat room. |
icon_url | String | A URL to the default icon that’s displayed in the Extensions directory. |
icon_urls | map[string]string | A dictionary that contains URLs to different sizes of the default icon. The dictionary’s key identifies the icon’s size (for example, 24x24), and the dictionary’s value contains the URL to the icon. |
id | String | The extension’s ID. |
name | String | The extension’s name. |
privacy_policy_url | String | A URL to the extension’s privacy policy. |
request_identity_link | Boolean | A Boolean value that determines whether the extension wants to explicitly ask viewers to link their Twitch identity. |
screenshot_urls | String[] | A list of URLs to screenshots that are shown in the Extensions marketplace. |
state | String | The extension’s state. Possible values are:
|
subscriptions_support_level | String | Indicates whether the extension can view the user’s subscription level on the channel that the extension is installed on. Possible values are:
|
summary | String | A short description of the extension that streamers see when hovering over the discovery splash screen in the Extensions manager. |
support_email | String | The email address that users use to get support for the extension. |
version | String | The extension’s version number. |
viewer_summary | String | A brief description displayed on the channel to explain how the extension works. |
views | Object | Describes all views-related information such as how the extension is displayed on mobile devices. |
mobile | Object | Describes how the extension is displayed on mobile devices. |
viewer_url | String | The HTML file that is shown to viewers on mobile devices. This page is presented to viewers as a panel behind the chat area of the mobile app. |
panel | Object | Describes how the extension is rendered if the extension may be activated as a panel extension. |
viewer_url | String | The HTML file that is shown to viewers on the channel page when the extension is activated in a Panel slot. |
height | Integer | The height, in pixels, of the panel component that the extension is rendered in. |
can_link_external_content | Boolean | A Boolean value that determines whether the extension can link to non-Twitch domains. |
video_overlay | Object | Describes how the extension is rendered if the extension may be activated as a video-overlay extension. |
viewer_url | String | The HTML file that is shown to viewers on the channel page when the extension is activated on the Video - Overlay slot. |
can_link_external_content | Boolean | A Boolean value that determines whether the extension can link to non-Twitch domains. |
component | Object | Describes how the extension is rendered if the extension may be activated as a video-component extension. |
viewer_url | String | The HTML file that is shown to viewers on the channel page when the extension is activated in a Video - Component slot. |
aspect_ratio_x | Integer | The width value of the ratio (width : height) which determines the extension’s width, and how the extension’s iframe will resize in different video player environments. |
aspect_ratio_y | Integer | The height value of the ratio (width : height) which determines the extension’s height, and how the extension’s iframe will resize in different video player environments. |
autoscale | Boolean | A Boolean value that determines whether to apply CSS zoom. If true, a CSS zoom is applied such that the size of the extension is variable but the inner dimensions are fixed based on Scale Pixels. This allows your extension to render as if it is of fixed width and height. If false, the inner dimensions of the extension iframe are variable, meaning your extension must implement responsiveness. |
scale_pixels | Integer | The base width, in pixels, of the extension to use when scaling (see autoscale ). This value is ignored if autoscale is false. |
target_height | Integer | The height as a percent of the maximum height of a video component extension. Values are between 1% - 100%. |
can_link_external_content | Boolean | A Boolean value that determines whether the extension can link to non-Twitch domains. |
config | Object | Describes the view that is shown to broadcasters while they are configuring your extension within the Extension Manager. |
viewer_url | String | The HTML file shown to broadcasters while they are configuring your extension within the Extension Manager. |
can_link_external_content | Boolean | A Boolean value that determines whether the extension can link to non-Twitch domains. |
allowlisted_config_urls | String[] | Allowlisted configuration URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities). |
allowlisted_panel_urls | String[] | Allowlisted panel URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities). |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the extension. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/extensions/released?extension_version=0.0.9&extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"author_name": "Twitch Developer Experience",
"bits_enabled": true,
"can_install": false,
"configuration_location": "hosted",
"description": "An extension for testing all the features that we add to extensions",
"eula_tos_url": "",
"has_chat_support": true,
"icon_url": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
"icon_urls": {
"100x100": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
"24x24": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/taskbar905b19da-e7e5-4d8f-beb7-f543a861ac1e",
"300x200": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/discoveryd9545b2c-5474-46d7-a523-1c3835d862ce"
},
"id": "pgn0bjv51epi7eaekt53tovjnc82qo",
"name": "Official Developer Experience Demo",
"privacy_policy_url": "",
"request_identity_link": true,
"screenshot_urls": [
"https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/screenshotbdec475d-3d2f-4378-b334-941dfddc897a"
],
"state": "Released",
"subscriptions_support_level": "optional",
"summary": "Test ALL the extensions features!",
"support_email": "dx-extensions-test-dev@justin.tv",
"version": "0.0.9",
"viewer_summary": "Test ALL the extensions features!",
"views": {
"mobile": {
"viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html"
},
"panel": {
"viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
"height": 300,
"can_link_external_content": false
},
"video_overlay": {
"viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
"can_link_external_content": false
},
"component": {
"viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
"aspect_width": 0,
"aspect_height": 0,
"aspect_ratio_x": 48000,
"aspect_ratio_y": 36000,
"autoscale": true,
"scale_pixels": 1024,
"target_height": 5333,
"size": 0,
"zoom": false,
"zoom_pixels": 0,
"can_link_external_content": false
}
},
"allowlisted_config_urls": [],
"allowlisted_panel_urls": []
}
]
}
Get Extension Bits Products
✎Gets the list of Bits products that belongs to the extension. The client ID in the app access token identifies the extension.
Authorization
Requires an app access token. The client ID in the app access token must be the extension’s client ID.
URL
GET https://api.twitch.tv/helix/bits/extensions
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
should_include_all | Boolean | No | A Boolean value that determines whether to include disabled or expired Bits products in the response. The default is false. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list of Bits products that the extension created. The list is in ascending SKU order. The list is empty if the extension hasn’t created any products or they’re all expired or disabled. |
sku | String | The product’s SKU. The SKU is unique across an extension’s products. |
cost | Object | An object that contains the product’s cost information. |
amount | Integer | The product’s price. |
type | String | The type of currency. Possible values are:
|
in_development | Boolean | A Boolean value that indicates whether the product is in development. If true, the product is not available for public use. |
display_name | String | The product’s name as displayed in the extension. |
expiration | String | The date and time, in RFC3339 format, when the product expires. |
is_broadcast | Boolean | A Boolean value that determines whether Bits product purchase events are broadcast to all instances of an extension on a channel. The events are broadcast via the onTransactionComplete helper callback. Is true if the event is broadcast to all instances. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of products. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Gets the extension’s products including its disabled and expired products.
curl -X GET 'https://api.twitch.tv/helix/bits/extensions?should_include_all=true' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"sku": "1010",
"cost": {
"amount": 990,
"type": "bits"
},
"in_development": true,
"display_name": "Rusty Crate 2",
"expiration": "2021-05-18T09:10:13.397Z",
"is_broadcast": false
}
]
}
Update Extension Bits Product
✎Adds or updates a Bits product that the extension created. If the SKU doesn’t exist, the product is added. You may update all fields except the sku
field.
Authorization
Requires an app access token. The client ID in the app access token must match the extension’s client ID.
URL
PUT https://api.twitch.tv/helix/bits/extensions
Request Body Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
sku | String | Yes | The product's SKU. The SKU must be unique within an extension. The product's SKU cannot be changed. The SKU may contain only alphanumeric characters, dashes (-), underscores (_), and periods (.) and is limited to a maximum of 255 characters. No spaces. |
cost | Object | Yes | An object that contains the product's cost information. |
amount | Integer | Yes | The product's price. |
type | String | Yes | The type of currency. Possible values are:
|
display_name | String | Yes | The product's name as displayed in the extension. The maximum length is 255 characters. |
in_development | Boolean | No | A Boolean value that indicates whether the product is in development. Set to true if the product is in development and not available for public use. The default is false. |
expiration | String | No | The date and time, in RFC3339 format, when the product expires. If not set, the product does not expire. To disable the product, set the expiration date to a date in the past. |
is_broadcast | Boolean | No | A Boolean value that determines whether Bits product purchase events are broadcast to all instances of the extension on a channel. The events are broadcast via the onTransactionComplete helper callback. The default is false. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list of Bits products that the extension created. The list is in ascending SKU order. The list is empty if the extension hasn't created any products or they're all expired or disabled. |
sku | String | The product's SKU. The SKU is unique across an extension's products. |
cost | Object | An object that contains the product's cost information. |
amount | Integer | The product's price. |
type | String | The type of currency. Possible values are:
|
in_development | Boolean | A Boolean value that indicates whether the product is in development. If true, the product is not available for public use. |
display_name | String | The product's name as displayed in the extension. |
expiration | String | The date and time, in RFC3339 format, when the product expires. |
is_broadcast | Boolean | A Boolean value that determines whether Bits product purchase events are broadcast to all instances of an extension on a channel. The events are broadcast via the onTransactionComplete helper callback. Is true if the event is broadcast to all instances. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully created the product. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X PUT 'https://api.twitch.tv/helix/bits/extensions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d {
"sku": "1010",
"cost": {
"amount": 990,
"type": "bits"
},
"in_development": true,
"display_name": "Rusty Crate 2",
"is_broadcast": true,
"expiration": "2021-05-18T09:10:13.397Z"
}
Example Response
{
"data": [
{
"sku": "1010",
"cost": {
"amount": 990,
"type": "bits"
},
"in_development": true,
"display_name": "Rusty Crate 2",
"expiration": "2021-05-18T09:10:13.397Z",
"is_broadcast": true
}
]
}
Create EventSub Subscription
✎Creates an EventSub subscription.
Authorization
If you use webhooks to receive events, the request must specify an app access token. The request will fail if you use a user access token. If the subscription type requires user authorization, the user must have granted your app (client ID) permissions to receive those events before you subscribe to them. For example, to subscribe to channel.subscribe events, your app must get a user access token that includes the channel:read:subscriptions
scope, which adds the required permission to your app access token’s client ID.
If you use WebSockets to receive events, the request must specify a user access token. The request will fail if you use an app access token. If the subscription type requires user authorization, the token must include the required scope. However, if the subscription type doesn’t include user authorization, the token may include any scopes or no scopes.
If you use Conduits to receive events, the request must specify an app access token. The request will fail if you use a user access token.
URL
POST https://api.twitch.tv/helix/eventsub/subscriptions
Request Body
Parameter | Type | Required | Description |
---|---|---|---|
type | String | Yes | The type of subscription to create. For a list of subscriptions that you can create, see Subscription Types. Set this field to the value in the Name column of the Subscription Types table. |
version | String | Yes | The version number that identifies the definition of the subscription type that you want the response to use. |
condition | Object | Yes | A JSON object that contains the parameter values that are specific to the specified subscription type. For the object’s required and optional fields, see the subscription type’s documentation. |
transport | Object | Yes | The transport details that you want Twitch to use when sending you notifications. |
method | String | Yes | The transport method. Possible values are:
|
callback | String | No | The callback URL where the notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an event. Specify this field only if NOTE: Redirects are not followed. |
secret | String | No | The secret used to verify the signature. The secret must be an ASCII string that’s a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message. Specify this field only if method is set to webhook. |
session_id | String | No | An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message. Specify this field only if method is set to websocket. |
conduit_id | String | No | An ID that identifies the conduit to send notifications to. When you create a conduit, the server returns the conduit ID. Specify this field only if method is set to conduit. |
Response Body
Parameter | Type | Description |
---|---|---|
data | Object[] | A list that contains the single subscription that you created. |
id | String | An ID that identifies the subscription. |
status | String | The subscription’s status. The subscriber receives events only for enabled subscriptions. Possible values are:
|
type | String | The subscription’s type. See Subscription Types. |
version | String | The version number that identifies this definition of the subscription’s data. |
condition | Object | The subscription’s parameter values. This is a string-encoded JSON object whose contents are determined by the subscription type. |
created_at | String | The date and time (in RFC3339 format) of when the subscription was created. |
transport | Object | The transport details used to send the notifications. |
method | String | The transport method. Possible values are:
|
callback | String | The callback URL where the notifications are sent. Included only if method is set to webhook. |
session_id | String | An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket. |
connected_at | String | The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket. |
conduit_id | String | An ID that identifies the conduit to send notifications to. Included only if method is set to conduit. |
cost | Integer | The amount that the subscription counts against your limit. Learn More |
total | Integer | The total number of subscriptions you’ve created. |
total_cost | Integer | The sum of all of your subscription costs. Learn More |
max_total_cost | Integer | The maximum total cost that you’re allowed to incur for all subscriptions you create. |
Response Codes
Code | Meaning |
---|---|
202 Accepted | Successfully accepted the subscription request. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden | The access token is missing the required scopes. |
409 Conflict | A subscription already exists for the specified event type and condition combination. |
429 Too Many Requests | The request exceeds the number of subscriptions that you may create with the same combination of |
Example Request 1
For a webhook method
type. Adds a user.update subscription.
curl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
-d '{
"type": "user.update",
"version": "1",
"condition": {
"user_id": "1234"
},
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com",
"secret":"s3cre7"
}
}'
# Twitch CLI example that adds a user.update subscription.
twitch api post /eventsub/subscriptions -b '{"type":"user.update","version":"1","condition":{"user_id":"1234"},"transport":{"method":"webhook","callback":"https://this-is-a-callback.com","secret":"s3cre7"}}'Example Response - Webhook
Example Response 1
{
"data": [
{
"id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
"status": "webhook_callback_verification_pending",
"type": "user.update",
"version": "1",
"condition": {
"user_id": "1234"
},
"created_at": "2020-11-10T14:32:18.730260295Z",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
},
"cost": 1
}
],
"total": 1,
"total_cost": 1,
"max_total_cost": 10000
}
Example Request 2
For a websocket method
type.
curl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
-d '{"
type": "user.update",
"version": "1",
"condition": {
"user_id": "1234"
},
"transport": {
"method": "websocket",
"session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
}
}'
Example Response 2
{
"data": [
{
"id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
"status": "webhook_callback_verification_pending",
"type": "user.update",
"version": "1",
"condition": {
"user_id": "1234"
},
"created_at": "2020-11-10T14:32:18.730260295Z",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
},
"cost": 1
}
],
"total": 1,
"total_cost": 1,
"max_total_cost": 10000
}
Example Request 3
For a conduit method
type.
Example RequestExample Requestcurl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
-d '{
"type":"user.update",
"version":"1",
"condition":{
"user_id":"1234"
},
"transport":{
"method":"conduit",
"conduit_id":"bfcfc993-26b1-b876-44d9-afe75a379dac"
}
}'
Example Response 3
{
"data": [
{
"id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
"status": "enabled",
"type": "user.update",
"version": "1",
"condition": {
"user_id": "1234"
},
"created_at": "2020-11-10T14:32:18.730260295Z",
"transport": {
"method": "conduit",
"conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
},
"cost": 1
}
],
"total": 1,
"total_cost": 1,
"max_total_cost": 10000
}
Delete EventSub Subscription
✎Deletes an EventSub subscription.
Authorization
If you use webhooks to receive events, the request must specify an app access token. The request will fail if you use a user access token.
If you use WebSockets to receive events, the request must specify a user access token. The request will fail if you use an app access token. The token may include any scopes.
URL
DELETE https://api.twitch.tv/helix/eventsub/subscriptions
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
id | String | Yes | The ID of the subscription to delete. |
Response Codes
Code | Description |
---|---|
204 No Content | Successfully deleted the subscription. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
Example Request
Deletes the specified EventSub subscription.
curl -X DELETE
'https://api.twitch.tv/helix/eventsub/subscriptions?id=26b1c993-bfcf-44d9-b876-379dacafe75a' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
# Twitch CLI example that deletes the specified subscription.
twitch api delete /eventsub/subscriptions -q id=c839a466-034a-4d77-8d4d-c9a751516e7
Get EventSub Subscriptions
✎Gets a list of EventSub subscriptions that the client in the access token created.
Authorization
If you use Webhooks or Conduits to receive events, the request must specify an app access token. The request will fail if you use a user access token.
If you use WebSockets to receive events, the request must specify a user access token. The request will fail if you use an app access token. The token may include any scopes.
URL
GET https://api.twitch.tv/helix/eventsub/subscriptions
Request Query Parameters
Use the status, type, and user_id query parameters to filter the list of subscriptions that are returned. The filters are mutually exclusive; the request fails if you specify more than one filter.
Parameter | Type | Required? | Description |
---|---|---|---|
status | String | No | Filter subscriptions by its status. Possible values are:
|
type | String | No | Filter subscriptions by subscription type. For a list of subscription types, see Subscription Types. |
user_id | String | No | Filter subscriptions by user ID. The response contains subscriptions where this ID matches a user ID that you specified in the Condition object when you created the subscription. |
after | String | No | The cursor used to get the next page of results. The pagination object in the response contains the cursor's value. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of subscriptions. The list is ordered by the oldest subscription first. The list is empty if the client hasn't created subscriptions or there are no subscriptions that match the specified filter criteria. |
id | String | An ID that identifies the subscription. |
status | String | The subscription's status. The subscriber receives events only for enabled subscriptions. Possible values are:
|
type | String | The subscription's type. See Subscription Types. |
version | String | The version number that identifies this definition of the subscription's data. |
condition | Object | The subscription's parameter values. This is a string-encoded JSON object whose contents are determined by the subscription type. |
created_at | String | The date and time (in RFC3339 format) of when the subscription was created. |
transport | Object | The transport details used to send the notifications. |
method | String | The transport method. Possible values are:
|
callback | String | The callback URL where the notifications are sent. Included only if method is set to webhook. |
session_id | String | An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket. |
connected_at | String | The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket. |
disconnected_at | String | The UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket. |
cost | Integer | The amount that the subscription counts against your limit. Learn More |
total | Integer | The total number of subscriptions that you've created. |
total_cost | Integer | The sum of all of your subscription costs. Learn More |
max_total_cost | Integer | The maximum total cost that you're allowed to incur for all subscriptions that you create. |
pagination | Object | An object that contains the cursor used to get the next page of subscriptions. The object is empty if there are no more pages to get. The number of subscriptions returned per page is undertermined. |
cursor | String | The cursor value that you set the after query parameter to. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the subscriptions. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Gets a list of EventSub subscriptions that you created. The list is ordered by the oldest subscription first.
curl -X GET 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
# Twitch CLI example that gets a list of EventSub subscriptions that you created.
twitch api get /eventsub/subscriptions
Example Response
{
"total": 2,
"data": [
{
"id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
"status": "enabled",
"type": "stream.online",
"version": "1",
"condition": {
"broadcaster_user_id": "1234"
},
"created_at": "2020-11-10T20:08:33.12345678Z",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
},
"cost": 1
},
{
"id": "35016908-41ff-33ce-7879-61b8dfc2ee16",
"status": "webhook_callback_verification_pending",
"type": "user.update",
"version": "1",
"condition": {
"user_id": "1234"
},
"created_at": "2020-11-10T14:32:18.730260295Z",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
},
"cost": 0
}
],
"total_cost": 1,
"max_total_cost": 10000,
"pagination": {}
}
Get Top Games
✎Gets information about all broadcasts on Twitch.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/games/top
Request Query Parameters
Parameter | Type | Required ? | Description |
---|---|---|---|
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
before | String | No | The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Fields | Type | Description |
---|---|---|
data | Object[] | The list of broadcasts. The broadcasts are sorted by the number of viewers, with the most popular first. |
id | String | An ID that identifies the category or game. |
name | String | The category’s or game’s name. |
box_art_url | String | A URL to the category’s or game’s box art. You must replace the {width}x{height} placeholder with the size of image you want. |
igdb_id | String | The ID that IGDB uses to identify this game. If the IGDB ID is not available to Twitch, this field is set to an empty string. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after or before query parameter to get the next or previous page of results. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of broadcasts. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/games/top' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "493057",
"name": "PUBG: BATTLEGROUNDS",
"box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/493057-{width}x{height}.jpg",
"igdb_id": "27789"
},
...
],
"pagination":{"cursor":"eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ=="}
}
Get Games
✎Gets information about specified categories or games.
You may get up to 100 categories or games by specifying their ID or name. You may specify all IDs, all names, or a combination of IDs and names. If you specify a combination of IDs and names, the total number of IDs and names must not exceed 100.
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/games
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
id | String | Yes | The ID of the category or game to get. Include this parameter for each category or game you want to get. For example, &id=1234&id=5678 . You may specify a maximum of 100 IDs. The endpoint ignores duplicate and invalid IDs or IDs that weren’t found. |
name | String | Yes | The name of the category or game to get. The name must exactly match the category’s or game’s title. Include this parameter for each category or game you want to get. For example, &name=foo&name=bar . You may specify a maximum of 100 names. The endpoint ignores duplicate names and names that weren’t found. |
igdb_id | String | Yes | The IGDB ID of the game to get. Include this parameter for each game you want to get. For example, &igdb_id=1234&igdb_id=5678 . You may specify a maximum of 100 IDs. The endpoint ignores duplicate and invalid IDs or IDs that weren’t found. |
Response Body
Fields | Type | Description |
---|---|---|
data | Object[] | The list of categories and games. The list is empty if the specified categories and games weren’t found. |
id | String | An ID that identifies the category or game. |
name | String | The category’s or game’s name. |
box_art_url | String | A URL to the category’s or game’s box art. You must replace the {width}x{height} placeholder with the size of image you want. |
igdb_id | String | The ID that IGDB uses to identify this game. If the IGDB ID is not available to Twitch, this field is set to an empty string. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the specified games. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/games?id=33214' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "33214",
"name": "Fortnite",
"box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/33214-{width}x{height}.jpg",
"igdb_id": "1905"
}
]
}
Get Creator Goals
✎Gets the broadcaster’s list of active goals. Use this endpoint to get the current progress of each goal.
Instead of polling for the progress of a goal, consider subscribing to receive notifications when a goal makes progress using the channel.goal.progress subscription type. Read More
Authorization
Requires a user access token that includes the channel:read:goals scope.
URL
GET https://api.twitch.tv/helix/goals
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that created the goals. This ID must match the user ID in the user access token. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of goals. The list is empty if the broadcaster hasn’t created goals. |
id | String | An ID that identifies this goal. |
broadcaster_id | String | An ID that identifies the broadcaster that created the goal. |
broadcaster_name | String | The broadcaster’s display name. |
broadcaster_login | String | The broadcaster’s login name. |
type | String | The type of goal. Possible values are:
|
description | String | A description of the goal. Is an empty string if not specified. |
current_amount | Integer | The goal’s current value. The goal’s type determines how this value is increased or decreased.
|
target_amount | Integer | The goal’s target value. For example, if the broadcaster has 200 followers before creating the goal, and their goal is to double that number, this field is set to 400. |
created_at | string | The UTC date and time (in RFC3339 format) that the broadcaster created the goal. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s goals. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/goals?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
# Twitch CLI example that gets the broadcaster's goals.
twitch api get /goals -q broadcaster_id=141981764
Example Response
{
"data": [
{
"id": "1woowvbkiNv8BRxEWSqmQz6Zk92",
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"type": "follower",
"description": "Follow goal for Helix testing",
"current_amount": 27062,
"target_amount": 30000,
"created_at": "2021-08-16T17:22:23Z"
}
]
}
Get Channel Guest Star Settings
✎BETA Gets the channel settings for configuration of the Guest Star feature for a particular host.
Authorization
- Query parameter
moderator_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:read:guest_star
,channel:manage:guest_star
,moderator:read:guest_star
ormoderator:manage:guest_star
URL
GET https://api.twitch.tv/helix/guest_star/channel_settings
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster you want to get guest star settings for. |
moderator_id | Yes | String | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
Response Body
Parameter | Type | Description |
---|---|---|
is_moderator_send_live_enabled | Boolean | Flag determining if Guest Star moderators have access to control whether a guest is live once assigned to a slot. |
slot_count | Integer | Number of slots the Guest Star call interface will allow the host to add to a call. Required to be between 1 and 6. |
is_browser_source_audio_enabled | Boolean | Flag determining if Browser Sources subscribed to sessions on this channel should output audio |
group_layout | String | This setting determines how the guests within a session should be laid out within the browser source. Can be one of the following values:
|
browser_source_token | String | View only token to generate browser source URLs |
Response Codes
Code | Meaning |
---|---|
400 Bad Request |
|
403 Forbidden | Insufficient authorization for viewing channel’s Guest Star settings |
Example Request
curl -x GET `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&moderator_id=9321049` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"is_moderator_send_live_enabled": true, "slot_count": 4, "is_browser_source_audio_enabled": true, "layout": "TILED_LAYOUT", "browser_source_token": "eihq8rew7q3hgierufhi3q"
}
]
}
Update Channel Guest Star Settings
✎BETA Mutates the channel settings for configuration of the Guest Star feature for a particular host.
Authorization
- Query parameter
broadcaster_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:manage:guest_star
URL
PUT https://api.twitch.tv/helix/guest_star/channel_settings
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster you want to update Guest Star settings for. |
Request Body
Parameter | Required | Type | Description |
---|---|---|---|
is_moderator_send_live_enabled | No | Boolean | Flag determining if Guest Star moderators have access to control whether a guest is live once assigned to a slot. |
slot_count | No | Integer | Number of slots the Guest Star call interface will allow the host to add to a call. Required to be between 1 and 6. |
is_browser_source_audio_enabled | No | Boolean | Flag determining if Browser Sources subscribed to sessions on this channel should output audio |
group_layout | No | String | This setting determines how the guests within a session should be laid out within the browser source. Can be one of the following values:
|
regenerate_browser_sources | No | Boolean | Flag determining if Guest Star should regenerate the auth token associated with the channel’s browser sources. Providing a true value for this will immediately invalidate all browser sources previously configured in your streaming software. |
Response Codes
Code | Meaning |
---|---|
204 No Content | Successfully updated channel settings |
400 Bad Request |
|
Example Request 1
Update browser source layout settings
curl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&group_layout=TILED_LAYOUT` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Request 2
Disable moderator control of slot live setting
curl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&is_moderator_send_live_enabled=false` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Request 3
Update max slot count
curl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&slot_count=6` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Request 4
Regenerate browser sources
curl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049®enerate_browser_sources=true` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Get Guest Star Session
✎BETA Gets information about an ongoing Guest Star session for a particular channel.
Authorization
- Requires OAuth Scope:
channel:read:guest_star
,channel:manage:guest_star
,moderator:read:guest_star
ormoderator:manage:guest_star
- Guests must be either invited or assigned a slot within the session
URL
GET https://api.twitch.tv/helix/guest_star/session
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | ID for the user hosting the Guest Star session. |
moderator_id | Yes | String | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
Response Body
Parameter | Type | Description |
---|---|---|
data | Session[] | Summary of the session details |
id | String | ID uniquely representing the Guest Star session. |
guests | Guest | List of guests currently interacting with the Guest Star session. |
slot_id | String | ID representing this guest’s slot assignment.
|
is_live | Boolean | Flag determining whether or not the guest is visible in the browser source in the host’s streaming software. |
user_id | String | User ID of the guest assigned to this slot. |
user_display_name | String | Display name of the guest assigned to this slot. |
user_login | String | Login of the guest assigned to this slot. |
volume | Integer | Value from 0 to 100 representing the host’s volume setting for this guest. |
assigned_at | String | Timestamp when this guest was assigned a slot in the session. |
audio_settings | MediaSettings | Information about the guest’s audio settings |
is_host_enabled | Boolean | Flag determining whether the host is allowing the guest’s audio to be seen or heard within the session. |
is_guest_enabled | Boolean | Flag determining whether the guest is allowing their audio to be transmitted to the session. |
is_available | Boolean | Flag determining whether the guest has an appropriate audio device available to be transmitted to the session. |
video_settings | MediaSettings | Information about the guest’s video settings |
is_host_enabled | Boolean | Flag determining whether the host is allowing the guest’s video to be seen or heard within the session. |
is_guest_enabled | Boolean | Flag determining whether the guest is allowing their video to be transmitted to the session. |
is_available | Boolean | Flag determining whether the guest has an appropriate video device available to be transmitted to the session. |
Response Codes
Code | Meaning |
---|---|
400 Bad Request |
|
401 Unauthenticated | moderator_id and user token do not match |
Example Request
Get session for host channel
curl -x GET `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049&moderator_id=9321049` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "2KFRQbFtpmfyD3IevNRnCzOPRJI",
"guests": [
{
"slot_id": "0",
"user_id": "9321049",
"user_display_name": "Cool_User",
"user_login": "cool_user",
"is_live": true,
"volume": 100,
"assigned_at": "2023-01-02T04:16:53.325Z",
"audio_settings": {
"is_available": true,
"is_host_enabled": true,
"is_guest_enabled": true,
},
"video_settings": {
"is_available": true,
"is_host_enabled": true,
"is_guest_enabled": true,
}
},
{
"slot_id": "1",
"user_id": "144601104",
"user_display_name": "Cool_Guest",
"user_login": "cool_guest",
"is_live": true,
"volume": 100,
"assigned_at": "2023-01-02T04:20:59.325Z",
"audio_settings": {
"is_available": true,
"is_host_enabled": true,
"is_guest_enabled": true,
},
"video_settings": {
"is_available": true,
"is_host_enabled": true,
"is_guest_enabled": true,
}
}
]
}
]
}
Create Guest Star Session
✎BETA Programmatically creates a Guest Star session on behalf of the broadcaster. Requires the broadcaster to be present in the call interface, or the call will be ended automatically.
Authorization
- Query parameter
broadcaster_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:manage:guest_star
URL
POST https://api.twitch.tv/helix/guest_star/session
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster you want to create a Guest Star session for. Provided broadcaster_id must match the user_id in the auth token. |
Response Body
Parameter | Type | Description |
---|---|---|
data | Session[] | Summary of the session details. |
id | String | ID uniquely representing the Guest Star session. |
guests | Guest | List of guests currently interacting with the Guest Star session. On creation, the session will contain the broadcaster as a solo guest. |
slot_id | String | ID representing this guest’s slot assignment.
|
is_live | Boolean | Flag determining whether or not the guest is visible in the browser source in the host’s streaming software. |
user_id | String | User ID of the guest assigned to this slot. |
user_display_name | String | Display name of the guest assigned to this slot. |
user_login | String | Login of the guest assigned to this slot. |
volume | Integer | Value from 0 to 100 representing the host’s volume setting for this guest. |
assigned_at | String | Timestamp when this guest was assigned a slot in the session. |
audio_settings | MediaSettings | Information about the guest’s audio settings |
is_host_enabled | Boolean | Flag determining whether the host is allowing the guest’s audio to be seen or heard within the session. |
is_guest_enabled | Boolean | Flag determining whether the guest is allowing their audio to be transmitted to the session. |
is_available | Boolean | Flag determining whether the guest has an appropriate audio device available to be transmitted to the session. |
video_settings | MediaSettings | Information about the guest’s video settings |
is_host_enabled | Boolean | Flag determining whether the host is allowing the guest’s video to be seen or heard within the session. |
is_guest_enabled | Boolean | Flag determining whether the guest is allowing their video to be transmitted to the session. |
is_available | Boolean | Flag determining whether the guest has an appropriate video device available to be transmitted to the session. |
Response Codes
Code | Meaning |
---|---|
400 Bad Request |
|
401 Unauthorized | Phone verification missing |
403 Forbidden | Insufficient authorization for creating session |
Example Request
Start Guest Star session
curl -x POST `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "2KFRQbFtpmfyD3IevNRnCzOPRJI",
"guests": [
{
"id": "0",
"user_id": "9321049",
"user_display_name": "Cool_User",
"user_login": "cool_user",
"is_live": true,
"volume": 100,
"assigned_at": "2023-01-02T04:16:53.325Z",
"audio_settings": {
"is_available": true,
"is_host_enabled": true,
"is_guest_enabled": true,
},
"video_settings": {
"is_available": true,
"is_host_enabled": true,
"is_guest_enabled": true,
}
},
]
},
]
}
End Guest Star Session
✎BETA Programmatically ends a Guest Star session on behalf of the broadcaster. Performs the same action as if the host clicked the “End Call” button in the Guest Star UI.
Authorization
- Query parameter
broadcaster_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:manage:guest_star
URL
DELETE https://api.twitch.tv/helix/guest_star/session
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster you want to end a Guest Star session for. Provided broadcaster_id must match the user_id in the auth token. |
session_id | Yes | String | ID for the session to end on behalf of the broadcaster. |
Response Body
Parameter | Type | Description |
---|---|---|
data | Session[] | Summary of the session details when the session was ended. |
id | String | ID uniquely representing the Guest Star session. |
guests | Guest | List of guests currently interacting with the Guest Star session. |
slot_id | String | ID representing this guest’s slot assignment.
|
is_live | Boolean | Flag determining whether or not the guest is visible in the browser source in the host’s streaming software. |
user_id | String | User ID of the guest assigned to this slot. |
user_display_name | String | Display name of the guest assigned to this slot. |
user_login | String | Login of the guest assigned to this slot. |
volume | Integer | Value from 0 to 100 representing the host’s volume setting for this guest. |
assigned_at | String | Timestamp when this guest was assigned a slot in the session. |
audio_settings | MediaSettings | Information about the guest’s audio settings |
is_host_enabled | Boolean | Flag determining whether the host is allowing the guest’s audio to be seen or heard within the session. |
is_guest_enabled | Boolean | Flag determining whether the guest is allowing their audio to be transmitted to the session. |
is_available | Boolean | Flag determining whether the guest has an appropriate audio device available to be transmitted to the session. |
video_settings | MediaSettings | Information about the guest’s video settings |
is_host_enabled | Boolean | Flag determining whether the host is allowing the guest’s video to be seen or heard within the session. |
is_guest_enabled | Boolean | Flag determining whether the guest is allowing their video to be transmitted to the session. |
is_available | Boolean | Flag determining whether the guest has an appropriate video device available to be transmitted to the session. |
Response Codes
Code | Meaning |
---|---|
400 Bad Request |
|
403 Forbidden | Insufficient authorization for ending session |
Example Request
End Guest Star session
curl -x DELETE `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "2KFRQbFtpmfyD3IevNRnCzOPRJI",
"guests": [
{
"id": "0",
"user_id": "9321049",
"user_display_name": "Cool_User",
"user_login": "cool_user",
"is_live": true,
"volume": 100,
"assigned_at": "2023-01-02T04:16:53.325Z",
"audio_settings": {
"is_available": true,
"is_host_enabled": true,
"is_guest_enabled": true,
},
"video_settings": {
"is_available": true,
"is_host_enabled": true,
"is_guest_enabled": true,
}
},
]
}
]
}
Get Guest Star Invites
✎BETA Provides the caller with a list of pending invites to a Guest Star session, including the invitee’s ready status while joining the waiting room.
Authorization
- Query parameter
broadcaster_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:read:guest_star
,channel:manage:guest_star
,moderator:read:guest_star
ormoderator:manage:guest_star
URL
GET https://api.twitch.tv/helix/guest_star/invites
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster running the Guest Star session. |
moderator_id | Yes | String | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user_id in the user access token. |
session_id | Yes | String | The session ID to query for invite status. |
Response Body
Parameter | Type | Description |
---|---|---|
data | Invite[] | A list of invite objects describing the invited user as well as their ready status. |
user_id | String | Twitch User ID corresponding to the invited guest |
invited_at | string | Timestamp when this user was invited to the session. |
status | string | Status representing the invited user’s join state. Can be one of the following:
|
is_video_enabled | Boolean | Flag signaling that the invited user has chosen to disable their local video device. The user has hidden themselves, but they may choose to reveal their video feed upon joining the session. |
is_audio_enabled | Boolean | Flag signaling that the invited user has chosen to disable their local audio device. The user has muted themselves, but they may choose to unmute their audio feed upon joining the session. |
is_video_available | Boolean | Flag signaling that the invited user has a video device available for sharing. |
is_audio_available | Boolean | Flag signaling that the invited user has an audio device available for sharing. |
Response Codes
Code | Meaning |
---|---|
400 Bad Request |
|
Example Request 1
Get session invites
curl -x GET `https://api.twitch.tv/helix/guest_star/invites?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Request 2
Get session for host channel
curl -x GET `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049` \ -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \ -H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response 2
{
"data": [
{
"user_id": "144601104",
"invited_at": "2023-01-02T04:16:53.325Z",
"status": "INVITED",
"is_audio_enabled": false,
"is_video_enabled": true,
"is_audio_available": true,
"is_video_available": true
}
]
}
Send Guest Star Invite
✎BETA Sends an invite to a specified guest on behalf of the broadcaster for a Guest Star session in progress.
Authorization
- Query parameter
moderator_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:manage:guest_star
ormoderator:manage:guest_star
URL
POST https://api.twitch.tv/helix/guest_star/invites
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster running the Guest Star session. |
moderator_id | Yes | String | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user_id in the user access token. |
session_id | Yes | String | The session ID for the invite to be sent on behalf of the broadcaster. |
guest_id | Yes | String | Twitch User ID for the guest to invite to the Guest Star session. |
Response Codes
Code | Meaning |
---|---|
400 Bad Request |
|
403 Forbidden |
|
Example Request
Invite user to Guest Star session
curl -x POST `https://api.twitch.tv/helix/guest_star/invites?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Delete Guest Star Invite
✎BETA Revokes a previously sent invite for a Guest Star session.
Authorization
- Query parameter
moderator_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:manage:guest_star
ormoderator:manage:guest_star
URL
DELETE https://api.twitch.tv/helix/guest_star/invites
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster running the Guest Star session. |
moderator_id | Yes | String | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user_id in the user access token. |
session_id | Yes | String | The ID of the session for the invite to be revoked on behalf of the broadcaster. |
guest_id | Yes | String | Twitch User ID for the guest to revoke the Guest Star session invite from. |
Response Codes
Code | Meaning |
---|---|
400 Bad Request |
|
404 Not Found | No invite exists for specified guest_id |
Example Request
Remove invite to session
curl -x DELETE `https://api.twitch.tv/helix/guest_star/invites?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Assign Guest Star Slot
✎BETA Allows a previously invited user to be assigned a slot within the active Guest Star session, once that guest has indicated they are ready to join.
Authorization
- Query parameter
moderator_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:manage:guest_star
ormoderator:manage:guest_star
URL
POST https://api.twitch.tv/helix/guest_star/slot
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster running the Guest Star session. |
moderator_id | Yes | String | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user_id in the user access token. |
session_id | Yes | String | The ID of the Guest Star session in which to assign the slot. |
guest_id | Yes | String | The Twitch User ID corresponding to the guest to assign a slot in the session. This user must already have an invite to this session, and have indicated that they are ready to join. |
slot_id | Yes | String | The slot assignment to give to the user. Must be a numeric identifier between “1” and “N” where N is the max number of slots for the session. Max number of slots allowed for the session is reported by Get Channel Guest Star Settings. |
Response Codes
Code | Meaning |
---|---|
204 No Content | Successfuly assigned guest to slot |
400 Bad Request |
|
401 Unauthorized | moderator_id is not a guest star moderator |
403 Forbidden |
|
Example Request
Assign invited user to slot
curl -x POST `https://api.twitch.tv/helix/guest_star/slot?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104&slot_id=1` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": {
"code": "USER_NOT_READY"
}
}
Update Guest Star Slot
✎BETA Allows a user to update the assigned slot for a particular user within the active Guest Star session.
Authorization
- Query parameter
moderator_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:manage:guest_star
ormoderator:manage:guest_star
URL
PATCH https://api.twitch.tv/helix/guest_star/slot
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster running the Guest Star session. |
moderator_id | Yes | String | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user_id in the user access token. |
session_id | Yes | String | The ID of the Guest Star session in which to update slot settings. |
source_slot_id | Yes | String | The slot assignment previously assigned to a user. |
destination_slot_id | No | String | The slot to move this user assignment to. If the destination slot is occupied, the user assigned will be swapped into source_slot_id . |
Response Codes
Code | Meaning |
---|---|
204 No Content | Successfuly updated slot(s) |
400 Bad Request |
|
Example Request
Move slot assignment to a new slot ID
curl -x PATCH `https://api.twitch.tv/helix/guest_star/slot?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&source_slot_id=1&destination_slot_id=2` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Delete Guest Star Slot
✎BETA Allows a caller to remove a slot assignment from a user participating in an active Guest Star session. This revokes their access to the session immediately and disables their access to publish or subscribe to media within the session.
Authorization
- Query parameter
moderator_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:manage:guest_star
ormoderator:manage:guest_star
URL
DELETE https://api.twitch.tv/helix/guest_star/slot
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster running the Guest Star session. |
moderator_id | Yes | String | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
session_id | Yes | String | The ID of the Guest Star session in which to remove the slot assignment. |
guest_id | Yes | String | The Twitch User ID corresponding to the guest to remove from the session. |
slot_id | Yes | String | The slot ID representing the slot assignment to remove from the session. |
should_reinvite_guest | No | String | Flag signaling that the guest should be reinvited to the session, sending them back to the invite queue. |
Response Codes
Code | Meaning |
---|---|
204 No Content | Successfuly removed user from slot |
400 Bad Request |
|
403 Forbidden |
|
404 Not Found | guest_id or slot_id not found |
Example Request
Remove user from slot
curl -x DELETE `https://api.twitch.tv/helix/guest_star/slot?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104&slot_id=1` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Update Guest Star Slot Settings
✎BETA Allows a user to update slot settings for a particular guest within a Guest Star session, such as allowing the user to share audio or video within the call as a host. These settings will be broadcasted to all subscribers which control their view of the guest in that slot. One or more of the optional parameters to this API can be specified at any time.
Authorization
- Query parameter
moderator_id
must match theuser_id
in the User-Access token - Requires OAuth Scope:
channel:manage:guest_star
ormoderator:manage:guest_star
URL
PATCH https://api.twitch.tv/helix/guest_star/slot_settings
Request Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
broadcaster_id | Yes | String | The ID of the broadcaster running the Guest Star session. |
moderator_id | Yes | String | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
session_id | Yes | String | The ID of the Guest Star session in which to update a slot’s settings. |
slot_id | Yes | String | The slot assignment that has previously been assigned to a user. |
is_audio_enabled | No | Boolean | Flag indicating whether the slot is allowed to share their audio with the rest of the session. If false, the slot will be muted in any views containing the slot. |
is_video_enabled | No | Boolean | Flag indicating whether the slot is allowed to share their video with the rest of the session. If false, the slot will have no video shared in any views containing the slot. |
is_live | No | Boolean | Flag indicating whether the user assigned to this slot is visible/can be heard from any public subscriptions. Generally, this determines whether or not the slot is enabled in any broadcasting software integrations. |
volume | No | Integer | Value from 0-100 that controls the audio volume for shared views containing the slot. |
Response Codes
Code | Meaning |
---|---|
204 No Content | Successfuly updated slot settings |
400 Bad Request |
|
403 Forbidden |
|
Example Request 1
Update slot settings to enable slot in broadcasting software
curl -x PATCH `https://api.twitch.tv/helix/guest_star/slot_settings?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&slot_id=1&is_audio_enabled=false` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Request 2
Mute a slot’s audio for a guest
curl -x PATCH `https://api.twitch.tv/helix/guest_star/slot_settings?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&slot_id=1&is_live=true` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Request 3
Allow slot audio to be unmuted by a guest. NOTE: This operation does not immediately unmute the guest. The guest will be notified they can unmute themselves when ready.
curl -x PATCH `https://api.twitch.tv/helix/guest_star/slot_settings?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&slot_id=1&is_audio_enabled=true` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Get Hype Train Events
✎Gets information about the broadcaster’s current or most recent Hype Train event.
Instead of polling for events, consider subscribing to Hype Train events (Begin, Progress, End).
Authorization
Requires a user access token that includes the channel:read:hype_train scope.
URL
GET https://api.twitch.tv/helix/hypetrain/events
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that’s running the Hype Train. This ID must match the User ID in the user access token. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 1. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of Hype Train events. The list is empty if the broadcaster hasn’t run a Hype Train within the last 5 days. |
id | String | An ID that identifies this event. |
event_type | String | The type of event. The string is in the form, hypetrain.{event_name}. The request returns only progress event types (i.e., hypetrain.progression). |
event_timestamp | String | The UTC date and time (in RFC3339 format) that the event occurred. |
version | String | The version number of the definition of the event’s data. For example, the value is 1 if the data in event_data uses the first definition of the event’s data. |
event_data | Object | The event’s data. |
broadcaster_id | String | The ID of the broadcaster that’s running the Hype Train. |
cooldown_end_time | string | The UTC date and time (in RFC3339 format) that another Hype Train can start. |
expires_at | String | The UTC date and time (in RFC3339 format) that the Hype Train ends. |
goal | Integer | The value needed to reach the next level. |
id | String | An ID that identifies this Hype Train. |
last_contribution | Object | The most recent contribution towards the Hype Train’s goal. |
total | Integer | The total amount contributed. If type is BITS, total represents the amount of Bits used. If type is SUBS, total is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions, respectively. |
type | String | The contribution method used. Possible values are:
|
user | String | The ID of the user that made the contribution. |
level | Integer | The highest level that the Hype Train reached (the levels are 1 through 5). |
started_at | String | The UTC date and time (in RFC3339 format) that this Hype Train started. |
top_contributions | Object[] | The top contributors for each contribution type. For example, the top contributor using BITS (by aggregate) and the top contributor using SUBS (by count). |
total | Integer | The total amount contributed. If type is BITS, total represents the amount of Bits used. If type is SUBS, total is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions, respectively. |
type | String | The contribution method used. Possible values are:
|
user | String | The ID of the user that made the contribution. |
total | Integer | The current total amount raised. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s Hype Train events. |
401 Unauthorized |
|
Example Request
curl -X GET
'https://api.twitch.tv/helix/hypetrain/events?broadcaster_id=270954519&first=1' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "1b0AsbInCHZW2SQFQkCzqN07Ib2",
"event_type": "hypetrain.progression",
"event_timestamp": "2020-04-24T20:07:24Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "270954519",
"cooldown_end_time": "2020-04-24T20:13:21.003802269Z",
"expires_at": "2020-04-24T20:12:21.003802269Z",
"goal": 1800,
"id": "70f0c7d8-ff60-4c50-b138-f3a352833b50",
"last_contribution": {
"total": 200,
"type": "BITS",
"user": "134247454"
},
"level": 2,
"started_at": "2020-04-24T20:05:47.30473127Z",
"top_contributions": [
{
"total": 600,
"type": "BITS",
"user": "134247450"
}
],
"total": 600
}
}
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjI3MDk1NDUxOToxNTg3NzU4ODQ0OjFiMEFzYkluQ0haVzJTUUZRa0N6cU4wN0liMiJ9fQ"
}
}
Check AutoMod Status
✎Checks whether AutoMod would flag the specified message for review.
AutoMod is a moderation tool that holds inappropriate or harassing chat messages for moderators to review. Moderators approve or deny the messages that AutoMod flags; only approved messages are released to chat. AutoMod detects misspellings and evasive language automatically. For information about AutoMod, see How to Use AutoMod.
Rate Limits: Rates are limited per channel based on the account type rather than per access token.
Account type | Limit per minute | Limit per hour |
---|---|---|
Normal | 5 | 50 |
Affiliate | 10 | 100 |
Partner | 30 | 300 |
The above limits are in addition to the standard Twitch API rate limits. The rate limit headers in the response represent the Twitch rate limits and not the above limits.
Authorization
Requires a user access token that includes the moderation:read scope.
URL
POST https://api.twitch.tv/helix/moderation/enforcements/status
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose AutoMod settings and list of blocked terms are used to check the message. This ID must match the user ID in the access token. |
Request Body
Field | Type | Required? | Description |
---|---|---|---|
data | Object[] | Yes | The list of messages to check. The list must contain at least one message and may contain up to a maximum of 100 messages. |
msg_id | String | Yes | A caller-defined ID used to correlate this message with the same message in the response. |
msg_text | String | Yes | The message to check. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of messages and whether Twitch would approve them for chat. |
msg_id | String | The caller-defined ID passed in the request. |
is_permitted | Boolean | A Boolean value that indicates whether Twitch would approve the message for chat or hold it for moderator review or block it from chat. Is true if Twitch would approve the message; otherwise, false if Twitch would hold the message for moderator review or block it from chat. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully checked the messages. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
429 Too Many Requests |
|
Example Request
curl -X POST 'https://api.twitch.tv/helix/moderation/enforcements/status?broadcaster_id=12345' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"data": [
{
"msg_id": "123",
"msg_text": "Hello World!"
},
{
"msg_id": "393",
"msg_text": "Boooooo!"
}
]
}'
Example Response
{
"data": [
{
"msg_id": "123",
"is_permitted": true
},
{
"msg_id": "393",
"is_permitted": false
}
]
}
Manage Held AutoMod Messages
✎Allow or deny the message that AutoMod flagged for review. For information about AutoMod, see How to Use AutoMod.
To get messages that AutoMod is holding for review, subscribe to the automod-queue.<moderator_id>.<channel_id> topic using PubSub. PubSub sends a notification to your app when AutoMod holds a message for review.
Authorization
Requires a user access token that includes the moderator:manage:automod scope.
URL
POST https://api.twitch.tv/helix/moderation/automod/message
Request Body
Field | Type | Required? | Description |
---|---|---|---|
user_id | String | Yes | The moderator who is approving or denying the held message. This ID must match the user ID in the access token. |
msg_id | String | Yes | The ID of the message to allow or deny. |
action | String | Yes | The action to take for the message. Possible values are:
|
Response Codes
Code | Description |
---|---|
204 No Content | Successfully approved or denied the message. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
Example Request
curl -X POST 'https://api.twitch.tv/helix/moderation/automod/message' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "9327994",
"msg_id": "836013710",
"action": "ALLOW"
}'
Get AutoMod Settings
✎Gets the broadcaster’s AutoMod settings. The settings are used to automatically block inappropriate or harassing messages from appearing in the broadcaster’s chat room.
Authorization
Requires a user access token that includes the moderator:read:automod_settings scope.
URL
GET https://api.twitch.tv/helix/moderation/automod/settings
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose AutoMod settings you want to get. |
moderator_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of AutoMod settings. The list contains a single object that contains all the AutoMod settings. |
broadcaster_id | String | The broadcaster’s ID. |
moderator_id | String | The moderator’s ID. |
overall_level | Integer | The default AutoMod level for the broadcaster. This field is null if the broadcaster has set one or more of the individual settings. |
disability | Integer | The Automod level for discrimination against disability. |
aggression | Integer | The Automod level for hostility involving aggression. |
sexuality_sex_or_gender | Integer | The AutoMod level for discrimination based on sexuality, sex, or gender. |
misogyny | Integer | The Automod level for discrimination against women. |
bullying | Integer | The Automod level for hostility involving name calling or insults. |
swearing | Integer | The Automod level for profanity. |
race_ethnicity_or_religion | Integer | The Automod level for racial discrimination. |
sex_based_terms | Integer | The Automod level for sexual content. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s AutoMod settings. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request
Gets the broadcaster’s AutoMod settings.
curl -X GET 'https://api.twitch.tv/helix/moderation/automod/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
Example Response
Shows what the response looks like if the broadcaster hasn’t enabled AutoMod (none of the settings are set).
{
"data": [
{
"broadcaster_id": "1234",
"moderator_id": "5678",
"overall_level": null,
"disability": 0,
"aggression": 0,
"sexuality_sex_or_gender": 0,
"misogyny": 0,
"bullying": 0,
"swearing": 0,
"race_ethnicity_or_religion": 0,
"sex_based_terms": 0
}
]
}
Update AutoMod Settings
✎Updates the broadcaster’s AutoMod settings. The settings are used to automatically block inappropriate or harassing messages from appearing in the broadcaster’s chat room.
Authorization
Requires a user access token that includes the moderator:manage:automod_settings scope.
URL
PUT https://api.twitch.tv/helix/moderation/automod/settings
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose AutoMod settings you want to update. |
moderator_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
Request Body
Because PUT is an overwrite operation, you must include all the fields that you want set after the operation completes. Typically, you’ll send a GET request, update the fields you want to change, and pass that object in the PUT request.
You may set either overall_level
or the individual settings like aggression
, but not both.
Setting overall_level
applies default values to the individual settings. However, setting overall_level
to 4 does not necessarily mean that it applies 4 to all the individual settings. Instead, it applies a set of recommended defaults to the rest of the settings. For example, if you set overall_level
to 2, Twitch provides some filtering on discrimination and sexual content, but more filtering on hostility (see the first example response).
If overall_level
is currently set and you update swearing
to 3, overall_level
will be set to null and all settings other than swearing
will be set to 0. The same is true if individual settings are set and you update overall_level
to 3 — all the individual settings are updated to reflect the default level.
Note that if you set all the individual settings to values that match what overall_level
would have set them to, Twitch changes AutoMod to use the default AutoMod level instead of using the individual settings.
Valid values for all levels are from 0 (no filtering) through 4 (most aggressive filtering). These levels affect how aggressively AutoMod holds back messages for moderators to review before they appear in chat or are denied (not shown).
Field | Type | Description |
---|---|---|
aggression | Integer | The Automod level for hostility involving aggression. |
bullying | Integer | The Automod level for hostility involving name calling or insults. |
disability | Integer | The Automod level for discrimination against disability. |
misogyny | Integer | The Automod level for discrimination against women. |
overall_level | Integer | The default AutoMod level for the broadcaster. |
race_ethnicity_or_religion | Integer | The Automod level for racial discrimination. |
sex_based_terms | Integer | The Automod level for sexual content. |
sexuality_sex_or_gender | Integer | The AutoMod level for discrimination based on sexuality, sex, or gender. |
swearing | Integer | The Automod level for profanity. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of AutoMod settings. The list contains a single object that contains all the AutoMod settings. |
broadcaster_id | String | The broadcaster’s ID. |
moderator_id | String | The moderator’s ID. |
overall_level | Integer | The default AutoMod level for the broadcaster. This field is null if the broadcaster has set one or more of the individual settings. |
disability | Integer | The Automod level for discrimination against disability. |
aggression | Integer | The Automod level for hostility involving aggression. |
sexuality_sex_or_gender | Integer | The AutoMod level for discrimination based on sexuality, sex, or gender. |
misogyny | Integer | The Automod level for discrimination against women. |
bullying | Integer | The Automod level for hostility involving name calling or insults. |
swearing | Integer | The Automod level for profanity. |
race_ethnicity_or_religion | Integer | The Automod level for racial discrimination. |
sex_based_terms | Integer | The Automod level for sexual content. |
Response Codes
Code | Description |
---|---|
200 Ok | Successfully updated the broadcaster’s AutoMod settings. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request 1
This example updates the overall_level
setting to 3.
curl -X PUT 'https://api.twitch.tv/helix/moderation/automod/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
-H 'Content-Type: application/json' \
-d '{"overall_level":3}'
Example Response 1
Notice in the response that not all settings are set to level 3.
{
"data": [
{
"broadcaster_id": "1234",
"moderator_id": "5678",
"overall_level": 3,
"disability": 3,
"aggression": 3,
"sexuality_sex_or_gender": 3,
"misogyny": 3,
"bullying": 2,
"swearing": 0,
"race_ethnicity_or_religion": 3,
"sex_based_terms": 3
}
]
}
If overall_level
is set to 3 and you try to change swearing
to 2, all other settings are set to 0. If the goal was to change the swearing
setting and leave all the others unchanged, the request must have included all the other settings as well.
{
"data": [
{
"broadcaster_id": "1234",
"moderator_id": "5678",
"overall_level": null,
"disability": 0,
"aggression": 0,
"sexuality_sex_or_gender": 0,
"misogyny": 0,
"bullying": 0,
"swearing": 2,
"race_ethnicity_or_religion": 0,
"sex_based_terms": 0
}
]
}
Get Banned Users
✎Gets all users that the broadcaster banned or put in a timeout.
Authorization
Requires a user access token that includes the moderation:read or moderator:manage:banned_users scope.
URL
GET https://api.twitch.tv/helix/moderation/banned
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose list of banned users you want to get. This ID must match the user ID in the access token. |
user_id | String | No | A list of user IDs used to filter the results. To specify more than one ID, include this parameter for each user you want to get. For example, user_id=1234&user_id=5678 . You may specify a maximum of 100 IDs.The returned list includes only those users that were banned or put in a timeout. The list is returned in the same order that you specified the IDs. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
before | String | No | The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of users that were banned or put in a timeout. |
user_id | String | The ID of the banned user. |
user_login | String | The banned user’s login name. |
user_name | String | The banned user’s display name. |
expires_at | String | The UTC date and time (in RFC3339 format) of when the timeout expires, or an empty string if the user is permanently banned. |
created_at | String | The UTC date and time (in RFC3339 format) of when the user was banned. |
reason | String | The reason the user was banned or put in a timeout if the moderator provided one. |
moderator_id | String | The ID of the moderator that banned the user or put them in a timeout. |
moderator_login | String | The moderator’s login name. |
moderator_name | String | The moderator’s display name. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of banned users. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/moderation/banned?broadcaster_id=198704263' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"user_id": "423374343",
"user_login": "glowillig",
"user_name": "glowillig",
"expires_at": "2022-03-15T02:00:28Z",
"created_at": "2022-03-15T01:30:28Z",
"reason": "Does not like pineapple on pizza.",
"moderator_id": "141981764",
"moderator_login": "twitchdev",
"moderator_name": "TwitchDev"
},
{
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok",
"expires_at": "2022-08-07T02:07:55Z",
"created_at": "2022-08-07T02:02:55Z",
"reason": "Inappropriate words.",
"moderator_id": "141981764",
"moderator_login": "twitchdev",
"moderator_name": "TwitchDev"
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
}
}
Ban User
✎Bans a user from participating in the specified broadcaster’s chat room or puts them in a timeout.
For information about banning or putting users in a timeout, see Ban a User and Timeout a User.
If the user is currently in a timeout, you can call this endpoint to change the duration of the timeout or ban them altogether. If the user is currently banned, you cannot call this method to put them in a timeout instead.
To remove a ban or end a timeout, see Unban user.
Authorization
Requires a user access token that includes the moderator:manage:banned_users scope.
URL
POST https://api.twitch.tv/helix/moderation/bans
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose chat room the user is being banned from. |
moderator_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
Request Body
Field | Type | Required? | Description |
---|---|---|---|
data | Object | Yes | Identifies the user and type of ban. |
user_id | String | Yes | The ID of the user to ban or put in a timeout. |
duration | Integer | No | To ban a user indefinitely, don’t include this field. To put a user in a timeout, include this field and specify the timeout period, in seconds. The minimum timeout is 1 second and the maximum is 1,209,600 seconds (2 weeks). To end a user’s timeout early, set this field to 1, or use the Unban user endpoint. |
reason | String | No | The reason the you’re banning the user or putting them in a timeout. The text is user defined and is limited to a maximum of 500 characters. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the user you successfully banned or put in a timeout. |
broadcaster_id | String | The broadcaster whose chat room the user was banned from chatting in. |
moderator_id | String | The moderator that banned or put the user in the timeout. |
user_id | String | The user that was banned or put in a timeout. |
created_at | string | The UTC date and time (in RFC3339 format) that the ban or timeout was placed. |
end_time | String | The UTC date and time (in RFC3339 format) that the timeout will end. Is null if the user was banned instead of being put in a timeout. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully banned the user or placed them in a timeout. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
409 Conflict |
|
429 Too Many Requests |
|
Example Request 1
Bans a user (it doesn’t include the duration
field).
curl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","reason":"no reason"}}'
Example Response 1
{
"data": [
{
"broadcaster_id": "1234",
"moderator_id": "5678",
"user_id": "9876",
"created_at": "2021-09-28T18:22:31Z",
"end_time": null
}
]
}
Example Request 2
Puts a user in a 5-minute timeout.
curl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","duration":300,"reason":"no reason"}}'
Example Response 2
{
"data": [
{
"broadcaster_id": "1234",
"moderator_id": "5678",
"user_id": "9876",
"created_at": "2021-09-28T19:27:31Z",
"end_time": "2021-09-28T19:22:31Z"
}
]
}
Example Request 3
Shows what happens if you try to place a banned user in a timeout. You can ban a user that’s already in a timeout but you can’t move a banned user into a timeout. To do this, you’d have to remove the ban and then place them in a timeout.
You’ll get the same response if you try to ban a user who is already banned.
curl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","duration":300,"reason":"no reason"}}'
Example Response 3
{
"error": "Bad Request",
"status": 400,
"message": "user is already banned"
}
Unban User
✎Removes the ban or timeout that was placed on the specified user.
To ban a user, see Ban user.
Authorization
Requires a user access token that includes the moderator:manage:banned_users scope.
URL
DELETE https://api.twitch.tv/helix/moderation/bans
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose chat room the user is banned from chatting in. |
moderator_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
user_id | String | Yes | The ID of the user to remove the ban or timeout from. |
Response Codes
Code | Description |
---|---|
204 No Content | Successfully removed the ban or timeout. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
409 Conflict |
|
429 Too Many Requests |
|
Example Request 1
Removes a ban or timeout from a user.
curl -X DELETE 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678&user_id=5432' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
Example Request 2
Tries to remove a ban or timeout from a user that is not currently banned or in a timeout.
curl -X DELETE 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678&user_id=5432' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
Example Response 2
{
"error": "Bad Request",
"status": 400,
"message": "user is not banned"
}
Get Unban Requests
✎NEW Gets a list of unban requests for a broadcaster’s channel.
Authorization
- Requires a user access token that includes the moderator:read:unban_requests or moderator:manage:unban_requests scope.
- Query parameter
moderator_id
must match theuser_id
in the user access token.
URL
GET https://api.twitch.tv/helix/moderation/unban_requests
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose channel is receiving unban requests. |
moderator_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token. |
status | String | Yes | Filter by a status.
|
user_id | String | No | The ID used to filter what unban requests are returned. |
after | String | No | Cursor used to get next page of results. Pagination object in response contains cursor value. |
first | Integer | No | The maximum number of items to return per page in response |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains information about the channel's unban requests. |
id | String | Unban request ID. |
broadcaster_id | String | User ID of broadcaster whose channel is receiving the unban request. |
broadcaster_name | String | The broadcaster's display name. |
broadcaster_login | String | The broadcaster's login name. |
moderator_id | String | User ID of moderator who approved/denied the request. |
moderator_login | String | The moderator's login name. |
moderator_name | String | The moderator's display name. |
user_id | String | User ID of the requestor who is asking for an unban. |
user_login | String | The user's login name. |
user_name | String | The user's display name. |
text | String | Text of the request from the requesting user. |
status | String | Status of the request. One of:
|
created_at | String | Timestamp of when the unban request was created. |
resolved_at | String | Timestamp of when moderator/broadcaster approved or denied the request. |
resolution_text | String | Text input by the resolver (moderator) of the unban. request |
pagination | Object | Contains information used to page through a list of results. The object is empty if there are no more pages left to page through. |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
HTTP Code | Description |
---|---|
200 OK | Successfully retrieved the list of unban requests. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Gets information about the specified broadcaster.
curl -X GET 'https://api.twitch.tv/helix/moderation/unban_requests?broadcaster_id=274637212&moderator_id=274637212&status=pending' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"moderator_id": "141981764",
"moderator_login": "twitchdev",
"moderator_name": "TwitchDev",
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok",
"text": "Please unban me from the channel?",
"status": "pending",
"created_at": "2022-08-07T02:07:55Z",
"resolved_at": null,
"resolution_text": null
}
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
}
}
Resolve Unban Requests
✎NEW Resolves an unban request by approving or denying it.
Authorization
-
Requires a user access token that includes the moderator:manage:unban_requests scope.
-
Query parameter
moderator_id
must match theuser_id
in theuser access token.
URL
PATCH https://api.twitch.tv/helix/moderation/unban_requests
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose channel is approving or denying the unban request. |
moderator_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token. |
unban_request_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token. |
status | String | Yes | Resolution status.
|
resolution_text | String | No | Message supplied by the unban request resolver. The message is limited to a maximum of 500 characters. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | |
id | String | Unban request ID. |
broadcaster_id | String | User ID of broadcaster whose channel is receiving the unban request. |
broadcaster_login | String | The broadcaster’s login name. |
broadcaster_name | String | The broadcaster’s display name. |
moderator_id | String | User ID of moderator who approved/denied the request. |
moderator_login | String | The moderator’s login name. |
moderator_name | String | The moderator’s display name. |
user_id | String | User ID of the requestor who is asking for an unban. |
user_login | String | The user’s login name. |
user_name | String | The user’s display name. |
text | String | Text of the request from the requesting user. |
status | String | Status of the request. One of:
|
created_at | String | Timestamp of when the unban request was created. |
resolved_at | String | Timestamp of when moderator/broadcaster approved or denied the request. |
resolution_text | String | Text input by the resolver (moderator) of the unban request. |
Response Codes
HTTP Code | Description |
---|---|
200 OK | Successfully resolved the unban request. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found | The unban request ID was not found. |
Example Request
Approving an unban request.
curl -X PATCH 'https://api.twitch.tv/helix/moderation/unban_requests?broadcaster_id=274637212&moderator_id=274637212&unban_request_id=92af127c-7326-4483-a52b-b0daa0be61c01&status=approved' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'`
Example Response
{
"data": [
{
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"moderator_id": "141981764",
"moderator_login": "twitchdev",
"moderator_name": "TwitchDev",
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok",
"text": "Please unban me from the channel?",
"status": "approved",
"created_at": "2022-08-07T02:07:55Z",
"resolved_at": "2022-08-09T02:07:55Z",
"resolution_text": null
}
]
}
Get Blocked Terms
✎Gets the broadcaster’s list of non-private, blocked words or phrases. These are the terms that the broadcaster or moderator added manually or that were denied by AutoMod.
Authorization
Requires a user access token that includes the moderator:read:blocked_terms or moderator:manage:blocked_terms scope.
URL
GET https://api.twitch.tv/helix/moderation/blocked_terms
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose blocked terms you’re getting. |
moderator_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of blocked terms. The list is in descending order of when they were created (see the created_at timestamp). |
broadcaster_id | String | The broadcaster that owns the list of blocked terms. |
moderator_id | String | The moderator that blocked the word or phrase from being used in the broadcaster’s chat room. |
id | String | An ID that identifies this blocked term. |
text | String | The blocked word or phrase. |
created_at | String | The UTC date and time (in RFC3339 format) that the term was blocked. |
updated_at | String | The UTC date and time (in RFC3339 format) that the term was updated. When the term is added, this timestamp is the same as created_at . The timestamp changes as AutoMod continues to deny the term. |
expires_at | String | The UTC date and time (in RFC3339 format) that the blocked term is set to expire. After the block expires, users may use the term in the broadcaster’s chat room. This field is null if the term was added manually or was permanently blocked by AutoMod. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Decription |
---|---|
200 OK | Successfully retrieved the list of blocked terms. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request
Gets the last 10 blocked terms (see the first query parameter) that were added.
curl -X GET 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678&first=10' \
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
Example Response
{
"data": [
{
"broadcaster_id": "1234",
"moderator_id": "5678",
"id": "520e4d4e-0cda-49c7-821e-e5ef4f88c2f2",
"text": "A phrase I’m not fond of",
"created_at": "2021-09-29T19:45:37Z",
"updated_at": "2021-09-29T19:45:37Z",
"expires_at": null
},
. . .
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6I..."
}
}
Add Blocked Term
✎Adds a word or phrase to the broadcaster’s list of blocked terms. These are the terms that the broadcaster doesn’t want used in their chat room.
Authorization
Requires a user access token that includes the moderator:manage:blocked_terms scope.
URL
POST https://api.twitch.tv/helix/moderation/blocked_terms
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that owns the list of blocked terms. |
moderator_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
Request Body
Field | Type | Required? | Description |
---|---|---|---|
text | String | Yes | The word or phrase to block from being used in the broadcaster’s chat room. The term must contain a minimum of 2 characters and may contain up to a maximum of 500 characters. Terms may include a wildcard character (*). The wildcard character must appear at the beginning or end of a word or set of characters. For example, *foo or foo*. If the blocked term already exists, the response contains the existing blocked term. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the single blocked term that the broadcaster added. |
broadcaster_id | String | The broadcaster that owns the list of blocked terms. |
moderator_id | String | The moderator that blocked the word or phrase from being used in the broadcaster’s chat room. |
id | String | An ID that identifies this blocked term. |
text | String | The blocked word or phrase. |
created_at | String | The UTC date and time (in RFC3339 format) that the term was blocked. |
updated_at | String | The UTC date and time (in RFC3339 format) that the term was updated. When the term is added, this timestamp is the same as created_at . The timestamp changes as AutoMod continues to deny the term. |
expires_at | String | The UTC date and time (in RFC3339 format) that the blocked term is set to expire. After the block expires, users may use the term in the broadcaster’s chat room. This field is null if the term was added manually or was permanently blocked by AutoMod. |
Response Codes
Code | Decription |
---|---|
200 OK | Successfully retrieved the list of blocked terms. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request 1
Adds a blocked term. Adding the same term again will return the previously added term.
curl -X POST 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 789nj68b49pwqs9nh2y2jrlgzju3f' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"text":"A phrase I’m not fond of"}'
Example Response 1
{
"data": [
{
"broadcaster_id": "713936733",
"moderator_id": "713936733",
"id": "3bb6e5d3-afb1-416c-ad4e-21af970ccfe7",
"text": "A phrase I’m not fond of",
"created_at": "2021-09-29T15:36:45Z",
"updated_at": "2021-09-29T15:36:45Z",
"expires_at": null
}
]
}
Example Request 2
Adds a term that uses the wildcard character (*).
curl -X POST 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 789nj68b49pwqs9nh2y2jrlgzju3f' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"text":"crac*"}'
Example Response 2
{
"data": [
{
"broadcaster_id": "1234",
"moderator_id": "5678",
"id": "520e4d4e-0cda-49c7-821e-e5ef4f88c2f2",
"text": "crac*",
"created_at": "2021-09-29T19:45:37Z",
"updated_at": "2021-09-29T19:45:37Z",
"expires_at": null
}
]
}
Remove Blocked Term
✎Removes the word or phrase from the broadcaster’s list of blocked terms.
Authorization
Requires a user access token that includes the moderator:manage:blocked_terms scope.
URL
DELETE https://api.twitch.tv/helix/moderation/blocked_terms
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that owns the list of blocked terms. |
moderator_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
id | String | Yes | The ID of the blocked term to remove from the broadcaster’s list of blocked terms. |
Response Codes
Code | Decription |
---|---|
204 No Content | Successfully removed the blocked term. Also returned if the ID is not found. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request
Deletes the specified blocked term.
curl -X DELETE 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678&id=c9fc79b8-0f63-4ef7-9d38-efd811e74ac2' \
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
Delete Chat Messages
✎Removes a single chat message or all chat messages from the broadcaster’s chat room.
Authorization
Requires a user access token that includes the moderator:manage:chat_messages scope.
URL
DELETE https://api.twitch.tv/helix/moderation/chat
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that owns the chat room to remove messages from. |
moderator_id | String | Yes | The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token. |
message_id | String | No | The ID of the message to remove. The id tag in the PRIVMSG tag contains the message’s ID. Restrictions:
|
Response Codes
Code | Description |
---|---|
204 No Content | Successfully removed the specified messages. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
Example Request
Removes all messages from the broadcaster’s chat room (doesn’t include the message_id query parameter).
curl -X DELETE 'https://api.twitch.tv/helix/moderation/chat?broadcaster_id=11111&moderator_id=44444' \
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
Removes the specified message from the broadcaster’s chat room.
curl -X DELETE 'https://api.twitch.tv/helix/moderation/chat?broadcaster_id=11111&moderator_id=44444&message_id=abc-123-def' \
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
Get Moderated Channels
✎Gets a list of channels that the specified user has moderator privileges in.
Authorization
- Query parameter
user_id
must match the user ID in the User-Access token - Requires OAuth Scope:
user:read:moderated_channels
URL
GET https://api.twitch.tv/helix/moderation/channels
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
user_id | String | Yes | A user’s ID. Returns the list of channels that this user has moderator privileges in. This ID must match the user ID in the user OAuth token |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. |
first | Integer | No | The maximum number of items to return per page in the response. Minimum page size is 1 item per page and the maximum is 100. The default is 20. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of channels that the user has moderator privileges in. |
broadcaster_id | String | An ID that uniquely identifies the channel this user can moderate. |
broadcaster_login | String | The channel’s login name. |
broadcaster_name | String | The channels’ display name. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Example Request
curl -X GET 'https://api.twitch.tv/helix/moderation/channels?user_id=931931' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"broadcaster_id" : "12345",
"broadcaster_login" : "grateful_broadcaster",
"broadcaster_name" : "Grateful_Broadcaster"
},
{
"broadcaster_id" : "98765",
"broadcaster_login" : "bashfulgamer",
"broadcaster_name" : "BashfulGamer"
},
...
],
"pagination" : {
"cursor" : "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
}
}
Get Moderators
✎Gets all users allowed to moderate the broadcaster’s chat room.
Authorization
Requires a user access token that includes the moderation:read scope. If your app also adds and removes moderators, you can use the channel:manage:moderators scope instead.
URL
GET https://api.twitch.tv/helix/moderation/moderators
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose list of moderators you want to get. This ID must match the user ID in the access token. |
user_id | String | No | A list of user IDs used to filter the results. To specify more than one ID, include this parameter for each moderator you want to get. For example, user_id=1234&user_id=5678 . You may specify a maximum of 100 IDs.The returned list includes only the users from the list who are moderators in the broadcaster’s channel. The list is returned in the same order as you specified the IDs. |
first | String | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of moderators. |
user_id | String | The ID of the user that has permission to moderate the broadcaster’s channel. |
user_login | String | The user’s login name. |
user_name | String | The user’s display name. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of moderators. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=198704263' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok"
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
}
}
Add Channel Moderator
✎Adds a moderator to the broadcaster’s chat room.
Rate Limits: The broadcaster may add a maximum of 10 moderators within a 10-second window.
Authorization
Requires a user access token that includes the channel:manage:moderators scope.
URL
POST https://api.twitch.tv/helix/moderation/moderators
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that owns the chat room. This ID must match the user ID in the access token. |
user_id | String | Yes | The ID of the user to add as a moderator in the broadcaster’s chat room. |
Response Codes
Code | Description |
---|---|
204 No Content | Successfully added the moderator. |
400 Bad Request |
|
401 Unauthorized |
|
422 Unprocessable Entity |
|
429 Too Many Requests |
|
Example Request
curl -X POST 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=11111&user_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Remove Channel Moderator
✎Removes a moderator from the broadcaster’s chat room.
Rate Limits: The broadcaster may remove a maximum of 10 moderators within a 10-second window.
Authorization
Requires a user access token that includes the channel:manage:moderators scope.
URL
DELETE https://api.twitch.tv/helix/moderation/moderators
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that owns the chat room. This ID must match the user ID in the access token. |
user_id | String | Yes | The ID of the user to remove as a moderator from the broadcaster’s chat room. |
Response Codes
Code | Description |
---|---|
204 No Content | Successfully removed the moderator. |
400 Bad Request |
|
401 Unauthorized |
|
429 Too Many Requests |
|
Example Request
curl -X DELETE 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=11111&user_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Get VIPs
✎Gets a list of the broadcaster’s VIPs.
Authorization
Requires a user access token that includes the channel:read:vips scope. If your app also adds and removes VIP status, you can use the channel:manage:vips scope instead.
URL
GET https://api.twitch.tv/helix/channels/vips
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
user_id | String | No | Filters the list for specific VIPs. To specify more than one user, include the user_id parameter for each user to get. For example, &user_id=1234&user_id=5678 . The maximum number of IDs that you may specify is 100. Ignores the ID of those users in the list that aren’t VIPs. |
broadcaster_id | String | Yes | The ID of the broadcaster whose list of VIPs you want to get. This ID must match the user ID in the access token. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The list of VIPs. The list is empty if the broadcaster doesn’t have VIP users. |
user_id | String | An ID that uniquely identifies the VIP user. |
user_name | String | The user’s display name. |
user_login | String | The user’s login name. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s list of VIPs. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Gets a list of the broadcaster’s VIPs
curl -X GET 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Gets a filtered list of the broadcaster’s VIPs. The list in the response contains only those users that are VIPs.
curl -X GET 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456&user_id=678' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Example Response
{
"data": [
{
"user_id": "11111",
"user_name": "UserDisplayName",
"user_login": "userloginname"
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
}
}
Add Channel VIP
✎Adds the specified user as a VIP in the broadcaster’s channel.
Rate Limits: The broadcaster may add a maximum of 10 VIPs within a 10-second window.
Authorization
Requires a user access token that includes the channel:manage:vips scope.
URL
POST https://api.twitch.tv/helix/channels/vips
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
user_id | String | Yes | The ID of the user to give VIP status to. |
broadcaster_id | String | Yes | The ID of the broadcaster that’s adding the user as a VIP. This ID must match the user ID in the access token. |
Response Body
None
Response Codes
Code | Description |
---|---|
204 No Content | Successfully added the VIP. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
409 Conflict | The broadcaster doesn’t have available VIP slots. Read More |
422 Unprocessable Entity |
|
425 Too Early | The broadcaster must complete the Build a Community requirement before they may assign VIPs. |
429 Too Many Requests | The broadcaster exceeded the number of VIP that they may add within a 10-second window. See Rate Limits for this endpoint above. |
Example Request
Adds a VIP to the broadcaster’s chat room.
curl -X POST 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Remove Channel VIP
✎Removes the specified user as a VIP in the broadcaster’s channel.
If the broadcaster is removing the user’s VIP status, the ID in the broadcaster_id query parameter must match the user ID in the access token; otherwise, if the user is removing their VIP status themselves, the ID in the user_id query parameter must match the user ID in the access token.
Rate Limits: The broadcaster may remove a maximum of 10 VIPs within a 10-second window.
Authorization
Requires a user access token that includes the channel:manage:vips scope.
URL
DELETE https://api.twitch.tv/helix/channels/vips
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
user_id | String | Yes | The ID of the user to remove VIP status from. |
broadcaster_id | String | Yes | The ID of the broadcaster who owns the channel where the user has VIP status. |
Response Body
None
Response Codes
Code | Description |
---|---|
204 No Content | Successfully removed the VIP status from the user. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
422 Unprocessable Entity |
|
429 Too Many Requests | The broadcaster exceeded the number of VIPs that they may remove within a 10-second window. See Rate Limits for this endpoint above. |
Example Request
Removes the VIP user from the broadcaster’s channel.
curl -X DELETE 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Update Shield Mode Status
✎Activates or deactivates the broadcaster’s Shield Mode.
Twitch’s Shield Mode feature is like a panic button that broadcasters can push to protect themselves from chat abuse coming from one or more accounts. When activated, Shield Mode applies the overrides that the broadcaster configured in the Twitch UX. If the broadcaster hasn’t configured Shield Mode, it applies default overrides.
Authorization
Requires a user access token that includes the moderator:manage:shield_mode scope.
URL
PUT https://api.twitch.tv/helix/moderation/shield_mode
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose Shield Mode you want to activate or deactivate. |
moderator_id | String | Yes | The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token. |
Request Body
Field | Type | Required? | Description |
---|---|---|---|
is_active | Boolean | Yes | A Boolean value that determines whether to activate Shield Mode. Set to true to activate Shield Mode; otherwise, false to deactivate Shield Mode. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains a single object with the broadcaster’s updated Shield Mode status. |
is_active | Boolean | A Boolean value that determines whether Shield Mode is active. Is true if Shield Mode is active; otherwise, false. |
moderator_id | String | An ID that identifies the moderator that last activated Shield Mode. |
moderator_login | String | The moderator’s login name. |
moderator_name | String | The moderator’s display name. |
last_activated_at | String | The UTC timestamp (in RFC3339 format) of when Shield Mode was last activated. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully updated the broadcaster’s Shield Mode status. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request
curl -X PUT 'https://api.twitch.tv/helix/moderation/shield_mode?broadcaster_id=12345&moderator_id=98765' \
-H 'Authorization: Bearer kpvy3cjboypmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0yan9c87zr6t' \
-H 'Content-Type: application/json' \
-d '{"is_active":false}'
Example Response
{
"data": [
{
"is_active": false,
"moderator_id": "98765",
"moderator_name": "SimplySimple",
"moderator_login": "simplysimple",
"last_activated_at": "2022-07-26T17:16:03.123Z"
}
]
}
Get Shield Mode Status
✎Gets the broadcaster’s Shield Mode activation status.
To receive notification when the broadcaster activates and deactivates Shield Mode, subscribe to the channel.shield_mode.begin and channel.shield_mode.end subscription types.
Authorization
Requires a user access token that includes the moderator:read:shield_mode or moderator:manage:shield_mode scope.
URL
GET https://api.twitch.tv/helix/moderation/shield_mode
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose Shield Mode activation status you want to get. |
moderator_id | String | Yes | The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains a single object with the broadcaster’s Shield Mode status. |
is_active | Boolean | A Boolean value that determines whether Shield Mode is active. Is true if the broadcaster activated Shield Mode; otherwise, false. |
moderator_id | String | An ID that identifies the moderator that last activated Shield Mode. Is an empty string if Shield Mode hasn’t been previously activated. |
moderator_login | String | The moderator’s login name. Is an empty string if Shield Mode hasn’t been previously activated. |
moderator_name | String | The moderator’s display name. Is an empty string if Shield Mode hasn’t been previously activated. |
last_activated_at | String | The UTC timestamp (in RFC3339 format) of when Shield Mode was last activated. Is an empty string if Shield Mode hasn’t been previously activated. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s Shield Mode activation status. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
Example Request
curl -X GET 'https://api.twitch.tv/helix/moderation/shield_mode?broadcaster_id=12345&moderator_id=98765' \
-H 'Authorization: Bearer kpvy3cjboypmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0yan9c87zr6t'
Example Response
{
"data": [
{
"is_active": true,
"moderator_id": "98765",
"moderator_name": "SimplySimple",
"moderator_login": "simplysimple",
"last_activated_at": "2022-07-26T17:16:03.123Z"
}
]
}
Warn Chat User
✎NEW Warns a user in the specified broadcaster’s chat room, preventing them from chat interaction until the warning is acknowledged. New warnings can be issued to a user when they already have a warning in the channel (new warning will replace old warning).
Authorization
Requires a user access token that includes the moderator:manage:warnings scope. Query parameter moderator_id
must match the user_id
in the user access token.
URL
POST https://api.twitch.tv/helix/moderation/warnings
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the channel in which the warning will take effect. |
moderator_id | String | Yes | The ID of the twitch user who requested the warning. |
Request Body
Parameter | Type | Required? | Description |
---|---|---|---|
data | Object | Yes | A list that contains information about the warning. |
user_id | String | Yes | The ID of the twitch user to be warned. |
reason | String | Yes | A custom reason for the warning. Max 500 chars. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains information about the warning. |
broadcaster_id | String | The ID of the channel in which the warning will take effect. |
user_id | String | The ID of the warned user. |
moderator_id | String | The ID of the user who applied the warning. |
reason | String | The reason provided for warning. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully warn a user. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden | The user in moderator_id is not one of the broadcaster’s moderators. |
409 Conflict | You may not update the user’s warning state while someone else is updating the state. For example, someone else is currently warning the user or the user is acknowledging an existing warning. Please retry your request. |
429 Too Many Requests | The app has exceeded the number of requests it may make per minute for this broadcaster. |
500 Internal Server Error | Internal Server Error. |
Example Request
curl -X POST 'https://api.twitch.tv/helix/moderation/warnings?broadcaster_id=404040&moderator_id=404041' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","reason":"stop doing that!"}}'
Example Response
{
"data": [
{
"broadcaster_id": "404040",
"user_id": "9876",
"moderator_id": "404041",
"reason": "stop doing that!"
}
]
}
Get Polls
✎Gets a list of polls that the broadcaster created.
Polls are available for 90 days after they’re created.
Authorization
Requires a user access token that includes the channel:read:polls or channel:manage:polls scope.
URL
GET https://api.twitch.tv/helix/polls
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that created the polls. This ID must match the user ID in the user access token. |
id | String | No | A list of IDs that identify the polls to return. To specify more than one ID, include this parameter for each poll you want to get. For example, id=1234&id=5678 . You may specify a maximum of 20 IDs.Specify this parameter only if you want to filter the list that the request returns. The endpoint ignores duplicate IDs and those not owned by this broadcaster. |
first | String | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 20 items per page. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list of polls. The polls are returned in descending order of start time unless you specify IDs in the request, in which case they're returned in the same order as you passed them in the request. The list is empty if the broadcaster hasn't created polls. |
id | String | An ID that identifies the poll. |
broadcaster_id | String | An ID that identifies the broadcaster that created the poll. |
broadcaster_name | String | The broadcaster's display name. |
broadcaster_login | String | The broadcaster's login name. |
title | String | The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters. |
choices | Object[] | A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices. |
id | String | An ID that identifies this choice. |
title | String | The choice's title. The title may contain a maximum of 25 characters. |
votes | Integer | The total number of votes cast for this choice. |
channel_points_votes | Integer | The number of votes cast using Channel Points. |
bits_votes | Integer | Not used; will be set to 0. |
bits_voting_enabled | Boolean | Not used; will be set to false. |
bits_per_vote | Integer | Not used; will be set to 0. |
channel_points_voting_enabled | Boolean | A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide. |
channel_points_per_vote | Integer | The number of points the viewer must spend to cast one additional vote. |
status | String | The poll's status. Valid values are:
|
duration | Integer | The length of time (in seconds) that the poll will run for. |
started_at | String | The UTC date and time (in RFC3339 format) of when the poll began. |
ended_at | String | The UTC date and time (in RFC3339 format) of when the poll ended. If status is ACTIVE, this field is set to null. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request's after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster's polls. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
Example Request
Gets the specified broadcaster’s list of polls.
curl -X GET 'https://api.twitch.tv/helix/polls?broadcaster_id=141981764&id=ed961efd-8a3f-4cf5-a9d0-e616c590cd2a' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
"broadcaster_id": "55696719",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Heads or Tails?",
"choices": [
{
"id": "4c123012-1351-4f33-84b7-43856e7a0f47",
"title": "Heads",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
},
{
"id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
"title": "Tails",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
}
],
"bits_voting_enabled": false,
"bits_per_vote": 0,
"channel_points_voting_enabled": false,
"channel_points_per_vote": 0,
"status": "ACTIVE",
"duration": 1800,
"started_at": "2021-03-19T06:08:33.871278372Z"
}
],
"pagination": {}
}
Create Poll
✎Creates a poll that viewers in the broadcaster’s channel can vote on.
The poll begins as soon as it’s created. You may run only one poll at a time.
Authorization
Requires a user access token that includes the channel:manage:polls scope.
URL
POST https://api.twitch.tv/helix/polls
Request Body
Field | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that’s running the poll. This ID must match the user ID in the user access token. |
title | String | Yes | The question that viewers will vote on. For example, What game should I play next? The question may contain a maximum of 60 characters. |
choices | Object[] | Yes | A list of choices that viewers may choose from. The list must contain a minimum of 2 choices and up to a maximum of 5 choices. |
title | String | Yes | One of the choices the viewer may select. The choice may contain a maximum of 25 characters. |
duration | Integer | Yes | The length of time (in seconds) that the poll will run for. The minimum is 15 seconds and the maximum is 1800 seconds (30 minutes). |
channel_points_voting_enabled | Boolean | No | A Boolean value that indicates whether viewers may cast additional votes using Channel Points. If true, the viewer may cast more than one vote but each additional vote costs the number of Channel Points specified in channel_points_per_vote . The default is false (viewers may cast only one vote). For information about Channel Points, see Channel Points Guide. |
channel_points_per_vote | Integer | No | The number of points that the viewer must spend to cast one additional vote. The minimum is 1 and the maximum is 1000000. Set only if ChannelPointsVotingEnabled is true. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the single poll that you created. |
id | String | An ID that identifies the poll. |
broadcaster_id | String | An ID that identifies the broadcaster that created the poll. |
broadcaster_name | String | The broadcaster’s display name. |
broadcaster_login | String | The broadcaster’s login name. |
title | String | The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters. |
choices | Object[] | A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices. |
id | String | An ID that identifies this choice. |
title | String | The choice’s title. The title may contain a maximum of 25 characters. |
votes | Integer | The total number of votes cast for this choice. |
channel_points_votes | Integer | The number of votes cast using Channel Points. |
bits_votes | Integer | Not used; will be set to 0. |
bits_voting_enabled | Boolean | Not used; will be set to false. |
bits_per_vote | Integer | Not used; will be set to 0. |
channel_points_voting_enabled | Boolean | A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide. |
channel_points_per_vote | Integer | The number of points the viewer must spend to cast one additional vote. |
status | String | The poll’s status. Valid values are:
|
duration | Integer | The length of time (in seconds) that the poll will run for. |
started_at | String | The UTC date and time (in RFC3339 format) of when the poll began. |
ended_at | String | The UTC date and time (in RFC3339 format) of when the poll ended. If status is ACTIVE, this field is set to null. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully created the poll. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Creates a poll for the specified broadcaster.
curl -X POST 'https://api.twitch.tv/helix/polls' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"broadcaster_id":"141981764",
"title":"Heads or Tails?",
"choices":[{
"title":"Heads"
},
{
"title":"Tails"
}],
"channel_points_voting_enabled":true,
"channel_points_per_vote":100,
"duration":1800
}'
Example Response
{
"data": [
{
"id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Heads or Tails?",
"choices": [
{
"id": "4c123012-1351-4f33-84b7-43856e7a0f47",
"title": "Heads",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
},
{
"id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
"title": "Tails",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
}
],
"bits_voting_enabled": false,
"bits_per_vote": 0,
"channel_points_voting_enabled": true,
"channel_points_per_vote": 100,
"status": "ACTIVE",
"duration": 1800,
"started_at": "2021-03-19T06:08:33.871278372Z"
}
]
}
End Poll
✎Ends an active poll. You have the option to end it or end it and archive it.
Authorization
Requires a user access token that includes the channel:manage:polls scope.
URL
PATCH https://api.twitch.tv/helix/polls
Request Body
Field | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that’s running the poll. This ID must match the user ID in the user access token. |
id | String | Yes | The ID of the poll to update. |
status | String | Yes | The status to set the poll to. Possible case-sensitive values are:
|
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the poll that you ended. |
id | String | An ID that identifies the poll. |
broadcaster_id | String | An ID that identifies the broadcaster that created the poll. |
broadcaster_name | String | The broadcaster’s display name. |
broadcaster_login | String | The broadcaster’s login name. |
title | String | The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters. |
choices | Object[] | A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices. |
id | String | An ID that identifies this choice. |
title | String | The choice’s title. The title may contain a maximum of 25 characters. |
votes | Integer | The total number of votes cast for this choice. |
channel_points_votes | Integer | The number of votes cast using Channel Points. |
bits_votes | Integer | Not used; will be set to 0. |
bits_voting_enabled | Boolean | Not used; will be set to false. |
bits_per_vote | Integer | Not used; will be set to 0. |
channel_points_voting_enabled | Boolean | A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide. |
channel_points_per_vote | Integer | The number of points the viewer must spend to cast one additional vote. |
status | String | The poll’s status. Valid values are:
|
duration | Integer | The length of time (in seconds) that the poll will run for. |
started_at | String | The UTC date and time (in RFC3339 format) of when the poll began. |
ended_at | String | The UTC date and time (in RFC3339 format) of when the poll ended. If status is ACTIVE, this field is set to null. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully ended the poll. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Ends the specific poll, but allows the results to be visible for viewers.
curl -X PATCH 'https://api.twitch.tv/helix/polls' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"broadcaster_id":"141981764",
"id":"ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
"status":"TERMINATED"
}'
Example Response
{
"data": [
{
"id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Heads or Tails?",
"choices": [
{
"id": "4c123012-1351-4f33-84b7-43856e7a0f47",
"title": "Heads",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
},
{
"id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
"title": "Tails",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
}
],
"bits_voting_enabled": false,
"bits_per_vote": 0,
"channel_points_voting_enabled": true,
"channel_points_per_vote": 100,
"status": "TERMINATED",
"duration": 1800,
"started_at": "2021-03-19T06:08:33.871278372Z",
"ended_at": "2021-03-19T06:11:26.746889614Z"
}
]
}
Get Predictions
✎Gets a list of Channel Points Predictions that the broadcaster created.
Authorization
Requires a user access token that includes the channel:read:predictions or channel:manage:predictions scope.
URL
GET https://api.twitch.tv/helix/predictions
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster whose predictions you want to get. This ID must match the user ID in the user access token. |
id | String | No | The ID of the prediction to get. To specify more than one ID, include this parameter for each prediction you want to get. For example, id=1234&id=5678 . You may specify a maximum of 25 IDs. The endpoint ignores duplicate IDs and those not owned by the broadcaster. |
first | String | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 25 items per page. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | The broadcaster’s list of Channel Points Predictions. The list is sorted in descending ordered by when the prediction began (the most recent prediction is first). The list is empty if the broadcaster hasn’t created predictions. |
id | String | An ID that identifies this prediction. |
broadcaster_id | String | An ID that identifies the broadcaster that created the prediction. |
broadcaster_name | String | The broadcaster’s display name. |
broadcaster_login | String | The broadcaster’s login name. |
title | String | The question that the prediction asks. For example, Will I finish this entire pizza? |
winning_outcome_id | String | The ID of the winning outcome. Is null unless status is RESOLVED. |
outcomes | Object[] | The list of possible outcomes for the prediction. |
id | String | An ID that identifies this outcome. |
title | String | The outcome’s text. |
users | Integer | The number of unique viewers that chose this outcome. |
channel_points | Integer | The number of Channel Points spent by viewers on this outcome. |
top_predictors | Object[] | A list of viewers who were the top predictors; otherwise, null if none. |
user_id | String | An ID that identifies the viewer. |
user_name | String | The viewer’s display name. |
user_login | String | The viewer’s login name. |
channel_points_used | Integer | The number of Channel Points the viewer spent. |
channel_points_won | Integer | The number of Channel Points distributed to the viewer. |
color | String | The color that visually identifies this outcome in the UX. Possible values are:
|
prediction_window | Integer | The length of time (in seconds) that the prediction will run for. |
status | String | The prediction’s status. Valid values are:
|
created_at | String | The UTC date and time of when the Prediction began. |
ended_at | String | The UTC date and time of when the Prediction ended. If status is ACTIVE, this is set to null. |
locked_at | String | The UTC date and time of when the Prediction was locked. If status is not LOCKED, this is set to null. |
pagination | Object | Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More |
cursor | String | The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the list of predictions. |
400 Bad Request |
|
401 Unauthorized |
|
Example Request
Gets the specified broadcaster’s list of predictions.
curl -X GET 'https://api.twitch.tv/helix/predictions?broadcaster_id=55696719&id=d6676d5c-c86e-44d2-bfc4-100fb48f0656' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "d6676d5c-c86e-44d2-bfc4-100fb48f0656",
"broadcaster_id": "55696719",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Will there be any leaks today?",
"winning_outcome_id": null,
"outcomes": [
{
"id": "021e9234-5893-49b4-982e-cfe9a0aaddd9",
"title": "Yes",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "BLUE"
},
{
"id": "ded84c26-13cb-4b48-8cb5-5bae3ec3a66e",
"title": "No",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "PINK"
}
],
"prediction_window": 600,
"status": "ACTIVE",
"created_at": "2021-04-28T16:03:06.320848689Z",
"ended_at": null,
"locked_at": null
}
],
"pagination": {}
}
Create Prediction
✎Creates a Channel Points Prediction.
With a Channel Points Prediction, the broadcaster poses a question and viewers try to predict the outcome. The prediction runs as soon as it’s created. The broadcaster may run only one prediction at a time.
Authorization
Requires a user access token that includes the channel:manage:predictions scope.
URL
POST https://api.twitch.tv/helix/predictions
Request Body
Field | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that’s running the prediction. This ID must match the user ID in the user access token. |
title | String | Yes | The question that the broadcaster is asking. For example, Will I finish this entire pizza? The title is limited to a maximum of 45 characters. |
outcomes | Object[] | Yes | The list of possible outcomes that the viewers may choose from. The list must contain a minimum of 2 choices and up to a maximum of 10 choices. |
title | String | Yes | The text of one of the outcomes that the viewer may select. The title is limited to a maximum of 25 characters. |
prediction_window | Integer | Yes | The length of time (in seconds) that the prediction will run for. The minimum is 30 seconds and the maximum is 1800 seconds (30 minutes). |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the single prediction that you created. |
id | String | An ID that identifies this prediction. |
broadcaster_id | String | An ID that identifies the broadcaster that created the prediction. |
broadcaster_name | String | The broadcaster’s display name. |
broadcaster_login | String | The broadcaster’s login name. |
title | String | The question that the prediction asks. For example, Will I finish this entire pizza? |
winning_outcome_id | String | The ID of the winning outcome. Is null unless status is RESOLVED. |
outcomes | Object[] | The list of possible outcomes for the prediction. |
id | String | An ID that identifies this outcome. |
title | String | The outcome’s text. |
users | Integer | The number of unique viewers that chose this outcome. |
channel_points | Integer | The number of Channel Points spent by viewers on this outcome. |
top_predictors | Object[] | A list of viewers who were the top predictors; otherwise, null if none. |
user_id | String | An ID that identifies the viewer. |
user_name | String | The viewer’s display name. |
user_login | String | The viewer’s login name. |
channel_points_used | Integer | The number of Channel Points the viewer spent. |
channel_points_won | Integer | The number of Channel Points distributed to the viewer. |
color | String | The color that visually identifies this outcome in the UX. Possible values are:
|
prediction_window | Integer | The length of time (in seconds) that the prediction will run for. |
status | String | The prediction’s status. Valid values are:
|
created_at | String | The UTC date and time of when the Prediction began. |
ended_at | String | The UTC date and time of when the Prediction ended. If status is ACTIVE, this is set to null. |
locked_at | String | The UTC date and time of when the Prediction was locked. If status is not LOCKED, this is set to null. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully created the Channel Points Prediction. |
400 Bad Request |
|
401 Unauthorized |
|
429 Too Many Requests |
Example Request
Creates a Channel Points Prediction for the specified broadcaster.
curl -X POST 'https://api.twitch.tv/helix/predictions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"broadcaster_id": "141981764",
"title": "Any leeks in the stream?",
"outcomes": [
{
"title": "Yes, give it time."
},
{
"title": "Definitely not."
}
],
"prediction_window": 120
}'
Example Response
{
"data": [
{
"id": "bc637af0-7766-4525-9308-4112f4cbf178",
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Any leeks in the stream?",
"winning_outcome_id": null,
"outcomes": [
{
"id": "73085848-a94d-4040-9d21-2cb7a89374b7",
"title": "Yes, give it time.",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "BLUE"
},
{
"id": "906b70ba-1f12-47ea-9e95-e5f93d20e9cc",
"title": "Definitely not.",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "PINK"
}
],
"prediction_window": 120,
"status": "ACTIVE",
"created_at": "2021-04-28T17:11:22.595914172Z",
"ended_at": null,
"locked_at": null
}
]
}
End Prediction
✎Locks, resolves, or cancels a Channel Points Prediction.
Authorization
Requires a user access token that includes the channel:manage:predictions scope.
URL
PATCH https://api.twitch.tv/helix/predictions
Request Body
Field | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that’s running the prediction. This ID must match the user ID in the user access token. |
id | String | Yes | The ID of the prediction to update. |
status | String | Yes | The status to set the prediction to. Possible case-sensitive values are:
The broadcaster has up to 24 hours after the prediction window closes to resolve the prediction. If not, Twitch sets the status to CANCELED and returns the points. |
winning_outcome_id | String | No | The ID of the winning outcome. You must set this parameter if you set status to RESOLVED. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains the single prediction that you updated. |
id | String | An ID that identifies this prediction. |
broadcaster_id | String | An ID that identifies the broadcaster that created the prediction. |
broadcaster_name | String | The broadcaster’s display name. |
broadcaster_login | String | The broadcaster’s login name. |
title | String | The question that the prediction asks. For example, Will I finish this entire pizza? |
winning_outcome_id | String | The ID of the winning outcome. Is null unless status is RESOLVED. |
outcomes | Object[] | The list of possible outcomes for the prediction. |
id | String | An ID that identifies this outcome. |
title | String | The outcome’s text. |
users | Integer | The number of unique viewers that chose this outcome. |
channel_points | Integer | The number of Channel Points spent by viewers on this outcome. |
top_predictors | Object[] | A list of viewers who were the top predictors; otherwise, null if none. |
user_id | String | An ID that identifies the viewer. |
user_name | String | The viewer’s display name. |
user_login | String | The viewer’s login name. |
channel_points_used | Integer | The number of Channel Points the viewer spent. |
channel_points_won | Integer | The number of Channel Points distributed to the viewer. |
color | String | The color that visually identifies this outcome in the UX. Possible values are:
|
prediction_window | Integer | The length of time (in seconds) that the prediction will run for. |
status | String | The prediction’s status. Valid values are:
|
created_at | String | The UTC date and time of when the Prediction began. |
ended_at | String | The UTC date and time of when the Prediction ended. If status is ACTIVE, this is set to null. |
locked_at | String | The UTC date and time of when the Prediction was locked. If status is not LOCKED, this is set to null. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully ended the prediction. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
Example Request
Resolves the specified Channel Points Prediction.
curl -X PATCH 'https://api.twitch.tv/helix/predictions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"broadcaster_id": "141981764",
"id": "bc637af0-7766-4525-9308-4112f4cbf178",
"status": "RESOLVED",
"winning_outcome_id": "73085848-a94d-4040-9d21-2cb7a89374b7"
}'
Example Response
{
"data": [
{
"id": "bc637af0-7766-4525-9308-4112f4cbf178",
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Will we win all the games?",
"winning_outcome_id": "73085848-a94d-4040-9d21-2cb7a89374b7",
"outcomes": [
{
"id": "73085848-a94d-4040-9d21-2cb7a89374b7",
"title": "yes",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "BLUE"
},
{
"id": "86010b2e-9764-4136-9359-fd1c9c5a8033",
"title": "no",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "PINK"
}
],
"prediction_window": 120,
"status": "RESOLVED",
"created_at": "2021-04-28T21:48:19.480371331Z",
"ended_at": "2021-04-28T21:54:24.026833954Z",
"locked_at": "2021-04-28T21:48:34.636685705Z"
}
]
}
Start a raid
✎Raid another channel by sending the broadcaster’s viewers to the targeted channel.
When you call the API from a chat bot or extension, the Twitch UX pops up a window at the top of the chat room that identifies the number of viewers in the raid. The raid occurs when the broadcaster clicks Raid Now or after the 90-second countdown expires.
To determine whether the raid successfully occurred, you must subscribe to the Channel Raid event. For more information, see Get notified when a raid begins.
To cancel a pending raid, use the Cancel a raid endpoint.
Rate Limit: The limit is 10 requests within a 10-minute window.
Authorization
Requires a user access token that includes the channel:manage:raids scope.
URL
POST https://api.twitch.tv/helix/raids
Request Query Parameters
Parameter | Type | Required ? | Description |
---|---|---|---|
from_broadcaster_id | String | Yes | The ID of the broadcaster that’s sending the raiding party. This ID must match the user ID in the user access token. |
to_broadcaster_id | String | Yes | The ID of the broadcaster to raid. |
Response Body
Field | Type | Description |
---|---|---|
data | Object[] | A list that contains a single object with information about the pending raid. |
created_at | String | The UTC date and time, in RFC3339 format, of when the raid was requested. |
is_mature | Boolean | A Boolean value that indicates whether the channel being raided contains mature content. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully requested to start a raid. To determine whether the raid successfully occurred (that is, the broadcaster clicked Raid Now or the countdown expired), you must subscribe to the Channel Raid event. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
409 Conflict |
|
429 Too Many Requests |
|
Example Request
curl -X POST 'https://api.twitch.tv/helix/raids?from_broadcaster_id=12345678&to_broadcaster_id=87654321' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Example Response
{
"data": [
{
"created_at": "2022-02-18T07:20:50.52Z",
"is_mature": false
}
]
}
Cancel a raid
✎Cancel a pending raid.
You can cancel a raid at any point up until the broadcaster clicks Raid Now in the Twitch UX or the 90-second countdown expires.
Rate Limit: The limit is 10 requests within a 10-minute window.
Authorization
Requires a user access token that includes the channel:manage:raids scope.
URL
DELETE https://api.twitch.tv/helix/raids
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that initiated the raid. This ID must match the user ID in the user access token. |
Response Codes
Code | Description |
---|---|
204 No Content | The pending raid was successfully canceled. |
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
429 Too Many Requests |
|
Example Request
curl -X DELETE 'https://api.twitch.tv/helix/raids?broadcaster_id=12345678' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'
Get Channel Stream Schedule
✎Gets the broadcaster’s streaming schedule. You can get the entire schedule or specific segments of the schedule. Learn More
Authorization
Requires an app access token or user access token.
URL
GET https://api.twitch.tv/helix/schedule
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that owns the streaming schedule you want to get. |
id | String | No | The ID of the scheduled segment to return. To specify more than one segment, include the ID of each segment you want to get. For example, id=1234&id=5678 . You may specify a maximum of 100 IDs. |
start_time | String | No | The UTC date and time that identifies when in the broadcaster’s schedule to start returning segments. If not specified, the request returns segments starting after the current UTC date and time. Specify the date and time in RFC3339 format (for example, 2022-09-01T00:00:00Z ). |
utc_offset | String | No | Not supported. |
first | Integer | No | The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 25 items per page. The default is 20. |
after | String | No | The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read More |
Response Body
Field | Type | Description |
---|---|---|
data | Object | The broadcaster’s streaming schedule. |
segments | Object[] | The list of broadcasts in the broadcaster’s streaming schedule. |
id | String | An ID that identifies this broadcast segment. |
start_time | String | The UTC date and time (in RFC3339 format) of when the broadcast starts. |
end_time | String | The UTC date and time (in RFC3339 format) of when the broadcast ends. |
title | String | The broadcast segment’s title. |
canceled_until | String | Indicates whether the broadcaster canceled this segment of a recurring broadcast. If the broadcaster canceled this segment, this field is set to the same value that’s in the end_time field; otherwise, it’s set to null. |
category | Object | The type of content that the broadcaster plans to stream or null if not specified. |
id | String | An ID that identifies the category that best represents the content that the broadcaster plans to stream. For example, the game’s ID if the broadcaster will play a game or the Just Chatting ID if the broadcaster will host a talk show. |
name | String | The name of the category. For example, the game’s title if the broadcaster will playing a game or Just Chatting if the broadcaster will host a talk show. |
is_recurring | Boolean | A Boolean value that determines whether the broadcast is part of a recurring series that streams at the same time each week or is a one-time broadcast. Is true if the broadcast is part of a recurring series. |
broadcaster_id | String | The ID of the broadcaster that owns the broadcast schedule. |
broadcaster_name | String | The broadcaster’s display name. |
broadcaster_login | String | The broadcaster’s login name. |
vacation | Object | The dates when the broadcaster is on vacation and not streaming. Is set to null if vacation mode is not enabled. |
start_time | String | The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation starts. |
end_time | String | The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation ends. |
pagination | Object | The information used to page through a list of results. The object is empty if there are no more pages left to page through. Read more. |
cursor | String | The cursor used to get the next page of results. Set the request’s after query parameter to this value. |
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s streaming schedule. |
400 Bad Request |
|
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
Example Request
Gets the specified broadcaster’s streaming schedule.
curl -X GET 'https://api.twitch.tv/helix/schedule?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": {
"segments": [
{
"id": "eyJzZWdtZW50SUQiOiJlNGFjYzcyNC0zNzFmLTQwMmMtODFjYS0yM2FkYTc5NzU5ZDQiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyNn0=",
"start_time": "2021-07-01T18:00:00Z",
"end_time": "2021-07-01T19:00:00Z",
"title": "TwitchDev Monthly Update // July 1, 2021",
"canceled_until": null,
"category": {
"id": "509670",
"name": "Science & Technology"
},
"is_recurring": false
},
...
],
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"vacation": null
},
"pagination": {}
}
Get Channel iCalendar
✎Gets the broadcaster’s streaming schedule as an iCalendar.
Authorization
The Client-Id and Authorization headers are not required.
URL
GET https://api.twitch.tv/helix/schedule/icalendar
Request Query Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
broadcaster_id | String | Yes | The ID of the broadcaster that owns the streaming schedule you want to get. |
Response Body
The response body contains the iCalendar data (see RFC5545).
The Content-Type response header is set to text/calendar
.
Response Codes
Code | Description |
---|---|
200 OK | Successfully retrieved the broadcaster’s schedule as an iCalendar. |
400 Bad Request |
|
Example Request
Gets the specified broadcaster’s streaming schedule as an iCalendar.
curl -X GET 'https://api.twitch.tv/helix/schedule/icalendar?broadcaster_id=141981764'
Example Response
BEGIN:VCALENDAR
PRODID:-//twitch.tv//StreamSchedule//1.0
VERSION:2.0
CALSCALE:GREGORIAN
REFRESH-INTERVAL;VALUE=DURATION:PT1H
NAME:TwitchDev
BEGIN:VEVENT
UID:e4acc724-371f-402c-81ca-23ada79759d4
DTSTAMP:20210323T040131Z
DTSTART;TZID=/America/New_York:20210701T140000
DTEND;TZID=/America/New_York:20210701T150000
SUMMARY:TwitchDev Monthly Update // July 1, 2021
DESCRIPTION:Science & Technology.
CATEGORIES:Science & Technology
END:VEVENT
END:VCALENDAR%
Update Channel Stream Schedule
✎Updates the broadcaster’s schedule settings, such as scheduling a vacation.
Authorization
Requires a user access token that includes the channel:manage:schedule