Here you can find detailed API documentation for all of the public and private endpoints served by MtheBot_
Public endpoints are accessible from any source, without authentication.
Used to authenticate a user to MtheBot_. Also initializes new users if it is their first authentication.
{
"code": "0123456789abcdefghijABCDEFGHIJ"
}code - string - the auth code returned from Twitch authentication
200 OK
{
"user_data": {
"id": "44322889",
"login": "dallas",
"display_name": "dallas",
"type": "staff",
"broadcaster_type": "",
"description": "Just a gamer playing games and chatting. :)",
"profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-profile_image-1a2c906ee2c35f12-300x300.png",
"offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-channel_offline_image-1a2c906ee2c35f12-1920x1080.png",
"view_count": 191836881,
},
"session_token": "0123456789abcdefghijABCDEFGHIJ"
}500 Internal Server Error
Retrieve the number of users being serviced by MtheBot_
json Pass this if a JSON response is desired (used for the README badges)
3{
"schemaVersion": 1,
"label": "users",
"message": 3,
"color": "blue"
}Submit a contact ticket for MtheBot_
{
"type": "Feedback",
"subject": "Awesome Bot!",
"email": "mitch@mtheb.tv",
"name": "Mitch",
"message": "This is a really cool project!"
}type - string - the type of contact being made ['General', 'Help', 'Bug Report', 'Suggestion', 'Feedback']
subject - string - the subject of the message
email - string - the email for responses to be sent to
name - string - the name of the person sending the message
message - string - the content of the contact message
200 OK
contact sent sucessfully
Private endpoints require the caller to be authenticated with Twitch
Get or update the status of MtheBot_ for a given channel id
Get the status of MtheBot_ for the channel
200 OK
MtheBot_ is enabled
1
MtheBot_ is disabled
0
Enable MtheBot_ in the channel
200 OK
Bot set to enabled for channel channelID
Disable MtheBot_ in the channel
200 OK
Bot set to disabled for channel channelID
Get or update commands for a given channel id
All request and response bodies will come in the form of the command object
{
"alias": "myCommand",
"message": "this is a command message",
"cooldown": 5,
"user_level": 0
}alias - string - the alias of the command (automatically prefixed by ! for use in chat)
message - string - the message to be sent by the bot when the command is used
cooldown - int - the cooldown time between uses in seconds
user_level - int - the enumerated user level at which the command can be used {user: 0, vip: 1, subscriber: 2, moderator: 3, global_mod: 3, broadcaster: 3}
Get a list of all commands for the channel
200 OK
[
{
"alias": "myCommand",
"message": "this is a command message",
"cooldown": 5,
"user_level": 0
},
{
"alias": "subs",
"message": "I currently have {{subcount}} subs",
"cooldown": 5,
"user_level": 0
}
]Gets the command with the given alias for the channel
200 OK
{
"alias": "myCommand",
"message": "this is a command message",
"cooldown": 5,
"user_level": 0
}404 Not Found
Command alias not found for channel channelID
Creates a new command for the channel
{
"alias": "myCommand",
"message": "this is a command message",
"cooldown": 5,
"user_level": 0
}The server will respond with the created command, which should be the same as the data provided
200 OK
{
"alias": "myCommand",
"message": "this is a command message",
"cooldown": 5,
"user_level": 0
}400 Bad Request
Command alias already exists for channel channelID
Update an existing command for the channel
{
"alias": "myCommand",
"message": "this is an updated command message",
"cooldown": 5,
"user_level": 0
}The server will respond with the updated command, which should be the same as the data provided
200 OK
{
"alias": "myCommand",
"message": "this is an updated command message",
"cooldown": 5,
"user_level": 0
}404 Not Found
Command alias not found for channel channelID
Removes the command from the channel
200 OK
404 Not Found
Get or update events for a given channel id. There are a set number of events for Twitch so the API neither creates nor deletes events for channels, only updates the data.
All request and response bodies will come in the form of the event object
{
"name": "sub",
"message": "{{user}} just subbed with a {{type}} sub!",
"enabled": true,
}name - string - the name of the event
message - string - the message to be sent by the bot when the event happens
enabled - boolean - whether or not the event is being handled by MtheBot_
Get a list of all events for the channel
200 OK
[
{
"name": "sub",
"message": "{{user}} just subbed with a {{type}} sub!",
"enabled": true
},
{
"name": "host",
"message": "{{user}} hosted for {{viewers}} viewers!",
"enabled": true
},
{
"name": "raid",
"message": "{{user}} raided for {{viewers}} viewers!",
"enabled": true
},
{
"name": "cheer",
"message": "{{user}} just cheered {{amount}} bits!",
"enabled": true
},
{
"name": "resub",
"message": "{{user}} resubbed for {{months}} months!",
"enabled": true
},
{
"name": "subgift",
"message": "{{user}} gifted {{recipient}} a sub!",
"enabled": true
},
{
"name": "giftupgrade",
"message": "{{user}} upgraded their gifted sub from {{gifter}}!",
"enabled": true
},
{
"name": "mysterygift",
"message": "{{user}} gifted {{count}} subs!",
"enabled": true
},
{
"name": "anongiftupgrade",
"message": "{{user}} upgraded their gifted sub!",
"enabled": true
}
]Gets the event with the given name for the channel
200 OK
{
"name": "sub",
"message": "{{user}} just subbed with a {{type}} sub!",
"enabled": true
}404 Not Found
Event name not found for channel channelID
Update an event for the channel
{
"enabled": false,
"message": "{{user}} just subbed with a {{type}} sub!",
}The server will respond with the updated event data, which should be the same as the data provided
200 OK
{
"name": "sub",
"message": "{{user}} just subbed with a {{type}} sub!",
"enabled": false
}404 Not Found
Event name not found for channel channelID
Get or update timers for a given channel id
All request and response bodies will come in the form of the timer object
{
"name": "prime",
"message": "subscribe with prime please",
"enabled": true,
"interval": 300,
"message_threshold": 5
}name - string - the name of the timer (only relevant for user reference)
message - string - the message to be sent by the bot when the command is used
enabled - boolean - whether or not the timer is active
interval - int - the number of seconds between each send of this timer
message_threshold - int - the number of chats required between each send of this message (useful so slower chats do not get spammed)
Get a list of all timers for the channel
200 OK
[
{
"name": "prime",
"message": "subscribe with prime please",
"enabled": true,
"interval": 300,
"message_threshold": 5
},
{
"name": "water",
"message": "dont forget to drink some water!",
"enabled": true,
"interval": 300,
"message_threshold": 0
}
]Gets the timer with the given name for the channel
200 OK
{
"name": "prime",
"message": "subscribe with prime please",
"enabled": true,
"interval": 300,
"message_threshold": 5
}404 Not Found
Timer name not found for channel channelID
Creates a new timer for the channel
{
"name": "prime",
"message": "subscribe with prime please",
"enabled": true,
"interval": 300,
"message_threshold": 5
}The server will respond with the created timer, which should be the same as the data provided
200 OK
{
"name": "prime",
"message": "subscribe with prime please",
"enabled": true,
"interval": 300,
"message_threshold": 5
}400 Bad Request
Timer prime already exists for channel channelID
Update an existing timer for the channel
{
"name": "prime",
"message": "subscribe with prime pretty please",
"enabled": true,
"interval": 60,
"message_threshold": 5
}The server will respond with the updated timer, which should be the same as the data provided
200 OK
{
"name": "prime",
"message": "subscribe with prime pretty please",
"enabled": true,
"interval": 60,
"message_threshold": 5
}404 Not Found
Timer name not found for channel channelID
Removes the timer from the channel
200 OK
404 Not Found