Twitch API Essential Guide

What type of API does Twitch provide?

Twitch primarily uses a GraphQL API. Their GraphQL API is hosted on https://gql.twitch.tv/gql. They use GraphQL for most of their API operations, with multiple GraphQL requests being made for each page load. Twitch sends GraphQL queries using HTTP POST requests.

Twitch does not appear to be versioning their GraphQL API. They use a batching mechanism, sending multiple GraphQL operations as an array in a single request. The API uses HTTP/1.1 rather than HTTP/2.

Twitch does not use GraphQL subscriptions for real-time updates. Instead, they use WebSockets for features like chat, which appears to be based on IRC.

Does the Twitch API have webhooks?

Yes, the official Twitch API has webhooks, which are part of their EventSub system. EventSub allows your application to listen for events that happen on Twitch.

Event Types

You can subscribe to various types of events, including:

• When a broadcaster goes online
• When a broadcaster gets a new follower
• When a broadcaster gets a new subscriber
• When a user cheers in a channel
• When a user redeems Channel Points

Subscription Process

To subscribe to events:

1. Create a webhook callback that listens for events. It must use SSL and listen on port 443.
2. Use the "Create EventSub Subscription" API endpoint to subscribe to specific events.
3. Specify the event type, version, conditions, and transport method (webhook or websocket) in your subscription request.

Notification Types

Your webhook handler needs to process three types of notifications:

1. notification: Contains the actual event data
2. webhook_callback_verification: Used to verify ownership of the webhook endpoint
3. revocation: Sent if Twitch revokes your subscription

Best Practices

• Verify the signature of incoming webhook messages to ensure they're from Twitch.
• Handle potential duplicate notifications.
• Monitor your subscription status and resubscribe if necessary.

Code Example

Here's a basic example of subscribing to a channel follow event using cURL:

curl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Client-Id: YOUR_CLIENT_ID' \
-H 'Content-Type: application/json' \
-d '{
  "type": "channel.follow",
  "version": "2",
  "condition": {
    "broadcaster_user_id": "1234",
    "moderator_user_id": "1234"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/callback",
    "secret": "s3cre77890ab"
  }
}'

This example subscribes to follow events for a specific channel.

Remember that for local development, you'll need to make your webhook endpoint publicly accessible. Tools like ngrok can help with this.

Rate Limits and other limitations

Here are the key points about the API rate limits for the Twitch API:

General Rate Limits

• Twitch uses a token-bucket algorithm to enforce rate limits.
• There are separate buckets for app access requests and user access requests.
• For user access requests, limits are applied per client ID per user per minute.
• If you exceed the limit, you'll receive an HTTP 429 (Too Many Requests) error.

Extension-Specific Rate Limits

• For Twitch Extensions, there is a rate limit of 30 requests per minute per Extension viewer.
• This limit applies across all Twitch APIs accessible by the Extension token.

Tracking Usage

The API includes the following headers with each response to help track usage:

• Ratelimit-Limit: The rate at which points are added to your bucket
• Ratelimit-Remaining: The number of points remaining in your bucket
• Ratelimit-Reset: A Unix epoch timestamp indicating when your bucket will reset to full

Key Considerations

1. Different endpoints may have different point values or limit values. Check the specific endpoint documentation for details.

2. If you receive a 429 error, use the Ratelimit-Reset header to determine how long to wait before making another request.

3. For list APIs, you can control the page size using the first query parameter, but be aware of minimum and maximum page size limits for each endpoint.

4. Some endpoints may have non-standard rate limit implementations. For example, the "Get EventSub Subscriptions" endpoint doesn't allow specifying page size.

Best Practices

1. Monitor the rate limit headers in API responses to stay within limits.
2. Implement backoff and retry logic for handling 429 errors.
3. Optimize your API usage by batching requests where possible and only requesting necessary data.
4. Be aware that rate limits may change, so design your application to be flexible and respect the limits provided in the headers.

By understanding and respecting these rate limits, you can ensure your application interacts smoothly with the Twitch API without disruptions due to exceeding usage thresholds.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the Twitch API:

1. The Twitch API does not have explicit version numbers like v1, v2, etc. Instead, it is continuously updated and improved.

