Skip to content

Twitch

Jump to bottom
JR edited this page Sep 27, 2023 · 76 revisions

If you're interested in trying the bot but don't want to run it yourself, contact me and I'll host an instance on a headless server.

Some of the steps below can be automated by passing --setup-twitch. The instructions in the readme are currently more up-to-date.

Connecting

To connect to Twitch servers, you must first compile the twitch build configuration to include Twitch support. All pre-compiled binaries available from under Releases already have this built-in.

You must also supply an OAuth token API key. Run the bot with --set twitch.keygen to start the captive process of generating one. It will open a browser window, in which you are asked to log onto Twitch on Twitch's own servers. Verify this by checking the page address; it should end with .twitch.tv, with the little lock symbol showing the connection is secure.

Note: At no point is the bot privy to your Twitch login credentials! The logging-in is wholly done on Twitch's own servers, and no information is sent to any third parties. The code that deals with this is open for audit; requestTwitchKey in plugins/twitch/keygen.d.

After entering your login and password and clicking Authorize, you will be redirected to an empty "this site can't be reached" or "unable to connect" page. Copy the URL address of it and paste it into the terminal, when asked. It will parse the address, extract your authorisation token, and offer to save it to your configuration file.

If you prefer to generate the token manually, here is the URL you need to follow. The key generation wizard only opens it for you, as well as automates saving the resulting token to your configuration file (as pass under [IRCBot]). . The only thing the generation process does is open it for you, and automate saving the end key to disk.

Example configuration

[IRCClient]
nickname            doesntmatter
user                ignored
realName            likewise

[IRCBot]
#account
#password
pass                personaloauthauthorisationtoken
admins              mainaccount
homeChannels        #mainaccount,#botaccount
#guestChannels

[IRCServer]
address             irc.chat.twitch.tv
port                6697

The Twitch SSL port is 6697 (or 443). For non-encrypted traffic, use the default port 6667.

Streamer assistant bot

Please make the bot a moderator to prevent its messages from being as aggressively rate-limited.

Song requests

To get song requests to work, you need to register an application to interface with Google (YouTube) and/or Spotify servers. To initiate the guides for this, pass --set twitch.googleKeygen for YouTube and --set twitch.spotifyKeygen for Spotify, then simply follow the on-screen instructions. (They behave much like --set twitch.keygen.)

Certain commands require higher permissions

Some functionality, such as setting the channel title or currently played game, require credentials with the permissions of the channel owner. As such, if you want to use such commands you will need to generate OAuth access tokens for the main account separately, much as you generated some for the bot account. This will request keys from Twitch with more permissions, and the authorisation screen should reflect this.

$ kameloso --set twitch.superKeygen

Note: Mind that you need to be logged in as your main account while doing this, or the tokens generated will be ones for the wrong channel.

Example use

Note: dot "." and slash "/" prefixes will not work on Twitch.

kameloso joined #streamer123

        <Bob> !uptime
   <kameloso> Streamer123 has been live for 32 minutes and 13 seconds, with 27 viewers. (Maximum at any one time has so far been 45 viewers.)

<Streamer123> !oneliner new
   <kameloso> Usage: !oneliner new [trigger] [type] [text...]
<Streamer123> !oneliner new info random
   <kameloso> Oneliner !info created! Use !oneliner add to add lines.
<Streamer123> !oneliner add info @$nickname: for more information just use Google
   <kameloso> Oneliner line added.
<Streamer123> !oneliner add info @$nickname: for more information just use Bing
   <kameloso> Oneliner line added.
<Streamer123> !oneliner new vods ordered
   <kameloso> Oneliner !vods created! Use !oneliner add to add lines.
<Streamer123> !oneliner add vods See https://twitch.tv/zorael/videos for $streamer's on-demand videos (stored temporarily)
   <kameloso> Oneliner line added.
<Streamer123> !oneliner new source ordered
   <kameloso> Oneliner !source created! Use !oneliner add to add lines.
<Streamer123> !oneliner add source I am $bot. Peruse my source at https://github.com/zorael/kameloso
   <kameloso> Oneliner line added.
<Streamer123> !info
   <kameloso> @Streamer123: for more information just use Google
<Streamer123> !info
   <kameloso> @Streamer123: for more information just use Bing
<Streamer123> !vods
   <kameloso> See https://twitch.tv/zorael/videos for Channel's on-demand videos (stored temporarily)
<Streamer123> !commands
   <kameloso> Available commands: !info, !vods, !source
<Streamer123> !oneliner del vods
   <kameloso> Oneliner !vods removed.

(...assuming the Votes plugin is enabled and a prefix of '!'...)
<Streamer123> !poll 60 snik snek
   <kameloso> Voting commenced! Please place your vote for one of: snik, snek (60 seconds)
        <Bob> snik
      <Alice> snek
        <Eve> snek
   <kameloso> Voting complete, results:
   <kameloso> snik : 1 vote (33.3%)
   <kameloso> snek : 2 votes (66.6%)

