On this page
- What TwitchConvergence Free can do on your server
- Check the requirements before you start
- Open a port Twitch can reach
- Register an application in the Twitch developer console
- Install the plugin and fill in config.yml
- Authorize your channel and let players link
- Turn follows and subs into in-game moments
- Give follower and sub ranks: premium or by hand
- Test your configuration before you go live
- Keep the Twitch connection alive
- Fix the common setup problems
Key takeaways
6- TwitchConvergence Free needs an extra TCP port reachable from the internet (default 8008); on panels, ask your host for an extra allocation.
- Register an app at the Twitch developer console as Category Other, Client Type Confidential, with a redirect URL using your domain and port.
- Put the client ID and secret into plugins/TwitchConvergence/config.yml, then run tc reload and tc authorize; players link with tc link.
- The free version covers announcements and commands on live, follow and sub events; custom rank distribution, bits, raids and channel points are premium.
- The listing supports 1.9 to 1.21 and 26.1 to 26.2 on Java 11+; earlier version support is premium.
- Twitch can drop the connection after about 12 idle hours, so run tc reload before streaming.
This guide is for streamers and server owners who want their Twitch channel to talk to their Minecraft server. By the end you will have TwitchConvergence Free installed, your channel authorized, players able to link their Twitch accounts, and in-game announcements and commands firing when someone follows or subscribes.
What TwitchConvergence Free can do on your server
TwitchConvergence Free is a plugin by ForbiddenSoul, listed on SpigotMC as free (version 1.0.2 at the time of writing). It connects one Twitch channel to your server and reacts to what happens on that channel.
- Account linking: players join their Minecraft and Twitch accounts.
- Chat merging: Minecraft chat and Twitch chat can be brought together.
- Announcements and event commands: react to Twitch events in game, for example fireworks from every player's location when the stream starts, or an emerald for everyone when someone follows.
- Testing: the author says you can test your configuration with the official Twitch CLI.
The free and premium versions differ in which Twitch events they listen for and in a few extras:
| Feature | Free version | Premium version |
|---|---|---|
| Stream online and offline | Yes | Yes |
| Follow | Yes | Yes |
| Subscribe, re-sub, gift sub, sub end | Yes | Yes |
| Cheers (bits), raids | No | Yes |
| Channel points redemptions | No | Yes |
| Polls, predictions, goals, hype trains | No | Yes |
| Custom rank distribution | No | Yes |
| Support for Minecraft versions older than 1.9 | No | Yes |
If channel points, raids or your own follower and subscriber ranks are the main thing you want, look at the premium TwitchConvergence listing by the same author. For live alerts, plus announcements and commands on follows and subs, the free version is enough.
Check the requirements before you start
- A Minecraft server on one of the listed versions: 1.9 to 1.21, or 26.1 to 26.2. Support for earlier versions is a premium feature.
- Java 11 or newer.
- One extra TCP port that Twitch can reach from the internet. The plugin uses
8008by default. - A Twitch account for the channel you want to connect.
Open a port Twitch can reach
Pick a free TCP port. Use 8008 if nothing else on the machine uses it. Whatever number you end up with, you will use it in three places: your firewall or panel, the Twitch app redirect URL, and the plugin config.
- Open the port in your firewall. With UFW that looks like this:
sudo ufw allow 8008/tcp - If your provider has a separate cloud firewall or security group in its dashboard, allow TCP
8008there too. - If the server runs at home behind a router, forward TCP
8008on the router to the machine running Minecraft, the same way you forwarded the game port.
- Your server can only listen on ports the host has given it (called allocations). Open the server's Network tab and see if you can add an extra allocation.
- If you can, add one and note its port number. That number replaces
8008everywhere in this guide. - If there is no option to add one, open a ticket with your host and ask for one additional TCP port for a plugin web listener. You cannot open ports yourself from inside the container.
- Multicraft servers usually get a single game port from the host, with no way to add more from the panel.
- Ask your host for an extra TCP port assigned to your server, and note the number they give you.
- Use that number instead of
8008in the steps below.
Register an application in the Twitch developer console
The plugin talks to Twitch through an app you own. This is where its client ID and secret come from.
- Sign in and go to
dev.twitch.tv/console/apps, then click Register Your Application. - Name: any unique name, for example your server name plus "Bridge".
- OAuth Redirect URLs: follow the format from the plugin's documentation, putting your own domain (or server IP) and port in:
If you only ever authorize from the same machine the server runs on, the docs also allow:
https://redirectmeto.com/http://yourdomain.com:8008http://localhost:8008 - Category: Other.
- Client Type: Confidential.
- Complete the captcha and click Create.
- Back on the Applications list, click Manage on your app. Keep this page open, you need the Client ID from it next, and you will click New Secret to get the client secret.
Install the plugin and fill in config.yml
Download the jar from the SpigotMC page, put it in the server, and let the server create the config on first start.
- Copy the jar into the plugins folder, for example with
scpor by downloading it on the server. - Restart the server (stop it cleanly, then start it again with your usual start script).
- Open the generated file:
nano plugins/TwitchConvergence/config.yml
- In the File Manager, open the
pluginsfolder and upload the jar (or upload it over SFTP, using the details on the Settings page). - Restart the server from the Console.
- Back in the File Manager, open
plugins/TwitchConvergence/config.ymlin the built-in editor.
- Go to Files, then FTP File Access, and upload the jar into
plugins. - Restart the server from the main panel page and watch the console until it finishes starting.
- Open
plugins/TwitchConvergence/config.ymlthrough the file manager or your FTP client.
In the config, fill in:
- The client ID from your Twitch app page.
- The client secret (click New Secret on the Twitch app page to see it).
- The port, if you are not using
8008. - Your announcement and event command settings. Read the comments in the file for each option rather than guessing names.
Save the file. Treat the client secret like a password: do not paste it in Discord or screenshots.
Authorize your channel and let players link
These commands come from the plugin's documentation. Run them from the server console (or in game, with an account that has access).
- Load your edited config:
tc reload - Start the Twitch authorization:
tc authorize - Open the link it prints. Check the Twitch account shown is the channel you want to connect, then click Authorize.
- Tell your players and viewers to link their own accounts with:
tc link
Turn follows and subs into in-game moments
The author's own examples give a feel for what works: fireworks from everyone's location when the stream goes live, or an emerald for everyone online when someone follows. A few ideas that suit most servers:
- Stream online: a broadcast plus fireworks, so players know to tune in.
- Follow: a small server-wide gift, which rewards the whole community rather than one person.
- Subscribe, re-sub or gift sub: a thank-you announcement in chat, with a slightly bigger gift for everyone online.
- Stream offline: a short message pointing players to your Discord or next stream time.
Give follower and sub ranks: premium or by hand
Custom rank distribution is listed as a premium feature, so do not plan around automatic follower or subscriber groups on the free version. You have two options:
- Premium: upgrade to the premium TwitchConvergence and use its custom rank distribution.
- Manual: create a follower group and a subscriber group in a permissions plugin such as LuckPerms, give them their prefix and perks there, and add or remove members yourself when viewers ask, for example after checking your Twitch subscriber list.
Either way, keep these ranks cosmetic or small so players who do not watch the stream never feel locked out.
Test your configuration before you go live
Nobody wants to discover a broken reward command in front of viewers. The author says you can test your configuration with the official Twitch CLI, Twitch's own command line tool for developers. Try it on a test server first and check each command does what you expect.
Keep the Twitch connection alive
The documentation warns that Twitch drops the connection when the plugin sits idle for a long time, usually after about 12 hours or more. If events stop arriving after a quiet day, run tc reload again. A simple habit is to reload the plugin before each stream, or rely on your regular daily restart.
Fix the common setup problems
| Problem | Likely cause | What to do |
|---|---|---|
| Authorize link fails or never returns | Port not reachable from the internet | Recheck the firewall, router forward, or the extra allocation from your host |
| Twitch says the redirect URL is invalid | Redirect URL on the Twitch app does not match your domain or port | Edit the app on the Twitch console so the domain and port match exactly |
| Config changes do nothing | Config not reloaded | Save the file, then run tc reload |
| Events worked yesterday, not today | Idle disconnect after many hours | Run tc reload |
| Plugin will not load | Java older than 11, or a Minecraft version outside the listed range | Update Java on a VPS, or ask your host to switch the Java version or Docker image; check your version is on the list |
If something still fails, the author runs a support Discord linked from the SpigotMC page, which is the right place for questions about specific config options.
Frequently asked questions
Can I use TwitchConvergence on shared Minecraft hosting?
Yes, if your host can give your server an extra port that is reachable from the internet. On Pterodactyl that is an extra allocation, which you may be able to add in the Network tab or need to request from support. Without an open port the plugin will not work, as the author states on the listing.
Does TwitchConvergence Free support channel points?
No. The free version handles stream online and offline, follows, subscriptions, re-subs, gift subs and sub ends. Channel points redemptions, bits, raids, polls, predictions, goals and hype trains are listed as premium features.
Why did my Twitch events stop working after a day?
The plugin's documentation says Twitch disconnects it after being idle for a long time, usually about 12 hours or more. Run tc reload to reconnect, or reload before each stream.
What Minecraft and Java versions does TwitchConvergence need?
The SpigotMC listing names Minecraft 1.9 to 1.21 and 26.1 to 26.2, with Java 11 or newer. Support for earlier versions is listed as a premium feature.
Can TwitchConvergence Free give subscribers a rank automatically?
Custom rank distribution is listed as a premium feature, so plan on the free version for announcements and commands on events. For follower or sub ranks, either upgrade to premium or add viewers to a LuckPerms group yourself.