2. The most recent major update mentioned is from March 7, 2024, which included the following:

   • Channel Chat Settings Update moved from public beta to v1
   • Added new API endpoints and EventSub subscription types in open beta, including:
     • Get Unban Requests
     • Resolve Unban Requests
     • Get User Emotes
     • New EventSub types for unban requests and automod features

3. Other recent updates include:

   • January 25, 2024: Conduits feature became generally available
   • January 8, 2024: Added Get Moderated Channels and channel.chat_settings.update to open beta
   • October 19, 2023: Added Chat on EventSub features to open beta

4. The Twitch API uses OAuth 2.0 for authentication and provides various endpoints for different functionalities.

5. Twitch recommends using EventSub subscriptions for receiving real-time updates instead of polling API endpoints.

6. Twitch offers a command-line interface (CLI) for managing Twitch resources and interacting with the API.

It's important to note that the Twitch API is continuously evolving, with new features and endpoints being added regularly. Developers should refer to the official Twitch API documentation and change logs for the most up-to-date information on available endpoints and features.

How to get a Twitch developer account and API Keys?

To get a developer account for Twitch and create an API integration, follow these steps:

1. Create a Twitch account:

   • You only need a regular Twitch account to get started. No special developer credentials are required initially.

2. Enable two-factor authentication (2FA):

   • Log in to your Twitch account
   • Go to Security and Privacy settings
   • Follow the steps to enable 2FA
   • Refresh the developer console after enabling 2FA

3. Register your application:

   • Log in to the Twitch developer console (https://dev.twitch.tv/console)
   • Go to the "Applications" tab
   • Click "Register Your Application"
   • Fill out the registration form:
     • Name: Choose a unique name for your application
     • OAuth Redirect URLs: Set this to http://localhost:3000 for testing, or your actual callback URL
     • Category: Select the appropriate category for your application

4. Get your Client ID and Client Secret:

   • After registering, go back to the "Applications" tab
   • Find your app under "Developer Applications" and click "Manage"
   • Note your Client ID
   • Click "New Secret" to generate a Client Secret
   • Save both the Client ID and Client Secret securely

5. Get an OAuth token:

   • Use the Client Credentials flow to get an app access token
   • You can use cURL, the Twitch CLI, or other methods to obtain the token

What can you do with the Twitch API?

Here's a list of data models you can interact with using the Twitch API, along with what is possible for each:

1. Users

• Get user information (id, login name, display name, profile image, etc.)
• Update user information (description, profile image)
• Get user's followed channels
• Check if a user follows another user

2. Channels

• Get channel information (title, game, tags, language, etc.)
• Modify channel information (title, game, tags, delay)
• Get channel editors
• Get channel followers
• Get channel subscriptions

3. Streams

• Get information about live streams
• Get stream key
• Create stream markers
• Get stream markers

4. Videos

• Get video information (title, description, duration, view count, etc.)
• Delete videos
• Get muted segments of videos

5. Clips

• Create clips from streams
• Get clip information
• Get top clips for a game or channel

6. Games

• Get game information
• Get top games

7. Analytics

• Get game analytics
• Get extension analytics

8. Bits

• Get bits leaderboard
• Get cheermotes

9. Subscriptions

• Get subscription information for a channel
• Check if a user is subscribed to a channel

10. Chat

• Get chat settings
• Update chat settings
• Send chat announcements
• Get chatters in a channel

11. Moderation

• Ban/unban users
• Get banned users
• Get moderators
• Add/remove moderators

12. Polls

• Create polls
• End polls
• Get poll information

13. Predictions

• Create predictions
• End predictions
• Get prediction information

14. Raids

• Start a raid
• Cancel a raid

15. Schedule

• Get channel stream schedule
• Update channel stream schedule
• Create or update schedule segments

16. Teams

• Get team information
• Get channel teams

17. Extensions

• Get extension information
• Get live channels using an extension

18. EventSub

• Create event subscriptions
• Delete event subscriptions
• Get event subscription information

Each of these data models allows for various operations such as retrieving, creating, updating, or deleting data, depending on the specific endpoint and permissions granted to your application.