<Streamer123> !timer new
   <kameloso> Usage: !timer new [name] [type] [condition] [message threshold] [time threshold] [stagger message count] [stagger time]
<Streamer123> !timer new mytimer sequential both 100 600 0 0
   <kameloso> New timer added. Use !timer add to add lines.
<Streamer123> !timer add mytimer This is an announcement on a timer
   <kameloso> Line added to timer mytimer.
<Streamer123> !timer add mytimer It is sent after 100 messages have been seen and 600 seconds have passed
   <kameloso> Line added to timer mytimer.
(...time passes, messages get sent...)
   <kameloso> This is an announcement on a timer
(...time passes, messages get sent...)
   <kameloso> It is sent after 100 messages have been seen and 600 seconds have passed

<Streamer123> !counter add deaths
   <kameloso> Counter deaths added! Access it with !deaths.
<Streamer123> !deaths+
   <kameloso> deaths +1! Current count: 1
<Streamer123> !deaths+
   <kameloso> deaths +1! Current count: 2
<Streamer123> !deaths
   <kameloso> Current deaths count: 2
<Streamer123> !deaths=0
   <kameloso> deaths count assigned to 0!

        <Bob> !followage
   <kameloso> You have been a follower for 3 years, 4 months and 2 days, since September 2019.
        <Bob> !followage mopiim
   <kameloso> mopiim has been a follower for 7 years, 10 months, 1 week and 4 days, since March 2015.

      <Alice> !so rayyousay
   <kameloso> Shoutout to RayYouSay! Visit them at https://twitch.tv/rayyousay! (last seen streaming Final Fantasy XIV: A Realm Reborn)

<Streamer123> !stopwatch start
   <kameloso> Stopwatch started!
<Streamer123> !stopwatch
   <kameloso> Elapsed time: 18 minutes and 42 seconds
<Streamer123> !stopwatch stop
   <kameloso> Stopwatch stopped after 48 minutes and 10 seconds.

      <blorp> !watchtime
   <kameloso> You have been a viewer for a total of 23 hours and 7 minutes.
      <blorp> !watchtime blarp
   <kameloso> Blarp has been a viewer for a total of 1 hour and 24 minutes.
      <blorp> !watchtime blerp
   <kameloso> BLERP has not been watching this channel's streams.

  <Hirrsteff> !ecount FrankerZ
   <kameloso> FrankerZ has been used 127 times!
  <Hirrsteff> !ecount :D
   <kameloso> :D has been used 24 times!

   <asdfhjkl> !poof

    <meanie1> oh yeah that character dies
    <meanie2> lol they dont know he dies
  <bystander> wait what?
    <meanie3> HE DIES
<friendlyMod> !nuke dies

(...retroactively becomes...)
    <meanie1> <message deleted>
    <meanie2> <message deleted>
  <bystander> wait what?
    <meanie3> <message deleted>
<friendlyMod> <message deleted>

(...assuming YouTube song requests enabled...)
     <zorael> !songrequest https://www.youtube.com/watch?v=D6os0Upx5A0
   <kameloso> Disasterpiece - Titan added to playlist.

(...assuming Spotify song requests enabled...)
        <ray> !songrequest https://open.spotify.com/track/2pbQx0tRnUPR5BM3NOJhck?si=845f495252e2481e
   <kameloso> Disasterpiece - Titan added to playlist.

    <someMod> !settitle First playthrough, no backseaters
    <someMod> !setgame Elden Ring
    <someMod> !commercial 30

      <shmoe> !time
   <kameloso> The time is currently 16:34 for Streamer123.
     <shmuck> !time London
   <kameloso> The time is currently 15:34 in London.

Feedback and ideas welcome.

Limitations and caveats

kameloso remains an IRC bot, but most features will work on Twitch, as its chat is IRC-like. The Automode plugin is an exception (as modes are not really applicable on Twitch), and it will auto-disable itself appropriately.

That said, in many ways Twitch chat does not behave as a normal IRC server. Most common IRC commands go unrecognised. Joins and parts are not always advertised. You can also only join channels for which a corresponding Twitch user account exists.

See this Twitch help page on moderation and this page on harassment for available moderator commands to send as normal channel PRIVMSG messages.

Certain events are not advertised over IRC and instead require webhooks to detect. These sadly include follows, and as such the bot is not able to detect those in real-time.

Webhooks require running a local HTTP server and some way of receiving traffic to it through a firewall. It is arguably out of scope for a generic IRC bot like kameloso. Contributions are certainly welcome and will likely be accepted, but without such it remains low priority.

Clone this wiki locally