====== Streamlabs Chatbot ======

**2022 Update**

This is a long overdue update, but I have noticed that this guide still gets quite a bit of traffic, and the majority of the commands posted here are still getting copy/pasted elsewhere. While I think that's great, I felt like I should offer an update regarding the current status of my own personal usage of SLCB. Without diving too much into the drama of things, Streamlabs made some poor decisions in their development process of their fork of OBS, Streamlabs OBS, that came to light last year. If you're unfamiliar with what occurred, [[https://twitter.com/OBSProject/status/1460782968633499651|this Twitter thread]] by the OBS team will explain the TLDR. It is important to note that the OBS devs have since stated that they are now currently on good terms with the Streamlabs team. However, for someone such as myself who literally makes a living off of contributing and developing for open-source communities, I made my own personal decision to find an alternative bot to replace SLCB. I am in no way suggesting users to migrate from Streamlabs, and again, this decision was my own.

That said, the purpose of this update was to focus on two things: (1) I will obviously not be updating this guide in the future, and (2) the commands here still work, but there are simply better ways to achieve what these commands give by using more modern commands/bots.

If you are interested in alternatives to Streamlabs, I believe the most user-friendly would be [[https://streamelements.com/|StreamElements]]. And for a slightly less user-friendly experience but powerful option, there is the bot I currently use, [[https://streamer.bot/|Streamer.bot]].

==== About ====

Streamlabs Chatbot (SLCB), formerly known as AnkhBot, is a self-hosted bot solution developed by [[https://twitter.com/ankhheart|AnkhHeart]] for Twitch streamers with a number of unique features, as well as now officially integrates with [[https://www.streamlabs.com/|Streamlabs]] and its exclusive services. Not to mention the software and all of its features are completely free.

There's numerous resources for learning how to utilize the bot to its fullest potential, but this documentation is an attempt at an all in one, quick and simple source for getting started and beyond. It's also important to note that a lot of these commands use an external API, coded and provided by the user [[https://decapi.me/|Decicus]] that would otherwise be impossible to do with the bot alone.

If there's one thing I can't recommend more, it's to join their [[https://discordapp.com/invite/J4QMG5m|Discord server]]. You can find support there, as well as community made addons for the bot.
==== Resources ====

  * [[https://streamlabs.com/chatbot|Official Site]]
  * [[https://cdn.streamlabs.com/chatbot/Documentation.pdf|Documentation]]
  * [[https://support.streamlabs.com/hc/en-us/articles/115003848733-Streamlabs-Chatbot-FAQ|Frequently Asked Questions]]
  * [[https://streamlabs.com/chatbot-changelog|Changelog]]
  * [[https://discordapp.com/invite/J4QMG5m|Discord Support Server]]
  * [[https://twitter.com/StreamlabsHQ|Streamlabs Twitter]]
  * [[https://docs.decapi.me/#/twitch|Decicus' Twitch API Documentation]]

----

==== Quickstart Commands ====

These are the most common commands that you see in other streamer's channels, and they are **100% copy and paste friendly**.

<panel id="stats" type="primary" title="Stats">
This retrieves and displays all information relative to the stream, including the game title, the status, the uptime, and the amount of current viewers.

<code>
Command: !stats  
Response: Game: $mygame | Title: $mystatus | Uptime: $uptime | Viewers: $readapi(https://api.crunchprank.net/twitch/viewercount/$mychannel)  
</code>
</panel>

<panel type="primary" title="Uptime">
This returns the duration of time that the stream has been live. If the stream is not live, it will return OFFLINE.

<code>
Command: !uptime  
Response: $mychannel has been live for $uptime.    
</code>
</panel>

<panel type="primary" title="Time">
This returns the local time for the streamer.

<code>
Command: !time  
Response: The time is currently $time for $mychannel.      
</code>
</panel>

<panel type="primary" title="Date">
This returns the date for the streamer.

<code>
Command: !date  
Response: The date is currently $date for $mychannel.  
</code>
</panel>

<panel type="primary" title="Top 5 Points">
This lists the top 5 users who have the most points/currency.

<code>
Command: !top5points  
Response: The top 5 users based on points: $toppoints(5)  
</code>
</panel>

<panel type="primary" title="Top 5 Hours">
This lists the top 5 users who have spent the most time, based on hours, in the stream.

<code>
Command: !top5time  
Response: The top 5 users based on hours: $tophours(5)  
</code>
</panel>

<panel type="primary" title="Follower Count">
This returns a numerical value representing how many followers you currently have.

<code>
Command: !followers  
Response: $mychannel currently has $readapi(https://api.crunchprank.net/twitch/followcount/$mychannel) followers.  
</code>
</panel>

<panel type="primary" title="Follow Date">
This returns the date and time of which the user of the command followed your channel.

<code>
Command: !followed  
Response: $tousername, you followed $mychannel on $readapi(https://api.crunchprank.net/twitch/followed/$mychannel/$touserid).  
</code>
</panel>

<panel type="primary" title="Follow Length">
This returns the "time ago" that the user of the command followed your channel.

<code>
Command: !following  
Response: $tousername, you have been following $mychannel for $readapi(https://api.crunchprank.net/twitch/followage/$mychannel/$touserid?precision=3).  
</code>
</panel>

<panel type="primary" title="Account Creation">
This returns the date and time of when a specified Twitch account was created.

<code>
Command: !created  
Response: The account for $tousername was created on $readapi(https://api.crunchprank.net/twitch/creation/$touserid).  
Example: !created crunchprank  
</code>
</panel>

<panel type="primary" title="Recent 3 Followers">
This grabs the last 3 users that followed your channel and displays them in chat.

<code>
Command: !recentfollowers  
Response: Welcome to our 3 most recent followers: $readapi(https://api.crunchprank.net/twitch/followers/$mychannel?count=3&direction=desc)!    
</code>
</panel>

<panel type="primary" title="Retweet">
This displays your latest tweet in your chat and requests users to retweet it. This only works if your Twitch name and Twitter name are the same.

<code>
Command: !retweet  
Response: Please retweet my recent tweet! $readapi(https://api.crunchprank.net/twitter/latest/$mychannel?no_rts&url)  
</code>
</panel>

<panel type="primary" title="Shoutout">
This provides an easy way to give a shout out to a specified target by providing a link to their channel in your chat.

<code>
Command: !shoutout  
Response: Please go check out $targetname at $url - I love them and you should too!  
Example: !shoutout crunchprank  
</code>
</panel>

<panel type="primary" title="Hosting">
This returns all channels that are currently hosting your channel (if you're a large streamer, use with caution).

<code>
Command: !hosting  
Response: Thanks to all the users currently hosting: $readapi(https://api.crunchprank.net/twitch/hosts/$mychannel?implode).  
</code>
</panel>

<panel type="primary" title="Current and Next Song With Details">
These commands show the song information, direct link, and requester of both the current song and the next queued song. For users using YouTube for song requests only.

<code>
Command: !song  
Response: Current song: $currentsong - https://www.youtube.com/watch?v=$readapi(https://api.crunchprank.net/youtube/videoid?search=$currentsong) Requested by: $requestedby

Example: !nextsong  
Response: Next song: $nextsong - https://www.youtube.com/watch?v=$readapi(https://api.crunchprank.net/youtube/videoid?search=$nextsong) Requested by: $nextrequestedby  
</code>
</panel>

<panel type="primary" title="BTTV Emotes">
This lists all BTTV emotes for your channel.

<code>
Command: !bttv  
Response: Check out all the BTTV emotes for $mychannel! $readapi(https://api.crunchprank.net/bttv/emotes?channel=$mychannel)  
</code>
</panel>

<panel type="primary" title="Give Points">
This allows one user to give a specified currency amount to another user.

<code>
Command: !give
Response: $givepoints("$userid","$targetid","$num2","$username gave $value $currencyname to $targetname","fail","false")
Example: !give woahh_jess 5
Explanation: 5 points are removed from user of the command and given to woahh_jess  
</code>
</panel>

<panel type="primary" title="Give Points To Everyone">
This gives a specified amount of points to all users currently in chat.

<code>
!points add +viewers <amount>
</code>
</panel>

----

==== Twitch API Commands ====

The following commands take use of AnkhBot's ''$readapi'' function. Basically it echoes the text of any API query to Twitch chat. Some of these commands have optional parameters that can help you customize your query results which I have noted for each command - be sure to play around with those.

<panel type="primary" title="Follow Age">
  * **Description**: Gets the time difference (also known as the "follow age" or "time ago") between when a user followed a channel.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitch/followage/CHANNEL/FOLLOWER)</code>
  * **Optional Parameters**:
    * ''precision'': How precise the timestamp should be in terms of years, months, weeks, days, hours, minutes & seconds (default: 2).
  * **Example Responses**: <code>$user has been following the channel for $readapi(https://api.crunchprank.net/twitch/followage/crunchprank/$user?precision=3).</code>
  * **Example Output**: ''yourfrienddustin has been following the channel for 1 month, 3 days, 19 hours.''
</panel>

<panel type="primary" title="Follow Time">
  * **Description**: Retrieves the date and time of when the user followed the channel.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitch/followed/CHANNEL/FOLLOWER).</code>
  * **Optional Parameters**:
    * ''tz'' - By default this query will output the result in UTC. However if you'd like to change the time zone, you can specify using the PHP list of all available time zones, check [[https://secure.php.net/manual/en/timezones.php|here]].
  * **Example Responses**: <code>$user started following on $readapi(https://api.crunchprank.net/twitch/followed/crunchprank/$user?tz=America/New_York).</code>
  * **Example Output(s)**: ''yourfrienddustin started following on Jun 07. 2016 - 05:57:21 PM (America/New_York).''
</panel>

<panel type="primary" title="Followers">
  * **Description**: Retrieves the followers of a specified channel using a variety of optional parameters for customization.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitch/followers/CHANNEL)</code>
  * **Optional Parameters**:
    * ''count'' - How many followers to get with the request (default: 1 | max: 100).
    * ''offset'' - How many followers to offset from the beginning of the object.
    * ''direction'' - What direction to retrieve followers in. Can either be 'asc' (oldest) or 'desc' (most recent). The default is 'desc'.
    * ''num'' - Prefixes each follower with a number.
  * **Example Responses**: <code>Everyone welcome our 3 most recent followers: $readapi(https://api.crunchprank.net/twitch/followers/crunchprank?count=3&direction=desc).</code>
  * **Example Output(s)**: ''Everyone welcome our 3 most recent followers: woahh_jess, z0mbyte, yourfrienddustin.''
</panel>

<panel type="primary" title="Account Creation">
  * **Description**: Retrieves the creation date and time of a user.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitch/creation/USER).</code>
  * **Optional Parameters**:
    * ''tz'' - By default this query will output the result in UTC. However if you'd like to change the time zone, you can specify using the PHP list of all available time zones, check [[https://secure.php.net/manual/en/timezones.php|here]].
  * **Example Responses**: <code>The account for $user was created on $readapi(https://api.crunchprank.net/twitch/creation/$user?tz=America/New_York).</code>
  * **Example Output(s)**: ''The account for crunchprank was created on Dec 26. 2013 - 09:31:06 PM (America/New_York).''
</panel>

<panel type="primary" title="Account Age">
  * **Description**: Retrieves the age of an account.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitch/accountage/USER).</code>
  * **Optional Parameters**:
    * ''precision'' - How precise the timestamp should be in terms of years, months, weeks, days, hours, minutes & seconds (default: 2).
  * **Example Responses**: <code>The account for $user was created $readapi(https://api.crunchprank.net/twitch/accountage/$user) ago.</code>
  * **Example Output(s)**: ''The account for crunchprank was created 3 years, 4 months ago.''
</panel>

<panel type="primary" title="Latest Highlights">
  * **Description**: Retrieves the latest highlight of the specified channel.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitch/highlight/CHANNEL).</code>
  * **Example Output**: ''"Hunter" LuL - %%https://www.twitch.tv/videos/231566911%%''
</panel>

<panel type="primary" title="Latest Upload">
  * **Description**: Returns the latest uploaded video for the specified channel.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitch/upload/CHANNEL)</code>
  * **Example Output(s)**: ''Evil @ Twitchcon 2017 - %%https://www.twitch.tv/videos/182630172%%''
</panel>

<panel type="primary" title="Host List">
  * **Description**: Returns a list of channel names hosting the specified channel.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitch/hosts/CHANNEL)</code>
  * **Optional Parameters**:
    * ''display_name'' - If specified, this will use the display names instead of the usernames of the users that are hosting.
    * ''list'' - If specified, the list will be in plaintext (using newlines) instead of in a JSON object.
    * ''implode'' - If specified, the list will be returned comma-separated (", ") instead of JSON/a "newlined" list.
  * **Example Responses**: <code>Thanks to all the users currently hosting: $readapi(https://api.crunchprank.net/twitch/hosts/crunchprank?implode).</code>
  * **Example Output(s)**: ''Thanks to all the users currently hosting: woahh_jess, yourfrienddustin, z0mbyte.''
</panel>

<panel type="primary" title="Subscriber Emotes">
  * **Description**: Retrieves the subscriber emotes for the specified channels and lists them.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitch/subscriber_emotes/CHANNEL)</code>
  * **Example Output(s)**: ''bobrossDealWithIt bobrossGold bobrossGG bobrossPal bobrossCanvasH bobrossBeli bobrossEve bobrossBush bobrossKappaR...''
</panel>

<panel type="primary" title="Team Member List">
  * **Description**: Retrieves the members of a specified team.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitch/team_members/TEAM)</code>
  * **Optional Parameters**:
    * ''sort'' - If this is specified, it will sort the members of the team alphabetically.
    * ''implode'' - If this is specified, the list will be returned in plaintext compared to a JSON array (use a ''+'' for space).
  * **Example Responses**: <code>Make sure to check out all the members of the Next Level team: $readapi(https://api.crunchprank.net/twitch/team_members/nextlevel?implode=,+).</code>
  * **Example Output(s)**: ''Make sure to check out all the members of the Next Level team: 360chrism, fuzzyness, nospimi99, redfalcongames, chrescendo, vespher, raysfire, theno1alex.''
</panel>

----

==== Miscellaneous Commands ====

<panel type="primary" title="Multi Stream Command">
  * **Description**: Allows a user to generate a multi-stream link.
  * **Response**: <code>http://multitwitch.tv/CHANNEL/$targetid</code>
  * **Usage**: If you have this response set to the command ''!multi'', then a user would type ''!multi user1/user2/user3'' etc which would generate a link like: ''%%http://multitwitch.tv/CHANNEL/user1/user2/user3%%''.
</panel>

----

==== Other Service API Commands ====

The following commands take use of AnkhBot's ''$readapi'' function the same way as above, however these are for other services than Twitch.

<panel type="primary" title="Twitter - Latest Tweet">
  * **Description**: Returns the latest tweet by the specified user.
  * **Response**: <code>$readapi(https://api.crunchprank.net/twitter/latest/USERNAME)</code>
  * **Optional Parameters**: 
    * ''no_rts'' - If specified, retweets will not be included.
    * ''include_replies'' - FIXME <del>If specified at all, this includes replies from the specified user to other users as well.</del>
    * ''no_exclude_replies'' - Works similarly to include replies, except this query string cannot be specified as just empty unlike include replies.
    * ''search'' - Goes through each of the latest tweets (up to 200) and then searches with the specified string (case-insensitive). If this is not specified, it will just return the latest tweet.
    * ''strict'' - This is used together with search. If specified, it will do a case-sensitive search.
    * ''url'' - If specified, the URL of the tweet will be appended to the result.
    * ''shorten'' - Used together with url. Shortens the URL using TinyURL.
    * ''howlong'' - Includes the time since the tweet was posted.
  * **Example Responses**: <code>Retweet my latest tweet: $readapi(https://api.crunchprank.net/twitter/latest/crunchprank?url).</code> 
  * **Example Output(s)**: ''yesterday i ate captain crunch, salt and vinegar chips, and pizza. today the roof of my mouth is non-existent. - %%https://twitter.com/crunchprank/status/821484732324188161%%''
</panel>

<panel type="primary" title="YouTube - Video ID">
  * **Description**: Searches the YouTube API with the specified string and returns the first result it can find.
  * **Response**: <code>$readapi(https://api.crunchprank.net/youtube/videoid?search=TERM)</code>
  * **Optional Parameters**:
    * ''show_url'' - Prepends ''%%https://youtu.be/%%'' before the video ID to make it a proper URL.
  * **Example Output(s)**: ''7rs6HuJj4TE''
</panel>

<panel type="primary" title="YouTube - Latest Video">
  * **Description**: Retrieves the latest video uploaded to the specified channel and returns the title and URL for it.
  * **Response**: <code>$readapi(https://api.crunchprank.net/youtube/latest_video?user=USER) or $readapi(https://api.crunchprank.net/youtube/latest_video?id=USERID)</code>
  * **Optional Parameters**:
    * ''user'' - For users with usernames in their URL.
    * ''id'' - For users with an ID number in their URL.
    * ''skip'' - Skips the specified amount of uploads (default: 0, maximum: 50).
  * **Example Responses**: <code>Check out my latest YouTube video: $readapi(https://api.crunchprank.net/youtube/latest_video?user=devinsupertramp).</code>
  * **Example Output(s)**: ''DevinSuperTramp BIGGEST FAILS 2.0! - %%https://youtu.be/rW_NzxoNK1Y%%''
</panel>

<panel type="primary" title="Urban Dictionary">
  * **Description**: Finds the first returned definition of a specified word from Urban Dictionary.
  * **Response**: <code>$msg: $readapi(http://jwd.me/twitch/api/urban-dictionary.php?q=$msg)</code>
  * **Usage**: If you have this response set to the command !urban, then a user would just type ''!urban word'' to get the Urban Dictionary's definition of that word.
</panel>

----

==== Game Specific Commands ====

The following commands are to be used for specific games to retrieve information such as player statistics.

<panel type="primary" title="Overwatch">
  * **Description**: Yes this is quite a block of text, but read it thoroughly as the overall concept is rather easy to understand. This allows users to issue commands to check various Overwatch stats of an Overwatch player and comes in two flavors for you to pick from. The first Response is for a command that checks a user-inputted Overwatch player. While this allows your viewers to check any Overwatch player on any platform, it makes it so the command can be longer for the user to type, as well as has a chance to become a source of chat spam if too many people are using it. The second Response is for a command that checks a defined Overwatch player, and what I personally recommend. This allows you to use a shorter command to check the stats, and also limits the usage so that any Overwatch player isn't able to be looked up - just you (or whoever you define). Credit to [[https://twitter.com/gerhardoh|xgerhard]] for creating the API. You can find an entire list of the various stats you're able to look up [[https://2g.be/twitch/Overwatch/|here]], and further general documentation [[https://community.nightdev.com/t/how-to-retrieve-overwatch-stats-through-nightbot/8148|here]]. **Important to note**, that if you're playing on PC and not in the NA/US region, you will need to explicitly give the region. 

----

  * **First Response**: <code>$readapi(https://2g.be/twitch/Overwatch/command/action=$target&bot=ankhbot&user=$username&console=$target3&channel=$mychannel&defaultconsole=pc&gamertag=$target2)</code>
  * **Usage**: This response **is copy/paste friendly**. The user interacts via commands such as ''!overwatch action username platform''. So for example if I wanted to check my Kill/Death ratio and I play Overwatch on PC, I would issue ''!overwatch kda crunchprank-1234 pc''. If I wanted to check the same thing, but my account was in Europe, I would need to type ''!overwatch kda crunchprank-1234-eu pc''. If I played on a console such as PS4, then there's no need for a Battletag or region and would look something like this ''!overwatch kda crunhprank ps''. 

----

  * **Second Response**: <code>$readapi(https://2g.be/twitch/Overwatch/command/action=$target&format=twitch&user=$username&bot=ankhbot&console=XX&channel=$mychannel&gamertag=USERNAME-XXXX&hideBnetID)</code>
  * **Usage**: This command **is not copy/paste friendly** but my suggested method. It requires you to make two adjustments so that it knows what user name to look up by default. So in the above response example, the parts that say ''console=XX'' and ''gamertag=USERNAME-XXXX'' will need to be changed to whatever Overwatch player you want the command to check by default for and what platform they are playing on. So if I wanted to only allow viewers to check the PC stats for ''woahh_jess'', I would make sure that those parts were changed to ''console=pc'' and ''gamertag=woahh_jess-1234''. If woahh_jess' account was in Europe, then I would change the gamertag portion to ''gamertag=woahh_jess-1234-eu''. If for PS4, I would change them to ''console=ps'' and ''gamertag=woahh_jess''. Once you have set up the response correctly, all a user would need to do is type for example ''!overwatch time'' and that would return the "time played" for the player you specified in your response.
</panel>