Edit – 2017-06-23:

This hasn’t been updated with new custom APIs that I’ve added over time from feature requests and such. If you want an overview of what extra those might be, I suggest you take a look at the DecAPI documentation, even though it lacks good examples.


Over time I’ve written several “custom APIs” for certain things that I’d find useful to have in chat, to make it easier for myself and other chat moderators.

Some of these custom APIs are already documented on this blog such as the latest tweet, uptime or subscriber count.

Before moving on to covering all of the custom APIs, I will mention a few things beforehand:

  • In most cases, you will be able to utilize other “variables” that the bot supports.
  • For each custom API I will only provide the URL for it as well as a description of it. This URL has to be inserted in the specific bot’s respective variables.
    • You can find the variables below where you replace CUSTOM_API_URL_HERE with the URL of the custom API you wish to use.
      • For Nightbot:
        • $(urlfetch CUSTOM_API_URL_HERE)
      • For Ankhbot:
        • $readapi(CUSTOM_API_URL_HERE)
      • For Deepbot:
        • @customapi@[CUSTOM_API_URL_HERE]
    • If your bot isn’t listed here it’s still possible it has the ability to utilize these custom APIs. Please refer to your bot’s own documentation for information regarding this.
  • Example/placeholder parameters will be surrounded by ‘curly brackets’, for example {CHANNEL}.
    • Do not include these in the actual URLs. Example: {CHANNEL} = decicus.
  • Optional parameters will be covered per custom API, if there are any.
  • Some of these custom APIs may be marked as “beta” and may change at any time (this is written in the notes about the endpoints).


  • https://decapi.me/twitch/help/{SEARCH}
    • Description: Retrieves a Twitch help article based on the specified search.
    • Optional parameters:
      • list – Returns a list of available help articles, with the title of each article (cannot be used in chat due to length).
    • Notes:
      • If {SEARCH} is list, it will provide a link to the list of help articles (with titles).
      • This generally requires another variable to accept user input, such as Nightbot’s $(querystring)or Ankhbot’s $msg.
        • Other bots may have something similar. Please refer to their documentation for further information.
      • It’s currently in “beta”, which means it might need some tweaks. Please contact me if you have any suggestions or reports.
    • Example:
  • https://decapi.me/twitch/followage/_CHANNEL_/_USER_
    • Description: Checks the specified user’s “follow age” (how long it has been since the user followed the channel).
    • Optional parameters:
      • precision – How precise the calculation of the “follow age” is. Defaults to 2.
        • While there is technically no limit on the precision, this will not require anything higher than “7” as the precision is calculated in this order:
          • years, months, weeks, days, hours, minutes, seconds
    • Notes:
      • This custom API is currently in “beta” and may change at any time.
      • This calculates the time between the last time the user followed and now, if the user has been following for a while, then unfollows and refollows, it will be reset.
    • Example:


  • https://decapi.me/twitter/latest?name={USERNAME}
    • Description: Gets the latest tweet of a specified user.
    • Optional parameters:
      • no_rts – Ignores retweets and gets the latest normal tweet.
      • url – Appends the direct URL of the tweet. Looks like this: This is a tweet - TWEET_URL_HERE
      • howlong – Appends how long it has been since the tweet was tweeted out. Looks like this: This is a tweet - 12 hours, 4 minutes ago
    • Notes: Your tweets have to be open to the public for this to work.
    • Example: https://decapi.me/twitter/latest?name=Decicus&no_rts&howlong&url



  • https://decapi.me/steam/hours?id={STEAM64}&appid={APP_ID}
    • Description: Gets the amount of hours of a game (APP_ID) for the specified Steam ID.
    • Notes:
      • If the custom API doesn’t work, then you either have to put your Steam profile to public or use your own Steam API key (check “Optional parameters” for this method).
      • Your Steam64 ID can be found using several tools, such as steamid.co.
      • The app ID is the ID of the Steam game. This is relatively easy to find in the store page URL. For example, the Steam store page URL for Counter-Strike: Global Offensive is http://store.steampowered.com/app/730/ where the number “730” is the app ID.
    • Optional parameters:
      • round – The number of decimals to round the number of hours down to. Defaults to 2.
      • key – Only recommended if you need to keep your Steam profile set to private.
        • This parameter needs to be the account owner’s Steam API key for it to have an effect.
        • You can sign up and get your Steam API key here: https://steamcommunity.com/dev/apikey
        • If you decide to use this, please make sure to not add your command directly through chat as exposing your API key to the public is not recommended!
    • Example: https://decapi.me/steam/hours?id=76561197997719567&appid=730&round=1 (My profile – Game: Counter-Strike: Global Offensive – 1 decimal)
  • https://decapi.me/br/player/_ID_
    • Description: Retrieves player information about the specified player from the Battle Royale leaderboards, where {ID} is either your STEAM64 ID or your unique ID from Battle Royale.
    • Notes:
      • By default, this will retrieve from the regular ranked games. If you want hardcore, add /hardcore at the end of the URL.
        • Please keep in mind that if you add /hardcore to the URL, all options parameters must come after the /hardcore part.
      • Alternatively, you can add /regular at the end of the URL, but since the default falls back to regular anyways, this is generally.
      • This custom API is in beta and may change at any time.
    • Optional parameters:
      • options – You can see what it retrieves by default by specifying default . You can specify list to see a list of available options.
        • Remember to comma-separate all options you wish to use.
      • separator – By default, this is the | (pipe) character. A space will be added before and after the separator, between each value.
    • Example:

End notes:

Congratulations! You reached the end of my post. Hopefully you’ll find some use out of these “custom APIs”.

If you have any questions or other concerns, please feel free to contact me.

If you would like to support me in any way (buying me a coffee/supporting server costs) then you can do so via this Streamtip link.

Thanks for reading!

Custom APIs for Bots (Nightbot/Ankhbot/Deepbot)
Tagged on:                             
  • Kitty Love1975

    Thanks for this! I found the info very clear and easy to use.

    I was wondering if you know of a readapi weather command I could use for ankhbot?
    Thank you for your time!

    Best Regards, Kitty

    • Hey there.

      Happy you’ve found some use for these.
      Sadly, I do not know of anything like that at the moment, but there’s a possibility I write something like that in the future and update this post with it.

  • LordDarkness

    Hi, that is really amazing bro, thanks ^^. Can u bring us some request to get time like http://www.timeapi.org/ but it seems like doesn’t work with the readapi from anhkbot. Maybe a more simple one, but anhkbot only has to get the time, but not the date, and i want to make a log with some commands. Thanks i appreciate a lot your work.

  • Pingback: Subscriber Count (Twitch) – Alex Thomassen()

  • Eyeofthenyte

    Awesome work here! Absolutely great I’ve been able to point people here for some of their bot needs.
    I was wondering how hard it would be to write something that would make the ankhbot run another command a certain number of times based on a $randnum() output?

    • Thanks!

      I’m not sure if that’s even possible with Ankhbot, to be quite honest, so honestly I have no idea.

  • Tom

    Looking for an API that allows for a total follow count so I can see in chat how many followers I have since Twitch tends to not update in my browser very often

    • I don’t have that as of right now, I’ll see if I can find time to implement that some time during the week, and let you know via email.

      • Tom

        Thanks for the email! I appreciate your work! Going to set this up before the stream tonight.

  • You can actually set currency command like this:


    If you add targets instead of EUR and USD for example then you can use this command with multiple currencies.

    For example: !convert eur usd 10 or !convert gbp aud 10


    • I didn’t actually know that Ankhbot supported numbering your $targets. Thanks for the tip :D

  • XKPlayzYT

    Is it possible you can add custom apis for a time length thing for like it displays the month it is for that person’s resub? And mind adding a custom api for bits which is a new twitch feature added? I would like for it to give points to the person for example for each 1 bit given it will give 1 point to that specific user. Also lastly, if it is possible to have customapis for gamewisp and patreon.

    • Is it possible you can add custom apis for a time length thing for like it displays the month it is for that person’s resub?

      I can, but it won’t be accurate. The subscriptions API doesn’t provide the proper value for anniversary months, only when the subscription was last updated/created. So in the case someone resubs 3 days after it expires, which is inside the 30-day grace period and they keep their anniversary, it would show the length of time between the last “resub date” and not the anniversary length. It would make a lot of the results inaccurate, so I don’t see any point in adding anything that supports that.

      And mind adding a custom api for bits which is a new twitch feature added? I would like for it to give points to the person for example for each 1 bit given it will give 1 point to that specific user.

      That’s not possible with just a custom API. You’d need a bot to “listen” to the “bit events” in chat, and then give points accordingly. I don’t personally know of any bot that supports this.

      Also lastly, if it is possible to have customapis for gamewisp and patreon.

      I don’t have any experience with the GameWisp or Patreon APIs, but if you provide anything specific idea, I can see if it’s possible.

      • Bramzee

        Hello. I am currently using the decapi.me/twitch/followers.php?channel={USERNAME} page for my bot to update the followers. And I was curious about gamewisp, so I searched around until I finally came upon something that had to do with gamewisp. This page -> https://gamewisp.readme.io/docs/getting-started <- has helped a bit, but if it would be possible to somehow have the customapi to show the most recent subscriber (and if possible the tier they subbed to, not a huge deal if that's not possible… I know it's not exactly simple) that would be awesome!

        • Hey, I’ve already mentioned in a reply to a previous comment that I was going to implement something like this, actually. I just haven’t gotten around to it, mainly due to lack of time (and interest), since I don’t really use GameWisp myself.

          Thanks for the link though.

          • Bramzee

            Alright. Appreciate the reply. Have you had any thoughts of adding anything for Revlo?

          • Not really, that hasn’t been requested yet, but because of this comment I decided to add it to my TODO-list, so I might add something for it in the future.

  • Can you make this Nightbot command work with Ankhbot?


    • Not sure I can. The custom API seems to only support URL-encoded, which Nightbot supports through $(querystring), but Ankhbot doesn’t support.

  • XxBonf1r3xX

    Currency API is broken looks like, it used to work correctly but now it gives me an error message “Invalid return currency.”

    • XxBonf1r3xX

      And “Invalid base currency.”

      • XxBonf1r3xX

        Don’t worry, I fixed it.

        • I assume it was an issue with the command itself?

          • XxBonf1r3xx


  • TxAggs01

    Is there a way to make the follower API only return the current total number of followers?

  • WeR2MuchGame

    I was wondering if you were ever to get the API to show the follower count?

  • ExplicitProphet

    Is there a way to make a command so my viewers can use !sr followed by a url instead of !songs request?

    • Just make a command alias, no custom API needed:

      !commands add -a=!songs !sr request $(query)

      Then you just use the command like this:

      !sr https://youtu.be/ZyhrYis509A

      • ExplicitProphet

        For some reason with !commands add -a=!songs !sr request $(query) in the message field and !songs request in the Alias field I get an error about the url everytime I try and request a song. Any ideas?

        • Because the way I put it shows how to do it in chat. If you wanna add it through the Nightbot dashboard, you’d do this:

          • Message: request $(query)
          • Alias: !songs

          Like this:

          But it seems like the command !sr is already a “default alias” in Nightbot (not documented), so if you want to use that with Nightbot, you shouldn’t have to do anything other than enabling song requests.

          • ExplicitProphet

            Thank you, I just removed it and tried !sr and it worked. I feel dumb now haha

          • No problem!
            So do I, actually. I didn’t realize until I tested !sr to see if it worked in my channel, and then I got an error when I wanted to delete it (so that I could re-create it). Glad you got it working though :D

  • Sathroz

    Any chance you would write an API to get the latest subscriber from Gamewisp or other nice methods in relation to GW subscribers?

    • The possibility is there, but I don’t have any specific ETA on when or if I’m going to end up doing that. I don’t have any experience with the GameWisp API, so it’d have to be whenever I have time to sit down and dedicate a few hours messing around, testing and eventually implementing it.

      I’ll add this to my TODO list and see when I have time to take a look at it.
      Thanks for the suggestion!

  • Kathithetigress

    First of all, thanks for this epic work, second is it possible to make an API so Nightbot for example prints a Random Viewer That is currently Watching?

    • That shouldn’t be too difficult, but the only way to really do that is to get a list of users logged into chat and picking it from there, which doesn’t do any check in terms of chat activity.

    • I’ve added this now, but it hasn’t been documented in this blog post yet (with examples and such). If you’re a bit of an “advanced user”, you can take a look at the docs here: https://docs.decapi.me/#twitch_random_user_CHANNEL

  • Roxas

    Can you make a 24 hour timezone api?

    • Hey, I’m assuming you mean the /misc/time endpoint.
      This is already supported via the format parameter, but I’ve forgotten to document this.

      It follows the date formats that you can in PHP’s date() documentation.

      By default, the format is: h:i:s A T
      You probably want something like: H:i:s T (note the capital “H” and the lack of the “A”), which will give you “15:02:31 UTC” instead of “03:02:31 PM UTC”.

      • Roxas

        So how would i edit $readapi(https://decapi.me/misc/time/?timezone=Europe/Dublin) to format into a 24 hour time instead of the normal 12?

        • Sorry for the somewhat late reply, I thought I already did.

          Just edit the URL from: https://decapi.me/misc/time/?timezone=Europe/Dublin
          To: https://decapi.me/misc/time/?timezone=Europe/Dublin&format=H%3Ai%3As+T
          Which should make it look like this example: 15:02:31 UTC

  • This is a great article it has improved how professional my channel looks so much, doe the twitter api is there a way to link the current count of retweets?

    • Thanks for the kind words!

      Yes. This post is a tiny bit outdated. Everything in the post still works, but some of it has been updated and hasn’t been covered yet.

      Basically, you just have to this URL instead, and add the parameter retweets.
      Here’s an example: https://beta.decapi.me/twitter/latest?name=twitch&retweets.
      This also supports all the other parameters that are in this post, such as howlong, no_rts etc.

  • ireen

    Since today the custom api for the hours in a game doesnt work anymore. If i add the command to the chat and test it out i get: streamer has You need to specify a valid app ID! logged . i always make the command like this:!addcom !hours streamer has $(urlfetch https://decapi.me/steam/hours?id=the id64 from the streamers steam appid=433850).
    I hope you have some advise for how i fix it :)

    • Did you put an & between the ID64 and “appid”?

      Should look like: $(urlfetch https://decapi.me/steam/hours?id=STEAM_ID_HERE&appid=433850)

      • ireen

        Thanks! I edit the command so many times that i didnt see that i was missing the &. Thanks for the quick reply! Your costum api are so useful!

  • Helppy

    Hi, Alex! First of all, thank you so much, you did really great work on this. And I have the question. Is there any way to make uptime API return only two units (for example: minutes and seconds or hours and minutes) or only hours and minutes without seconds?

    • Hey Helppy.

      Sorry, but as of right now that’s not possible. I’ve added it to my TODO-list, but I haven’t really been able to work on it lately so I don’t have any ETA of when that may be implemented.

      • Helppy

        Ok, I got it. Thanks, mate, and good luck on your business!

        • I decided to do a quick implementation of the precision query parameter, which works basically the same as for followage. I’m not exactly sure if this is exactly what you requested, but it works for most cases anyways.

          Here’s a quick example:
          https://beta.decapi.me/twitch/uptime/monstercat?precision=4 – Default is 4, so this is the same as not including the parameter.
          https://beta.decapi.me/twitch/uptime/monstercat?precision=2 – Only shows the first two values. In this case “day” + “hours”.

          In regards to the last example: If you’ve only been streaming for say… 2 hours, it will say (for example): “2 hours, 40 minutes”
          Similarly, if you’ve streamed for less than 1 hour, it will say (for example): “34 minutes, 20 seconds”

          • Helppy

            Wow, cool! Great work, this is exactly what I wanted. Thank you so much, Alex and best regards!

  • KnezoCaixao

    I am pretty much new to streaming and ankhbot but i find this article very much helpfull. Awesome work :)
    I played a bit with commands and api and found the followcount api great: https://beta.decapi.me/twitch/followcount/{CHANNEL}
    Now i look for if its possible to do the same with viewers. So is there a way to show the viewercount also?

    I would like to have a timed chat message showing up including since when the stream started ($uptime), the follower count and the viewer count.

    Would be very thankfull for any help.

    • Hey, this isn’t properly documented, but you can use: https://beta.decapi.me/twitch/viewercount/monstercat
      Replace “monstercat” with your channel name, obviously.

      Keep in mind, it might be slightly inaccurate, due to caching and such. It only displays what the API says the viewercount is, so it might not be 100% accurate compared to what your dashboard says, for instance.

      • KnezoCaixao

        Thanks for the fast reply.
        Am i correct saying it will only show the viewers when the stream is live and say offline when the stream is off right?

        Will give it a try

        • Correct, as of right now it only says “CHANNEL_NAME is offline”.

          • KnezoCaixao

            Yeah works perfect.
            Thank you sooo much :)

  • Just wanted to say all of these things are absolutely fantastic, thanks for the work you’ve done!

    I’m partially here because rtainc.co has recently become very unstable and is now down for the most part so a lot of the functionality I had before is now gone.
    I was wondering if you had any plans to include some of the following for Twitch:
    > Latest Sub – Shows the name of the latest subscriber to {CHANNEL}
    > Sub Duration – Shows how long a {USER} has been subbed to {CHANNEL}
    > Sub List – Shows a comma separated list of all users currently subscribed to {CHANNEL}

    I’m working on alternative ways of fetching this data but as I’m not too savvy with authentication and whatnot I’ve often found myself relying on services like the one you’re providing.

    In any case, thanks for what you’ve provided so far! It’s allowed me to patch up some of the holes left by rtainc.co

    • > Latest Sub – Shows the name of the latest subscriber to {CHANNEL}

      There hasn’t been any demand for this, but I guess that’s because people already used rtainc’s API for that. I’ll add it to my TODO-list.

      > Sub Duration – Shows how long a {USER} has been subbed to {CHANNEL}

      I kinda just refuse to do this, mainly because the API doesn’t give me any accurate data.
      I’ve decided to add this to my TODO-list as well, but I still haven’t been able to find the time to actually implement it.

      The reason I say that is because the API gives you the day of when the subscription was started. This means that if someone had to cancel their sub for say, 2 weeks, and resubbed right after that, it would track it from that day and not take into account the grace period.
      Considering Twitch Prime subs instantly disables auto-renew when subscribing, this is a lot more common.

      > Sub List – Shows a comma separated list of all users currently subscribed to {CHANNEL}

      Had something like this in the past, but as with the first one, there wasn’t any demand because people were probably just using rtainc’s API for that.
      Note: There could be a small issue displaying all of those users in Twitch chat if that’s what you were thinking of using it for, due to it being limited to ~500 characters per message.
      I’ll add this to my TODO-list as well.

      Thanks for all the suggestions!

      • No prob!

        None of what I do involves posting to twitch chat thankfully, I mostly use it for onscreen banners and in the case of the sub duration it was mostly to show different animations during a sub shoutout for long-term supporters despite the inherent flaw you mentioned.

        I’ll keep an eye out all the same, thanks for the quick response!

  • Nikita Pereverzev

    ok. custom api for time that user has been following channel doesn`t seem to be functional, needs to be replaced probably

    • They all work fine on my end, but I’ve just updated some of the examples because they used some old Twitch usernames in the URL, which would break them.
      Can you give me an example of the one that doesn’t work, if it’s not related to that?

  • Jurgen

    12:57 Moderator 3-Month Subscriber Jurgen112112: !commands add !test $(touser) has been following Dianarrr for $(urlfetch https://beta.decapi.me/twitch/followage/dianarrr/ $(touser)?precision=7)
    12:57 Moderator Verified Nightbot: jurgen112112 -> The command “!test” has been added successfully.
    12:58 Moderator 3-Month Subscriber Jurgen112112: !test
    12:58 Moderator Verified Nightbot: jurgen112112 has been following Dianarrr for Remote Server Returned Code 404

    • Remove the space between https://beta.decapi.me/twitch/followage/dianarrr/ and $(touser)

      • Ethan

        Hi, I have this same problem but i can’t seem to remove the space. any thoughts?

        • I’m not sure I understand. Can you copy/paste the command you have right now?

  • Tair

    Hi. I’ve been using your followage for a month or so and it’s been great until recently when I noticed that if you do a followage of someone not following the channel, it returns with numbers instead of account names. Example: tairc has been following for: 140491972 is not following 47000447

    • Yes, this is something I’m aware of, just haven’t gotten around to fixing yet. It’s being tracked here: https://github.com/Decicus/DecAPI/issues/15

      • Tair

        I see. I wasn’t aware it was an old issue. I swear it worked fine a week or so ago. Is there an optional parameter I can use so that it just outputs “not following” for example?

  • Anarchy1980

    Hiya any chance of getting a total views API my mate streams and wants to get a whisper of the views on his channel, i have found followers one but the API’s change so much from different things and i can’t find one online :(

    • Hey.

      As of right now I don’t have an API for total views, but I’ve added it to my TODO-list. I haven’t been able to work on this TODO-list in a while, as I’ve been distracted with other things, so I don’t have an ETA.

      Also, whispering it might be tricky depending on the bot you use. Nightbot, for instance, won’t be able to do so, but Ankhbot should be fine.

    • Hi again,

      I added a “total views” API, since it was a pretty quick addition. You can find it here: https://beta.decapi.me/twitch/total_views/decicus
      Replace “decicus” with the channel name you want to use.

      • Anarchy1980

        Thank you so much :P

  • matute_las

    I am looking for a command which buying with currency becomes moderator for a day is that possible that the ankhbot does?

  • BellocDK

    Awesome find, bookmarked for futher study! Thanks man! :)

  • Kraetok

    Awesome info!! Thanks for all the hard work! Is it possible to have a Sub Points count just like you have the Sub Count command? I know Ankhbot just recently added Twitch subscriber info and they are able to show count, points, levels and who etc… so it must be possible for to pull the info somehow…

    • Hey, you’re welcome! Happy to know some people are finding this useful.

      Subpoints has already been added (it’s just not covered in this blog post (yet)), but you can find a basic example of it here: https://docs.decapi.me/#/twitch?endpoint=subpoints%2F%3Achannel

      • Kraetok

        Thank you so much for the quick reply. I know this is a long shot.. but would you know how to put that info into a text based source for OBS so I could have a “goal counter” of sorts?

        Like: Sub Point Goal: 23 / 50

        • Sorry for the super late reply, apparently I didn’t get any notification of this reply.

          I do know how, but it’s not exactly… convenient. You should be able to throw that URL in the OBS browser source plugin and it should work.
          Add another text source before it and you should be able to line them up (in theory, I haven’t tested this).

          If you know CSS, you could use that in the browser source to make the text use the same fonts.

  • What currency are you trying to convert from and to?

    Right now, with the URL you’ve put into the command, it tries to convert from “FROM” (which isn’t a valid currency) to “TO” (another invalid currency).

    EDIT – Did a quick edit right after posting to make this a bit clearer and easier to copy.:
    I don’t have Deepbot to test with, but you could use this URL: https://decapi.me/misc/currency?value=@target@[1]&from=@target@[2]&to=@target@[3]
    This should allow you to specify the amount + the currencies to convert in the command.
    Say the command name is !currency and you want to convert 100 USD (US Dollars) to NOK (Norwegian Krone), then you would do the command:
    !currency 100 USD NOK

    As I said, I don’t have Deepbot to test with, so I’m not 100% sure that URL will work, but give it a shot and let me know what the result is.

  • Kitty

    ahh ok cause i tried having it from = USD and TO = NZD and when i ran the command it would respons 0 USD = 0 NZD when i had done !convert 100 ? So i though maybe it auto found the currency from your example { !commandname 100 USD GBP } Anyway i want to mainly be able to USD to NZD my curency is NZD.

    • Oh okay, in that case you should be able to use and it will only convert from USD to NZD:

  • eTheBlack

    By looking at “achievements” that Twitch implented, I guess there is APi for that? Did you find or can you make one where it displays total hours watched specific channel (from all viewers) and total streaming hours (specific channel)?

    • There is an API, it’s not documented publicly and it requires authentication, but I don’t know what kind of access one would need to get that data (which might complicate things by a ton).

      I’ll try to look into it a bit more, but I’m a bit hesitant to add something like this because it’s not in the official documentation for their API, nor do I want to start using “old” endpoints before they’ve fully released their new API fully (called “Helix”).