├── LICENSE ├── includes ├── _errors.md ├── _userlevels.md ├── channel │ ├── _get.md │ ├── _introduction.md │ ├── _post_join.md │ ├── _post_part.md │ └── _post_send.md ├── commands │ ├── _delete_id.md │ ├── _get.md │ ├── _get_id.md │ ├── _introduction.md │ ├── _post.md │ ├── _put_id.md │ └── default │ │ ├── _get.md │ │ ├── _get_name.md │ │ └── _put_name.md ├── me │ ├── _get.md │ └── _introduction.md ├── oauth │ ├── _auth_code_flow.md │ ├── _basic_steps.md │ ├── _implicit_flow.md │ ├── _introduction.md │ ├── _refreshing_tokens.md │ ├── _revoking_tokens.md │ └── _scopes.md ├── regulars │ ├── _delete_id.md │ ├── _get.md │ ├── _get_id.md │ ├── _introduction.md │ └── _post.md ├── song_requests │ ├── _get.md │ ├── _introduction.md │ ├── _put.md │ ├── playlist │ │ ├── _delete.md │ │ ├── _delete_id.md │ │ ├── _get.md │ │ ├── _get_id.md │ │ ├── _post.md │ │ └── _post_import.md │ └── queue │ │ ├── _delete.md │ │ ├── _delete_id.md │ │ ├── _get.md │ │ ├── _get_id.md │ │ ├── _post.md │ │ ├── _post_id_promote.md │ │ ├── _post_pause.md │ │ ├── _post_play.md │ │ └── _post_skip.md ├── spam_protection │ ├── _get.md │ ├── _get_type.md │ ├── _introduction.md │ └── _put_type.md ├── subscribers │ ├── _delete_id.md │ ├── _get.md │ ├── _get_id.md │ ├── _introduction.md │ └── _post.md └── timers │ ├── _delete_id.md │ ├── _get.md │ ├── _get_id.md │ ├── _introduction.md │ ├── _post.md │ └── _put_id.md └── index.html.md /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 Nightbot 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /includes/_errors.md: -------------------------------------------------------------------------------- 1 | # Errors 2 | 3 | ``` 4 | { 5 | "status": "400", 6 | "message": "channel is not joined" 7 | } 8 | ``` 9 | 10 | Any request with a non-200 status code represents an error. We return the status as an HTTP status as well as within the response of API requests to make debugging easier. 11 | 12 | For every error, a human-readable error message is returned under the `message` key. In the future, we will likely expand error handling to include error codes so that each error can be better documented and handled by third parties. 13 | -------------------------------------------------------------------------------- /includes/_userlevels.md: -------------------------------------------------------------------------------- 1 | # Userlevels 2 | 3 | In order to add access levels to features of Nightbot, we use the following userlevels: 4 | 5 | * **admin** - Nightbot Administrator 6 | * **owner** - Channel Owner/Manager 7 | * **moderator** - Channel Moderator 8 | * **twitch_vip** - Twitch VIP (only for Twitch accounts) 9 | * **soop_vip** - SOOP VIP (only for SOOP accounts) 10 | * **regular** - Nightbot Regular (users in the regulars list) 11 | * **subscriber** - Paid Channel Subscriber (called "Channel Members" on YouTube) 12 | * **everyone** - Normal User (default) 13 | 14 | The userlevels are listed from highest to lowest. Users in higher userlevels acquire the permissions of the levels below them. 15 | -------------------------------------------------------------------------------- /includes/channel/_get.md: -------------------------------------------------------------------------------- 1 | ## Get channel 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/channel" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "channel": { 10 | "_id": "567224fe9511a38f5114cae0", 11 | "createdAt": "2024-02-14T06:34:49.000Z", 12 | "updatedAt": "2024-03-23T03:17:27.568Z", 13 | "name": "testing", 14 | "displayName": "Testing", 15 | "avatar": "https://static-cdn.jtvnw.net/user-default-pictures-uv/dbdc9198-def8-11e9-8681-784f43822e80-profile_image-300x300.png", 16 | "provider": "twitch", 17 | "providerId": "12345678", 18 | "admin": false, 19 | "joined": true, 20 | "botId": "554eb4b73ee1bab94698bae7" 21 | } 22 | } 23 | ``` 24 | 25 | Gets the current API user's channel information 26 | 27 | **HTTP Request** 28 | 29 | `GET https://api.nightbot.tv/1/channel` 30 | 31 | **Scope** 32 | 33 | `channel` 34 | -------------------------------------------------------------------------------- /includes/channel/_introduction.md: -------------------------------------------------------------------------------- 1 | # Channel 2 | 3 | The channel endpoints allow you to get information about the channel as well as join and part the bot. 4 | 5 | ## Channel Resource 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 |
FieldsTypeDescription
_idstringChannel ID
displayNamestringChannel display name
joinedbooleanChannel join status
namestringChannel name
planstringFor future use
-------------------------------------------------------------------------------- /includes/channel/_post_join.md: -------------------------------------------------------------------------------- 1 | ## Join channel 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/channel/join" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200 9 | } 10 | ``` 11 | 12 | Makes Nightbot join (enter) the current user's channel 13 | 14 | **HTTP Request** 15 | 16 | `POST https://api.nightbot.tv/1/channel/join` 17 | 18 | **Scope** 19 | 20 | `channel` -------------------------------------------------------------------------------- /includes/channel/_post_part.md: -------------------------------------------------------------------------------- 1 | ## Part channel 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/channel/part" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200 9 | } 10 | ``` 11 | 12 | Makes Nightbot part (leave) the current user's channel 13 | 14 | **HTTP Request** 15 | 16 | `POST https://api.nightbot.tv/1/channel/part` 17 | 18 | **Scope** 19 | 20 | `channel` -------------------------------------------------------------------------------- /includes/channel/_post_send.md: -------------------------------------------------------------------------------- 1 | ## Send channel message 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/channel/send" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "message=test%20message" 7 | 8 | { 9 | "status": 200 10 | } 11 | ``` 12 | 13 | Makes Nightbot send a message to the channel 14 | 15 | **HTTP Request** 16 | 17 | `POST https://api.nightbot.tv/1/channel/send` 18 | 19 | **Scope** 20 | 21 | `channel_send` 22 | 23 | **Rate Limit** 24 | 25 | This endpoint is rate limited to 1 request per 5 seconds. If exceeded a HTTP 429 "Too Many Requests" response is returned. 26 | 27 | **Body Parameters** 28 | 29 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 |
ParameterTypeRequiredDescription
messagestringRequiredThe message to send to chat. Maximum length: 400 characters
chatIdstringOptionalThe chat ID to send chat to. When not provided the message is sent to all chat rooms for this channel. This is only useful for YouTube channels with multiple concurrent chat rooms.
55 | -------------------------------------------------------------------------------- /includes/commands/_delete_id.md: -------------------------------------------------------------------------------- 1 | ## Delete custom command by id 2 | 3 | ```cURL 4 | curl -X DELETE "https://api.nightbot.tv/1/commands/56739fb5d0c250946ed6746e" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200 9 | } 10 | ``` 11 | 12 | Deletes a custom command by id 13 | 14 | **HTTP Request** 15 | 16 | `DELETE https://api.nightbot.tv/1/commands/:id` 17 | 18 | **Scope** 19 | 20 | `commands` -------------------------------------------------------------------------------- /includes/commands/_get.md: -------------------------------------------------------------------------------- 1 | ## Get custom commands 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/commands" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "_total": 30, 9 | "status": 200, 10 | "commands": [ 11 | { 12 | "_id": "56739fb5d0c250946ed6746e", 13 | "createdAt": "2015-12-18T05:55:01.735Z", 14 | "updatedAt": "2015-12-18T05:55:01.735Z", 15 | "name": "!testing", 16 | "message": "this is a test message", 17 | "coolDown": 30, 18 | "count": 0, 19 | "userLevel": "everyone" 20 | }, 21 | ... 22 | ] 23 | } 24 | ``` 25 | 26 | Gets the current API user's custom commands list 27 | 28 | **HTTP Request** 29 | 30 | `GET https://api.nightbot.tv/1/commands` 31 | 32 | **Scope** 33 | 34 | `commands` -------------------------------------------------------------------------------- /includes/commands/_get_id.md: -------------------------------------------------------------------------------- 1 | ## Get custom command by id 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/commands/56739fb5d0c250946ed6746e" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "command": { 10 | "_id": "56739fb5d0c250946ed6746e", 11 | "createdAt": "2015-12-18T05:55:01.735Z", 12 | "updatedAt": "2015-12-18T05:55:01.735Z", 13 | "name": "!testing", 14 | "message": "this is a test message", 15 | "coolDown": 30, 16 | "count": 0, 17 | "userLevel": "everyone" 18 | } 19 | } 20 | ``` 21 | 22 | Looks up a custom command by id 23 | 24 | **HTTP Request** 25 | 26 | `GET https://api.nightbot.tv/1/commands/:id` 27 | 28 | **Scope** 29 | 30 | `commands` -------------------------------------------------------------------------------- /includes/commands/_introduction.md: -------------------------------------------------------------------------------- 1 | # Commands 2 | 3 | The commands endpoints allow you to view, add, edit, and remove channel commands. Default commands can only be enabled and disabled, not removed. 4 | 5 | ## Custom Command Resource 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 |
FieldsTypeDescription
_idstringThe command's unique ID
coolDownnumberThe minimum amount of seconds between command usage (prevents spam)
countnumberThe number of times a command has been used (only increments if the command uses the count variable)
createdAtdateThe time the command was created
messagestringThe message Nightbot sends to chat when the command is called. It can contain variables for extra functionality.
namestringThe command name (usually prefixed with a !, but any prefix [or none] can be used)
updatedAtdateThe last time the command was updated
userLevelenumThe userlevel required to use the command
58 | 59 | ## Default Command Resource 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 |
FieldsTypeDescription
_namestringThe command's unique name
coolDownnumberThe minimum amount of seconds between command usage (prevents spam)
enabledbooleanThe status of the default command. If true, command is enabled. If false, the command is disabled and is nonfunctional.
namestringThe command name (usually prefixed with a !, but any prefix [or none] can be used)
userLevelenumThe userlevel required to use the command
-------------------------------------------------------------------------------- /includes/commands/_post.md: -------------------------------------------------------------------------------- 1 | ## Add new custom command 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/commands" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "message=test%20message" \ 7 | -d "userLevel=everyone" \ 8 | -d "coolDown=5" \ 9 | -d "name=!test" 10 | 11 | { 12 | "status": 200, 13 | "command": { 14 | "createdAt": "2016-01-04T05:26:27.593Z", 15 | "updatedAt": "2016-01-04T05:26:27.593Z", 16 | "name": "!test", 17 | "message": "test message", 18 | "_id": "568a02834184d1a07660f380", 19 | "coolDown": 5, 20 | "count": 0, 21 | "userLevel": "everyone" 22 | } 23 | } 24 | ``` 25 | 26 | Adds a new custom command to the current user's channel 27 | 28 | **HTTP Request** 29 | 30 | `POST https://api.nightbot.tv/1/commands` 31 | 32 | **Scope** 33 | 34 | `commands` 35 | 36 | **Body Parameters** 37 | 38 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 |
ParameterTypeRequiredDescription
coolDownnumberRequiredThe minimum amount of seconds between command usage (prevents spam).
messagestringRequiredThe message to send to chat. It can contain variables for extra functionality. Maximum length: 400 characters
namestringRequiredThe command name (usually prefixed with a !, but any prefix [or none] can be used)
userLevelenumRequiredThe userlevel required to use the command.
-------------------------------------------------------------------------------- /includes/commands/_put_id.md: -------------------------------------------------------------------------------- 1 | ## Edit custom command by id 2 | 3 | ```cURL 4 | curl -X PUT "https://api.nightbot.tv/1/commands/568a02834184d1a07660f380" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "name=!testing" 7 | 8 | { 9 | "status": 200, 10 | "command": { 11 | "createdAt": "2016-01-04T05:26:27.593Z", 12 | "updatedAt": "2016-01-04T05:26:27.593Z", 13 | "name": "!testing", 14 | "message": "test message", 15 | "_id": "568a02834184d1a07660f380", 16 | "coolDown": 5, 17 | "count": 0, 18 | "userLevel": "everyone" 19 | } 20 | } 21 | ``` 22 | 23 | Edits a custom command by its id. 24 | 25 | **HTTP Request** 26 | 27 | `PUT https://api.nightbot.tv/1/commands/:id` 28 | 29 | **Scope** 30 | 31 | `commands` 32 | 33 | **Body Parameters** 34 | 35 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). `PUT` requests usually require the entire model to be included in the request, but we allow partial updates. 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 |
ParameterTypeRequiredDescription
coolDownnumberOptionalThe minimum amount of seconds between command usage (prevents spam). Defaults to 30
countnumberOptionalThe number of times a command has been used (only increments if the command uses the count variable). Defaults to 0
messagestringOptionalThe message to send to chat. It can contain variables for extra functionality. Maximum length: 400 characters
namestringOptionalThe command name (usually prefixed with a !, but any prefix [or none] can be used)
userLevelenumOptionalThe userlevel required to use the command. Defaults to everyone
-------------------------------------------------------------------------------- /includes/commands/default/_get.md: -------------------------------------------------------------------------------- 1 | ## Get default commands 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/commands/default" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "_total": 8, 9 | "status": 200, 10 | "commands": [ 11 | { 12 | "name": "!commands", 13 | "coolDown": 5, 14 | "enabled": true, 15 | "userLevel": "everyone", 16 | "_name": "commands", 17 | "_description": "Allows users to get a list of commands and moderators to manage commands", 18 | "_docs": "https://docs.nightbot.tv/commands/commands" 19 | }, 20 | ... 21 | ] 22 | } 23 | ``` 24 | 25 | Gets the current API user's default commands list 26 | 27 | **HTTP Request** 28 | 29 | `GET https://api.nightbot.tv/1/commands/default` 30 | 31 | **Scope** 32 | 33 | `commands_default` -------------------------------------------------------------------------------- /includes/commands/default/_get_name.md: -------------------------------------------------------------------------------- 1 | ## Get default command by name 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/commands/default/commands" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "command": { 10 | "name": "!commands", 11 | "coolDown": 5, 12 | "enabled": true, 13 | "userLevel": "everyone", 14 | "_name": "commands", 15 | "_description": "Allows users to get a list of commands and moderators to manage commands", 16 | "_docs": "https://docs.nightbot.tv/commands/commands" 17 | } 18 | } 19 | ``` 20 | 21 | Looks up a default command by name 22 | 23 | **HTTP Request** 24 | 25 | `GET https://api.nightbot.tv/1/commands/default/:name` 26 | 27 | **Scope** 28 | 29 | `commands_default` -------------------------------------------------------------------------------- /includes/commands/default/_put_name.md: -------------------------------------------------------------------------------- 1 | ## Edit default command by name 2 | 3 | ```cURL 4 | curl -X PUT "https://api.nightbot.tv/1/commands/default/commands" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "coolDown=6" 7 | 8 | { 9 | "status": 200, 10 | "command": { 11 | "name": "!commands", 12 | "coolDown": 6, 13 | "enabled": true, 14 | "userLevel": "everyone", 15 | "_name": "commands", 16 | "_description": "Allows users to get a list of commands and moderators to manage commands", 17 | "_docs": "https://docs.nightbot.tv/commands/commands" 18 | } 19 | } 20 | ``` 21 | 22 | Edits a default command by its name. 23 | 24 | **HTTP Request** 25 | 26 | `PUT https://api.nightbot.tv/1/commands/default/:name` 27 | 28 | **Scope** 29 | 30 | `commands_default` 31 | 32 | **Body Parameters** 33 | 34 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). `PUT` requests usually require the entire model to be included in the request, but we allow partial updates. 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 |
ParameterTypeRequiredDescription
coolDownnumberOptionalThe minimum amount of seconds between command usage (prevents spam).
enabledbooleanOptionalThe status of the default command. If true, command is enabled. If false, the command is disabled and is nonfunctional.
userLevelenumOptionalThe userlevel required to use the command.
-------------------------------------------------------------------------------- /includes/me/_get.md: -------------------------------------------------------------------------------- 1 | ## Get current user 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/me" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "authorization": { 10 | "userLevel": "owner", 11 | "authType": "oauth2", 12 | "credentials": { 13 | "expires": "2016-02-02T20:32:36.129Z", 14 | "client": "d3cfa25e47c9c18e51220e4757d8e57a" 15 | }, 16 | "scopes": [ 17 | "channel", 18 | "channel_send", 19 | "commands", 20 | "commands_default", 21 | "logs", 22 | "regulars", 23 | "song_requests", 24 | "song_requests_queue", 25 | "song_requests_playlist", 26 | "spam_protection", 27 | "timers" 28 | ] 29 | }, 30 | "user": { 31 | "_id": "567224fe9511a38f5114cae0", 32 | "name": "testing", 33 | "displayName": "Testing", 34 | "provider": "twitch", 35 | "providerId": "24895647", 36 | "avatar": "https://static-cdn.jtvnw.net/jtv_user_pictures/testing-profile_image-b209b2800a897689-300x300.png", 37 | "admin": false 38 | } 39 | } 40 | ``` 41 | 42 | Gets the current API user's information 43 | 44 | **HTTP Request** 45 | 46 | `GET https://api.nightbot.tv/1/me` 47 | 48 | **Scope** 49 | 50 | none required -------------------------------------------------------------------------------- /includes/me/_introduction.md: -------------------------------------------------------------------------------- 1 | # Me 2 | 3 | The me endpoint provides you with information about the authorized user 4 | 5 | ## Authorization Resource 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 |
FieldsTypeDescription
userLevelenumUsed internally. Always owner for oauth2.
authTypeenumUsed internally. Always oauth2 for oauth2.
credentialsobjectContains access token expires as a date and client id as a string (of the app the current access token belongs to)
scopesarrayArray of scopes this authorization grants access to
38 | 39 | ## User Resource 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 |
FieldsTypeDescription
_idstringUser id
adminbooleanWhether or not the user is a Nightbot administrator
avatarstringUser avatar link
displayNamestringUser display name
namestringUser name
providerenumThe auth provider for the user account (twitch, youtube, trovo, noice, soop)
providerIdstringThe unique id for this user at the auth provider
87 | -------------------------------------------------------------------------------- /includes/oauth/_auth_code_flow.md: -------------------------------------------------------------------------------- 1 | ## Authorization Code Flow 2 | 3 | **1. Register an app** 4 | 5 | First you need to register an OAuth application on the [applications page](https://nightbot.tv/account/applications) of your account area. Name your app and specify a URL users should be redirected to after authorizing your app. After creating an application, you need to generate a client secret. Click the edit button for your app on the apps page, and then click on the "New Secret" button. 6 | 7 | 10 | 11 | **2. Once you have created an app, you can *302 redirect* users to our authorization endpoint:** 12 | 13 | `https://api.nightbot.tv/oauth2/authorize` 14 | 15 | with the following query string parameters: 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 |
ParameterValuesDescription
client_idThe client ID for the appIdentifies the client that is making the request. The value passed in this parameter must exactly match the value for the app.
redirect_uriOne of the redirect url values listed for the appDetermines where the response is sent. The value of this parameter must exactly match one of the values listed for this app (including the http or https scheme and casing).
response_typecodeDetermines whether the OAuth 2 endpoint returns an authorization code. Web server applications should use code.
scopeSpace-delimited set of permissions that the application requests.Identifies the access that your application is requesting. The values passed in this parameter inform the consent screen that is shown to the user. There is an inverse relationship between the number of permissions requested and the likelihood of obtaining user consent. For information about available scopes, see scopes.
stateAny stringProvides any state that might be useful to your application upon receipt of the response. The authorization server roundtrips this parameter, so your application receives the same value it sent. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response.
53 | 54 | Example URL: 55 | 56 | `https://api.nightbot.tv/oauth2/authorize?response_type=code&client_id=d3cfa25e47c9c18e51220e4757d8e57a&redirect_uri=https%3A%2F%2Ftesting.com%2Fcallback&scope=commands%20timers` 57 | 58 | **3. From the URL above users can choose to allow or deny your application access. Users will then be sent back to your application with a code.** 59 | 60 | Successful Response Example: 61 | 62 | `https://your_redirect_uri?code=cfbdb83aaa4d5c2534c23329de35301a` 63 | 64 | Unsuccessful Response Example: 65 | 66 | `https://your_redirect_uri?error=access_denied` 67 | 68 | **4. With the authorization code sent back with the user, you can exchange it for an access token with a POST request to the following endpoint:** 69 | 70 | `https://api.nightbot.tv/oauth2/token` 71 | 72 | ```cURL 73 | curl -X POST "https://api.nightbot.tv/oauth2/token" \ 74 | -d "client_id=d3cfa25e47c9c18e51220e4757d8e57a" \ 75 | -d "client_secret=50951bf21ec9639b210c7fda38665861" \ 76 | -d "grant_type=authorization_code" \ 77 | -d "redirect_uri=https%3A%2F%2Ftesting.com%2Fcallback" \ 78 | -d "code=cfbdb83aaa4d5c2534c23329de35301a" 79 | 80 | { 81 | "access_token": "4fb1fed8889ec9d1c319d5b3c9a54b23", 82 | "refresh_token": "b98dbbc2e64789532de2c9e7c69b0f89", 83 | "token_type": "bearer", 84 | "expires_in": 2592000, 85 | "scope": "commands timers" 86 | } 87 | ``` 88 | 89 | The request must include the following parameters: 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 115 | 116 | 117 | 118 | 119 | 120 | 121 |
FieldDescription
client_idThe client ID of the app.
client_secretThe client secret of the app.
codeThe authorization code returned from the initial request.
grant_typeAs defined in the OAuth 2 specification, this field must contain a 114 | value of authorization_code.
redirect_uriOne of the redirect URIs listed for the app.
122 | 123 | A successful response from the token endpoint will return an access token and a refresh token. 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 146 | 147 | 148 | 150 | 151 | 152 | 153 | 155 | 156 | 157 |
FieldDescription
access_tokenThe token that can be sent to the Nightbot API.
expires_inThe remaining lifetime of the access token.
refresh_tokenA token that may be used to obtain a new access token. Refresh tokens 144 | are valid until the user revokes access, they expire, or they are used. 145 |
token_typeIdentifies the type of token returned. At this time, this field will 149 | always have the value bearer.
scopeA space separated list of scopes attached to the token returned. 154 | This should be identical to scopes requested during authorization.
158 | 159 | **5. The access token can then be used to access the Nightbot API. Access tokens last 30 days and then must be replaced either by using the refresh token flow or by reauthorizing the user with OAuth. Refresh tokens last 60 days, and a new one is issued by the refresh token flow should you choose to use it.** 160 | 161 | ```cURL 162 | # Access the API via header 163 | curl -X GET "https://api.nightbot.tv/1/me" \ 164 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 165 | 166 | # Access the API via query string 167 | curl -X GET "https://api.nightbot.tv/1/me?access_token=4fb1fed8889ec9d1c319d5b3c9a54b23" 168 | ``` 169 | 170 | **Accessing the API via header:** 171 | 172 | 177 | 178 | **Accessing the API via query string:** 179 | 180 | 184 | -------------------------------------------------------------------------------- /includes/oauth/_basic_steps.md: -------------------------------------------------------------------------------- 1 | ## Basic Steps 2 | 3 | All applications follow a basic pattern when accessing the Nightbot API using OAuth 2. At a high level, you follow four steps: 4 | 5 | **1. Obtain OAuth 2 credentials from the Nightbot Control Panel.** 6 | 7 | Visit the Nightbot Control Panel's Account [Applications](https://nightbot.tv/account/applications) page to obtain OAuth 2 credentials such as a client ID and client secret that are known to both Nightbot and your application. 8 | 9 | **2. Obtain an access token from the Nightbot API.** 10 | 11 | Before your application can access private data using the Nightbot API, it must obtain an access token that grants access to the API. A single access token can grant varying degrees of access to the API. A variable parameter called scope controls the set of operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter. 12 | 13 | There are several ways to make this request, and they vary based on the type of application you are building. For example, a server-side application might request an access token by exchanging a code redirected from our authorization endpoint, while a JavaScript application might request an access token using a browser redirect to our authorization endpoint. 14 | 15 | Some requests require an authentication step where the user logs in with their Nightbot account (if they are not previously logged in). After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent. 16 | 17 | If the user grants the permission, the Nightbot API sends your application an access token (or an authorization code that your application can use to obtain an access token). If the user does not grant the permission, the server returns an error. 18 | 19 | It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. 20 | 21 | **3. Send the access token to an API.** 22 | 23 | After an application obtains an access token, it sends the token to the Nightbot API in an HTTP authorization header. It is possible to send tokens as URI query-string parameters, but we don't recommend it, because URI parameters can end up in log files that are not completely secure. Also, it is good REST practice to avoid creating unnecessary URI parameter names. 24 | 25 | Access tokens are valid only for the set of operations and resources described in the scope of the token request. 26 | 27 | **4. Refresh the access token, if necessary.** 28 | 29 | Access tokens have limited lifetimes. If your application needs access to the Nightbot API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens. 30 | 31 | 34 | -------------------------------------------------------------------------------- /includes/oauth/_implicit_flow.md: -------------------------------------------------------------------------------- 1 | ## Implicit Flow 2 | 3 | **1. Register an app** 4 | 5 | First you need to register an OAuth application on the [applications page](https://nightbot.tv/account/applications) of your account area. Name your app and specify a URL users should be redirected to after authorizing your app. Because this is a client-side flow, you do not need to generate or use a client secret. 6 | 7 | **2. Once you have created an app, you can *302 redirect* users to our authorization endpoint:** 8 | 9 | `https://api.nightbot.tv/oauth2/authorize` 10 | 11 | with the following query string parameters: 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 |
ParameterValuesDescription
client_idThe client ID for the appIdentifies the client that is making the request. The value passed in this parameter must exactly match the value for the app.
redirect_uriOne of the redirect url values listed for the appDetermines where the response is sent. The value of this parameter must exactly match one of the values listed for this app (including the http or https scheme and casing).
response_typetokenDetermines whether the OAuth 2 endpoint returns a token in the fragment of the redirect url.
scopeSpace-delimited set of permissions that the application requests.Identifies the access that your application is requesting. The values passed in this parameter inform the consent screen that is shown to the user. There is an inverse relationship between the number of permissions requested and the likelihood of obtaining user consent. For information about available scopes, see scopes.
stateAny stringProvides any state that might be useful to your application upon receipt of the response. The authorization server roundtrips this parameter, so your application receives the same value it sent. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response.
49 | 50 | Example URL: 51 | 52 | `https://api.nightbot.tv/oauth2/authorize?response_type=token&client_id=d3cfa25e47c9c18e51220e4757d8e57a&redirect_uri=https%3A%2F%2Ftesting.com%2Fcallback&scope=commands%20timers` 53 | 54 | **3. From the URL above users can choose to allow or deny your application access. Users will then be sent back to your application with an access token.** 55 | 56 | Successful Response Example: 57 | 58 | `https://your_redirect_uri#access_token=cfbdb83aaa4d5c2534c23329de35301a&expires_in=2592000&token_type=bearer` 59 | 60 | Unsuccessful Response Example: 61 | 62 | `https://your_redirect_uri#error=access_denied` 63 | 64 | **5. The access token can then be used to access the Nightbot API. Access tokens last 30 days and then must be replaced by reauthorizing the user with OAuth. Refresh tokens are not issued for implicit authorizations, so it is not possible to refresh the access token with this implementation.** 65 | 66 | ```cURL 67 | # Access the API via header 68 | curl -X GET "https://api.nightbot.tv/1/me" \ 69 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 70 | 71 | # Access the API via query string 72 | curl -X GET "https://api.nightbot.tv/1/me?access_token=4fb1fed8889ec9d1c319d5b3c9a54b23" 73 | ``` 74 | 75 | **Accessing the API via header:** 76 | 77 | 82 | 83 | **Accessing the API via query string:** 84 | 85 | 89 | -------------------------------------------------------------------------------- /includes/oauth/_introduction.md: -------------------------------------------------------------------------------- 1 | # OAuth 2 2 | 3 | Nightbot uses the OAuth 2 flow for securely authorizing requests to our API. Much of these authorization docs have been adapted from [Google's excellent documentation on OAuth](https://developers.google.com/identity/protocols/OAuth2). 4 | -------------------------------------------------------------------------------- /includes/oauth/_refreshing_tokens.md: -------------------------------------------------------------------------------- 1 | ## Refreshing Tokens 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/oauth2/token" \ 5 | -d "client_id=d3cfa25e47c9c18e51220e4757d8e57a" \ 6 | -d "client_secret=50951bf21ec9639b210c7fda38665861" \ 7 | -d "grant_type=refresh_token" \ 8 | -d "redirect_uri=https%3A%2F%2Ftesting.com%2Fcallback" \ 9 | -d "refresh_token=cfbdb83aaa4d5c2534c23329de35301a" 10 | 11 | { 12 | "access_token": "4fb1fed8889ec9d1c319d5b3c9a54b23", 13 | "refresh_token": "b98dbbc2e64789532de2c9e7c69b0f89", 14 | "token_type": "bearer", 15 | "expires_in": 2592000, 16 | "scope": "commands timers" 17 | } 18 | ``` 19 | 20 | As indicated in the previous sections, a refresh token is obtained in the token exchange with an authorization code. In this case, your application may obtain a new access token by sending a refresh token to the token endpoint: 21 | 22 | `https://api.nightbot.tv/oauth2/token` 23 | 24 | The request must include the following parameters: 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 |
FieldDescription
client_idThe client ID of the app.
client_secretThe client secret of the app.
grant_typeAs defined in the OAuth 2 specification, this field must contain a 45 | value of refresh_token.
redirect_uriOne of the redirect URIs listed for the app.
refresh_tokenThe refresh token of the access token being refreshed.
57 | 58 | The new access token can then be used to access the Nightbot API. Access tokens last 30 days and then must be replaced either by using the **new** refresh token flow or by reauthorizing the user with OAuth. Refresh tokens last 60 days. 59 | -------------------------------------------------------------------------------- /includes/oauth/_revoking_tokens.md: -------------------------------------------------------------------------------- 1 | ## Revoking Tokens 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/oauth2/token/revoke" \ 5 | -d "token=cfbdb83aaa4d5c2534c23329de35301a" 6 | ``` 7 | 8 | In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting [Account Applications](https://nightbot.tv/account/applications). It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes or removes an application. In other words, part of the removal process can include an API request to ensure the permissions granted to the application are removed. 9 | 10 | To revoke an access or refresh token, pass the token in a **POST** request to the revocation endpoint: 11 | 12 | `https://api.nightbot.tv/oauth2/token/revoke` 13 | 14 | The request must include the following parameters: 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 |
FieldDescription
tokenThe access or refresh token being revoked.
30 | -------------------------------------------------------------------------------- /includes/oauth/_scopes.md: -------------------------------------------------------------------------------- 1 | ## Scopes 2 | 3 | We provide the following scopes to allow you to restrict Nightbot API access to use only what your application requires. 4 | 5 | * **channel** - View and edit channel settings and join/part the bot 6 | * **channel_send** - Ability to send messages to the channel as Nightbot 7 | * **commands** - View, add, edit, and remove channel custom commands 8 | * **commands_default** - View, edit, enable, and disable channel default commands 9 | * **regulars** - View, add, and remove channel regulars 10 | * **song_requests** - View and edit channel song request settings 11 | * **song_requests_queue** - View, add, edit, and remove songs on the channel song request queue 12 | * **song_requests_playlist** - View, add, edit, and remove songs on the channel song request playlist 13 | * **spam_protection** - View, edit, enable, and disable channel spam protection filters 14 | * **subscribers** - View, add, and remove channel subscribers (useful for third party subscription services) 15 | * **timers** - View, add, edit, and remove channel timers 16 | -------------------------------------------------------------------------------- /includes/regulars/_delete_id.md: -------------------------------------------------------------------------------- 1 | ## Delete regular by id 2 | 3 | ```cURL 4 | curl -X DELETE "https://api.nightbot.tv/1/regulars/56739fb5d0c250946ed67448" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200 9 | } 10 | ``` 11 | 12 | Deletes a regular by id 13 | 14 | **HTTP Request** 15 | 16 | `DELETE https://api.nightbot.tv/1/regulars/:id` 17 | 18 | **Scope** 19 | 20 | `regulars` -------------------------------------------------------------------------------- /includes/regulars/_get.md: -------------------------------------------------------------------------------- 1 | ## Get regulars 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/regulars" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "_total": 30, 9 | "status": 200, 10 | "regulars": [ 11 | { 12 | "_id": "56739fb5d0c250946ed67448", 13 | "createdAt": "2015-12-18T05:55:01.458Z", 14 | "updatedAt": "2015-12-18T05:55:01.458Z", 15 | "provider": "twitch", 16 | "providerId": "96837452", 17 | "name": "test_user", 18 | "displayName": "Test_User" 19 | }, 20 | ... 21 | ] 22 | } 23 | ``` 24 | 25 | Gets the current API user's regulars list 26 | 27 | **HTTP Request** 28 | 29 | `GET https://api.nightbot.tv/1/regulars` 30 | 31 | **Scope** 32 | 33 | `regulars` 34 | 35 | **Query String Parameters** 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 |
ParameterTypeRequiredDescription
limitnumberOptionalThe is the maximum amount of regulars to return in the request (minimum 1, maximum 100)
offsetnumberOptionalThis is the regular offset count that is used for pagination
qstringOptionalA displayName to search for (case insensitive)
-------------------------------------------------------------------------------- /includes/regulars/_get_id.md: -------------------------------------------------------------------------------- 1 | ## Get regular by id 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/regulars/56739fb5d0c250946ed67448" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "regular": { 10 | "_id": "56739fb5d0c250946ed67448", 11 | "createdAt": "2015-12-18T05:55:01.458Z", 12 | "updatedAt": "2015-12-18T05:55:01.458Z", 13 | "provider": "twitch", 14 | "providerId": "96837452", 15 | "name": "test_user", 16 | "displayName": "Test_User" 17 | } 18 | } 19 | ``` 20 | 21 | Looks up a regular by id 22 | 23 | **HTTP Request** 24 | 25 | `GET https://api.nightbot.tv/1/regulars/:id` 26 | 27 | **Scope** 28 | 29 | `regulars` 30 | -------------------------------------------------------------------------------- /includes/regulars/_introduction.md: -------------------------------------------------------------------------------- 1 | # Regulars 2 | 3 | The regulars endpoints allow you to view, add, edit, and remove channel regulars. Nightbot Regulars adds another userlevel to the chat. Regulars can be granted extra permission for commands and spam protection. 4 | 5 | ## Regular Resource 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 |
FieldsTypeDescription
_idstringRegular id
createdAtdateThe time the regular was added
displayNamestringUser display name
namestringUser unique name
providerenumThe auth provider for the regular (twitch, youtube, trovo, noice, soop)
providerIdstringThe unique id for this user at the auth provider
updatedAtdateThe last time the regular was updated
53 | -------------------------------------------------------------------------------- /includes/regulars/_post.md: -------------------------------------------------------------------------------- 1 | ## Add new regular 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/regulars" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "name=test_user" 7 | 8 | { 9 | "status": 200, 10 | "regular": { 11 | "_id": "56739fb5d0c250946ed67448", 12 | "createdAt": "2015-12-18T05:55:01.458Z", 13 | "updatedAt": "2015-12-18T05:55:01.458Z", 14 | "provider": "twitch", 15 | "providerId": "96837452", 16 | "name": "test_user", 17 | "displayName": "Test_User" 18 | } 19 | } 20 | ``` 21 | 22 | Adds a new regular to the current user's channel 23 | 24 | **HTTP Request** 25 | 26 | `POST https://api.nightbot.tv/1/regulars` 27 | 28 | **Scope** 29 | 30 | `regulars` 31 | 32 | **Body Parameters** 33 | 34 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 |
ParameterTypeRequiredDescription
namestringRequiredThis is the username of the person you wish to add as a regular. In the case of YouTube, it would be the user's YouTube channel URL.
54 | -------------------------------------------------------------------------------- /includes/song_requests/_get.md: -------------------------------------------------------------------------------- 1 | ## Get song request settings 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/song_requests" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "settings": { 10 | "limits": { 11 | "queue": 20, 12 | "user": 10, 13 | "playlistOnly": false, 14 | "exemptUserLevel": "moderator" 15 | }, 16 | "volume": 59, 17 | "enabled": true, 18 | "providers": [ 19 | "soundcloud", 20 | "youtube" 21 | ], 22 | "playlist": "channel", 23 | "userLevel": "everyone", 24 | "searchProvider": "soundcloud", 25 | "youtube": { 26 | "limitToMusic": false, 27 | "limitToLikedVideos": true 28 | } 29 | }, 30 | "providers": { 31 | "soundcloud": "SoundCloud", 32 | "youtube": "YouTube" 33 | }, 34 | "playlists": { 35 | "channel": "Channel", 36 | "monstercat": "Monstercat", 37 | "twitch_music_library": "Twitch Music Library" 38 | } 39 | } 40 | ``` 41 | 42 | Gets the current API user's song request settings 43 | 44 | **HTTP Request** 45 | 46 | `GET https://api.nightbot.tv/1/song_requests` 47 | 48 | **Scope** 49 | 50 | `song_requests` -------------------------------------------------------------------------------- /includes/song_requests/_introduction.md: -------------------------------------------------------------------------------- 1 | # Song Requests 2 | 3 | The song request endpoints allow you to view, add, edit, and delete song from the song request queue and playlist as well as modify the settings for song requests. 4 | 5 | ## Song Request Settings Resource 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 |
FieldsTypeDescription
enabledbooleanThe status of song requests. If true, song requests are enabled and songs can be requested by users. If false, song requests are disabled and are nonfunctional.
limitsobjectContains user-configurable song request limits
limits
.queue		numberThe maximum number of songs in the queue (minimum 1, maximum 100)
limits
.user		numberThe maximum number of songs a user can request at a time (minimum 1, maximum 100)
limits
.playlistOnly		booleanIf true, song requests will be limited to the configured playlist. If false, requests can be made from any listed providers
limits
.exemptUserLevel		enumThe userlevel required to be exempt from the limits
playlistenumThe playlist AutoDJ will source from when the queue is empty. If limits.playlistOnly is true all requested songs must be on this playlist. Available playlists are listed in the song request settings GET endpoint as playlists.
providersarrayAn array of enums for the enabled song request providers. Providers are the services which we support pulling songs from. Available providers are listed in the song request settings GET endpoint as providers.
searchProviderenumInstead of requiring users to request songs with a URL or ID, users can search for the closest match to request a song. This controls where that search is performed. Available providers are listed in the song request settings GET endpoint as providers.
userLevelenumThe userlevel required to be able to request songs
volumenumberThe volume that the AutoDJ player runs at (minimum 0, maximum 100)
youtubeobjectYouTube-specific song request settings
youtube
.limitToMusic		booleanTo reduce non-music videos from being requested, you can limit to just the music category by setting this to true. If set to false, videos are not restricted to just the music category.
youtube
.limitToLikedVideos		booleanTo reduce bad videos from being requested, you can limit to videos with more likes than dislikes by setting this to true. If set to false, videos with more dislikes than likes are able to be requested. Defaults to true
88 | 89 | ## Playlist Item Resource 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 |
FieldsTypeDescription
_idstringThe playlist item's unique id
createdAtdateThe time the playlist item was created
trackobjectTrack Information
track
.artist		string, optionalTrack Artist
track
.duration		numberTrack Duration (in seconds)
track
.provider		enumTrack Provider (like "youtube" or "soundcloud")
track
.providerId		stringTrack Provider's unique id
track
.title		stringTrack Title
track
.url		stringTrack URL
updatedAtdateThe last time the playlist item was updated
152 | 153 | ## Queue Item Resource 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | 225 | 226 | 227 | 228 | 229 | 230 | 231 | 232 | 233 | 234 | 235 | 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 |
FieldsTypeDescription
_positionnumber, optionalThe queue item's position in the queue
_idstringThe queue item's unique id
createdAtdateThe time the queue item was created
trackobjectTrack Information
track
.artist		string, optionalTrack Artist
track
.duration		numberTrack Duration (in seconds)
track
.provider		enumTrack Provider (like "youtube" or "soundcloud")
track
.providerId		stringTrack Provider's unique id
track
.title		stringTrack Title
track
.url		stringTrack URL
userobjectInformation about who the queue item belongs to
user
.displayName		stringUser display name
user
.name		stringUser unique name
user
.provider		enumUser provider (twitch, youtube, trovo, noice, soop, discord)
user
.providerId		stringUser provider's unique id
updatedAtdateThe last time the queue item was updated
246 | -------------------------------------------------------------------------------- /includes/song_requests/_put.md: -------------------------------------------------------------------------------- 1 | ## Edit song request settings 2 | 3 | ```cURL 4 | curl -X PUT "https://api.nightbot.tv/1/song_requests" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "enabled=false" 7 | 8 | { 9 | "status": 200, 10 | "settings": { 11 | "youtube": { 12 | "limitToMusic": false, 13 | "limitToLikedVideos": true 14 | }, 15 | "searchProvider": "soundcloud", 16 | "userLevel": "everyone", 17 | "playlist": "channel", 18 | "providers": ["soundcloud", "youtube"], 19 | "enabled": false, 20 | "volume": 59, 21 | "limits": { 22 | "queue": 20, 23 | "user": 10, 24 | "playlistOnly": false, 25 | "exemptUserLevel": "moderator" 26 | } 27 | }, 28 | "providers": { 29 | "soundcloud": "SoundCloud", 30 | "youtube": "YouTube" 31 | }, 32 | "playlists": { 33 | "channel": "Channel", 34 | "monstercat": "Monstercat", 35 | "twitch_music_library": "Twitch Music Library" 36 | } 37 | } 38 | ``` 39 | 40 | Edits the song request settings 41 | 42 | **HTTP Request** 43 | 44 | `PUT https://api.nightbot.tv/1/song_requests` 45 | 46 | **Scope** 47 | 48 | `song_requests` 49 | 50 | **Body Parameters** 51 | 52 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). `PUT` requests usually require the entire model to be included in the request, but we allow partial updates. 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 |
ParameterTypeRequiredDescription
enabledbooleanOptionalThe status of song requests. If true, song requests are enabled and songs can be requested by users. If false, song requests are disabled and are nonfunctional.
limits
.queue		numberOptionalThe maximum number of songs in the queue (minimum 1, maximum 100)
limits
.user		numberOptionalThe maximum number of songs a user can request at a time (minimum 1, maximum 100)
limits
.playlistOnly		booleanOptionalIf true, song requests will be limited to the configured playlist. If false, requests can be made from any listed providers
limits
.playlistOnly		booleanOptionalIf true, song requests will be limited to the configured playlist. If false, requests can be made from any listed providers
limits
.exemptUserLevel		enumOptionalThe userlevel required to be exempt from the limits
playlistenumOptionalThe playlist AutoDJ will source from when the queue is empty. If limits.playlistOnly is true all requested songs must be on this playlist. Available playlists are listed in the song request settings GET endpoint as playlists.
providersarrayOptionalAn array of enums for the enabled song request providers. Providers are the services which we support pulling songs from. Available providers are listed in the song request settings GET endpoint as providers.
searchProviderenumOptionalInstead of requiring users to request songs with a URL or ID, users can search for the closest match to request a song. This controls where that search is performed. Available providers are listed in the song request settings GET endpoint as providers.
userLevelenumOptionalThe userlevel required to be able to request songs
volumenumberOptionalThe volume that the AutoDJ player runs at (minimum 0, maximum 100)
youtube
.limitToMusic		booleanOptionalTo reduce non-music videos from being requested, you can limit to just the music category by setting this to true. If set to false, videos are not restricted to just the music category.
youtube
.limitToLikedVideos		booleanOptionalTo reduce bad videos from being requested, you can limit to videos with more likes than dislikes by setting this to true. If set to false, videos with more dislikes than likes are able to be requested. Defaults to true
-------------------------------------------------------------------------------- /includes/song_requests/playlist/_delete.md: -------------------------------------------------------------------------------- 1 | ## Clear playlist 2 | 3 | ```cURL 4 | curl -X DELETE "https://api.nightbot.tv/1/song_requests/playlist" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200 9 | } 10 | ``` 11 | 12 | Deletes all playlist items 13 | 14 | **HTTP Request** 15 | 16 | `DELETE https://api.nightbot.tv/1/song_requests/playlist` 17 | 18 | **Scope** 19 | 20 | `song_requests_playlist` -------------------------------------------------------------------------------- /includes/song_requests/playlist/_delete_id.md: -------------------------------------------------------------------------------- 1 | ## Delete playlist item by id 2 | 3 | ```cURL 4 | curl -X DELETE "https://api.nightbot.tv/1/song_requests/playlist/567baac77aa5ea140225baf0" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200 9 | } 10 | ``` 11 | 12 | Deletes a song requests playlist item by id 13 | 14 | **HTTP Request** 15 | 16 | `DELETE https://api.nightbot.tv/1/song_requests/playlist/:id` 17 | 18 | **Scope** 19 | 20 | `song_requests_playlist` -------------------------------------------------------------------------------- /includes/song_requests/playlist/_get.md: -------------------------------------------------------------------------------- 1 | ## Get playlist 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/song_requests/playlist" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "_sort": { 10 | "date": "asc" 11 | }, 12 | "_limit": 25, 13 | "_offset": 0, 14 | "_total": 34, 15 | "playlist": [ 16 | { 17 | "track": { 18 | "providerId": "njos57IJf-0", 19 | "provider": "youtube", 20 | "duration": 168, 21 | "title": "Steve Jobs vs Bill Gates. Epic Rap Battles of History Season 2.", 22 | "artist": "ERB", 23 | "url": "https://youtu.be/njos57IJf-0" 24 | }, 25 | "_id": "567baac77aa5ea140225baec", 26 | "createdAt": "2015-12-24T08:20:23.268Z", 27 | "updatedAt": "2015-12-24T08:20:23.268Z" 28 | }, 29 | ... 30 | ] 31 | } 32 | ``` 33 | 34 | Gets the current API user's song request playlist 35 | 36 | **HTTP Request** 37 | 38 | `GET https://api.nightbot.tv/1/song_requests/playlist` 39 | 40 | **Scope** 41 | 42 | `song_requests_playlist` 43 | 44 | **Query String Parameters** 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 |
ParameterTypeRequiredDescription
directionenumOptionalThis is the sorting direction. Values are asc or desc
limitnumberOptionalThe is the maximum amount of playlist items to return in the request (minimum 1, maximum 100)
offsetnumberOptionalThis is the playlist item offset count that is used for pagination
qstringOptionalA term to search for (case insensitive)
sort_byenumOptionalThis is the sorting selection. Values are artist, date, random, title. Defaults to date.
-------------------------------------------------------------------------------- /includes/song_requests/playlist/_get_id.md: -------------------------------------------------------------------------------- 1 | ## Get playlist item by id 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/song_requests/playlist/567baac77aa5ea140225baf0" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "item": { 10 | "track": { 11 | "providerId": "N9qYF9DZPdw", 12 | "provider": "youtube", 13 | "duration": 171, 14 | "title": "\"Weird Al\" Yankovic - White & Nerdy (Official Video)", 15 | "artist": "alyankovicVEVO", 16 | "url": "https://youtu.be/N9qYF9DZPdw" 17 | }, 18 | "_id": "567baac77aa5ea140225baf0", 19 | "createdAt": "2015-12-24T08:20:23.268Z", 20 | "updatedAt": "2015-12-24T08:20:23.268Z" 21 | } 22 | } 23 | ``` 24 | 25 | Looks up a song request playlist item by id 26 | 27 | **HTTP Request** 28 | 29 | `GET https://api.nightbot.tv/1/song_requests/playlist/:id` 30 | 31 | **Scope** 32 | 33 | `song_requests_playlist` 34 | -------------------------------------------------------------------------------- /includes/song_requests/playlist/_post.md: -------------------------------------------------------------------------------- 1 | ## Add new playlist item 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/song_requests/playlist" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "q=https%3A%2F%2Fyoutu.be%2FN9qYF9DZPdw" 7 | 8 | { 9 | "status": 200, 10 | "item": { 11 | "track": { 12 | "providerId": "N9qYF9DZPdw", 13 | "provider": "youtube", 14 | "duration": 171, 15 | "title": "\"Weird Al\" Yankovic - White & Nerdy (Official Video)", 16 | "artist": "alyankovicVEVO", 17 | "url": "https://youtu.be/N9qYF9DZPdw" 18 | }, 19 | "_id": "567baac77aa5ea140225baf0", 20 | "createdAt": "2015-12-24T08:20:23.268Z", 21 | "updatedAt": "2015-12-24T08:20:23.268Z" 22 | } 23 | } 24 | ``` 25 | 26 | Adds a new playlist item to the current user's channel. 27 | 28 | **HTTP Request** 29 | 30 | `POST https://api.nightbot.tv/1/song_requests/playlist` 31 | 32 | **Scope** 33 | 34 | `song_requests_playlist` 35 | 36 | **Body Parameters** 37 | 38 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 |
ParameterTypeRequiredDescription
qstringRequiredThis is the song to add to the playlist. It can be a URL for one of the supported song request providers or a song name to search for (closest match is chosen and search is performed on the channel's selected search provider)
58 | -------------------------------------------------------------------------------- /includes/song_requests/playlist/_post_import.md: -------------------------------------------------------------------------------- 1 | ## Import remote playlist 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/song_requests/playlist/import" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "url=https%3A%2F%2Fwww.youtube.com%2Fplaylist%3Flist%3DPLA11538113C16891A" 7 | 8 | { 9 | "status": 200 10 | } 11 | ``` 12 | 13 | Imports a remote playlist to the current user's channel. 14 | 15 | **HTTP Request** 16 | 17 | `POST https://api.nightbot.tv/1/song_requests/playlist/import` 18 | 19 | **Scope** 20 | 21 | `song_requests_playlist` 22 | 23 | **Body Parameters** 24 | 25 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 |
ParameterTypeRequiredDescription
urlstringRequiredThis is the playlist to import. This is a playlist URL located at one of the supported song request providers
45 | -------------------------------------------------------------------------------- /includes/song_requests/queue/_delete.md: -------------------------------------------------------------------------------- 1 | ## Clear queue 2 | 3 | ```cURL 4 | curl -X DELETE "https://api.nightbot.tv/1/song_requests/queue" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200 9 | } 10 | ``` 11 | 12 | Deletes all queue items 13 | 14 | **HTTP Request** 15 | 16 | `DELETE https://api.nightbot.tv/1/song_requests/queue` 17 | 18 | **Scope** 19 | 20 | `song_requests_queue` -------------------------------------------------------------------------------- /includes/song_requests/queue/_delete_id.md: -------------------------------------------------------------------------------- 1 | ## Delete queue item by id 2 | 3 | ```cURL 4 | curl -X DELETE "https://api.nightbot.tv/1/song_requests/queue/567baac77aa5ea140225baf0" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200 9 | } 10 | ``` 11 | 12 | Deletes a song requests queue item by id 13 | 14 | **HTTP Request** 15 | 16 | `DELETE https://api.nightbot.tv/1/song_requests/queue/:id` 17 | 18 | **Scope** 19 | 20 | `song_requests_queue` -------------------------------------------------------------------------------- /includes/song_requests/queue/_get.md: -------------------------------------------------------------------------------- 1 | ## Get queue 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/song_requests/queue" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "_total": 1, 9 | "_currentSong": { 10 | "_id": "56888945f788ea622d320c38", 11 | "createdAt": "2016-01-03T02:36:53.141Z", 12 | "updatedAt": "2016-01-05T07:39:10.710Z", 13 | "track": { 14 | "providerId": "v4Za061pQac", 15 | "provider": "youtube", 16 | "duration": 191, 17 | "title": "Alex Skrindo - Jumbo [NCS Release]", 18 | "artist": "NoCopyrightSounds", 19 | "url": "https://youtu.be/v4Za061pQac" 20 | }, 21 | "user": { 22 | "name": "test_user_1", 23 | "displayName": "test_user_1", 24 | "providerId": "94385764", 25 | "provider": "twitch" 26 | } 27 | }, 28 | "_requestsEnabled": true, 29 | "_searchProvider": "youtube", 30 | "_providers": ["soundcloud", "youtube"], 31 | "status": 200, 32 | "queue": [ 33 | { 34 | "_id": "5688d2bdc93762323f402b9d", 35 | "createdAt": "2016-01-03T07:50:21.334Z", 36 | "updatedAt": "2016-01-03T07:50:21.334Z", 37 | "track": { 38 | "providerId": "r9gz0Z9yV1k", 39 | "provider": "youtube", 40 | "duration": 197, 41 | "title": "I'm Just a Kid - Simple Plan lyrics", 42 | "artist": "sabrina01021997", 43 | "url": "https://youtu.be/r9gz0Z9yV1k" 44 | }, 45 | "user": { 46 | "name": "test_user_2", 47 | "displayName": "test_user_2", 48 | "providerId": "93854453", 49 | "provider": "twitch" 50 | }, 51 | "_position": 1 52 | } 53 | ] 54 | } 55 | ``` 56 | 57 | Gets the current API user's song request queue 58 | 59 | **HTTP Request** 60 | 61 | `GET https://api.nightbot.tv/1/song_requests/queue` 62 | 63 | **Scope** 64 | 65 | `song_requests_queue` 66 | -------------------------------------------------------------------------------- /includes/song_requests/queue/_get_id.md: -------------------------------------------------------------------------------- 1 | ## Get queue item by id 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/song_requests/queue/567baac77aa5ea140225baf0" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "item": { 10 | "_id": "5688d2bdc93762323f402b9d", 11 | "createdAt": "2016-01-03T07:50:21.334Z", 12 | "updatedAt": "2016-01-03T07:50:21.334Z", 13 | "track": { 14 | "providerId": "r9gz0Z9yV1k", 15 | "provider": "youtube", 16 | "duration": 197, 17 | "title": "I'm Just a Kid - Simple Plan lyrics", 18 | "artist": "sabrina01021997", 19 | "url": "https://youtu.be/r9gz0Z9yV1k" 20 | }, 21 | "user": { 22 | "name": "test_user_2", 23 | "displayName": "test_user_2", 24 | "providerId": "93854453", 25 | "provider": "twitch" 26 | }, 27 | "_position": 1 28 | } 29 | } 30 | ``` 31 | 32 | Looks up a song request queue item by id 33 | 34 | **HTTP Request** 35 | 36 | `GET https://api.nightbot.tv/1/song_requests/queue/:id` 37 | 38 | **Scope** 39 | 40 | `song_requests_queue` 41 | -------------------------------------------------------------------------------- /includes/song_requests/queue/_post.md: -------------------------------------------------------------------------------- 1 | ## Add new queue item 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/song_requests/queue" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "q=https%3A%2F%2Fyoutu.be%2Fr9gz0Z9yV1k" 7 | 8 | { 9 | "status": 200, 10 | "item": { 11 | "_id": "5688d2bdc93762323f402b9d", 12 | "createdAt": "2016-01-03T07:50:21.334Z", 13 | "updatedAt": "2016-01-03T07:50:21.334Z", 14 | "track": { 15 | "providerId": "r9gz0Z9yV1k", 16 | "provider": "youtube", 17 | "duration": 197, 18 | "title": "I'm Just a Kid - Simple Plan lyrics", 19 | "artist": "sabrina01021997", 20 | "url": "https://youtu.be/r9gz0Z9yV1k" 21 | }, 22 | "user": { 23 | "name": "test_user_2", 24 | "displayName": "test_user_2", 25 | "providerId": "93854453", 26 | "provider": "twitch" 27 | }, 28 | "_position": 1 29 | } 30 | } 31 | ``` 32 | 33 | Adds a new queue item to the current user's channel. 34 | 35 | **HTTP Request** 36 | 37 | `POST https://api.nightbot.tv/1/song_requests/queue` 38 | 39 | **Scope** 40 | 41 | `song_requests_queue` 42 | 43 | **Body Parameters** 44 | 45 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 |
ParameterTypeRequiredDescription
qstringRequiredThis is the song to add to the queue. It can be a URL for one of the supported song request providers or a song name to search for (closest match is chosen and search is performed on the channel's selected search provider)
65 | -------------------------------------------------------------------------------- /includes/song_requests/queue/_post_id_promote.md: -------------------------------------------------------------------------------- 1 | ## Promote queue item 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/song_requests/queue/5688d2bdc93762323f402b9d/promote" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "item": { 10 | "_id": "5688d2bdc93762323f402b9d", 11 | "createdAt": "2016-01-03T07:50:21.334Z", 12 | "updatedAt": "2016-01-03T07:50:21.334Z", 13 | "track": { 14 | "providerId": "r9gz0Z9yV1k", 15 | "provider": "youtube", 16 | "duration": 197, 17 | "title": "I'm Just a Kid - Simple Plan lyrics", 18 | "artist": "sabrina01021997", 19 | "url": "https://youtu.be/r9gz0Z9yV1k" 20 | }, 21 | "user": { 22 | "name": "test_user_2", 23 | "displayName": "test_user_2", 24 | "providerId": "93854453", 25 | "provider": "twitch" 26 | }, 27 | "_position": 1 28 | } 29 | } 30 | ``` 31 | 32 | Promotes a queue item to the front of the queue 33 | 34 | **HTTP Request** 35 | 36 | `POST https://api.nightbot.tv/1/song_requests/queue/:id/promote` 37 | 38 | **Scope** 39 | 40 | `song_requests_queue` 41 | -------------------------------------------------------------------------------- /includes/song_requests/queue/_post_pause.md: -------------------------------------------------------------------------------- 1 | ## Pause current queue item 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/song_requests/queue/pause" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "item": { 10 | "_id": "5688d2bdc93762323f402b9d", 11 | "createdAt": "2016-01-03T07:50:21.334Z", 12 | "updatedAt": "2016-01-03T07:50:21.334Z", 13 | "track": { 14 | "providerId": "r9gz0Z9yV1k", 15 | "provider": "youtube", 16 | "duration": 197, 17 | "title": "I'm Just a Kid - Simple Plan lyrics", 18 | "artist": "sabrina01021997", 19 | "url": "https://youtu.be/r9gz0Z9yV1k" 20 | }, 21 | "user": { 22 | "name": "test_user_2", 23 | "displayName": "test_user_2", 24 | "providerId": "93854453", 25 | "provider": "twitch" 26 | } 27 | } 28 | } 29 | ``` 30 | 31 | Pauses the current playing queue item in the current user's channel. 32 | 33 | **HTTP Request** 34 | 35 | `POST https://api.nightbot.tv/1/song_requests/queue/pause` 36 | 37 | **Scope** 38 | 39 | `song_requests_queue` 40 | -------------------------------------------------------------------------------- /includes/song_requests/queue/_post_play.md: -------------------------------------------------------------------------------- 1 | ## Resume current queue item 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/song_requests/queue/play" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "item": { 10 | "_id": "5688d2bdc93762323f402b9d", 11 | "createdAt": "2016-01-03T07:50:21.334Z", 12 | "updatedAt": "2016-01-03T07:50:21.334Z", 13 | "track": { 14 | "providerId": "r9gz0Z9yV1k", 15 | "provider": "youtube", 16 | "duration": 197, 17 | "title": "I'm Just a Kid - Simple Plan lyrics", 18 | "artist": "sabrina01021997", 19 | "url": "https://youtu.be/r9gz0Z9yV1k" 20 | }, 21 | "user": { 22 | "name": "test_user_2", 23 | "displayName": "test_user_2", 24 | "providerId": "93854453", 25 | "provider": "twitch" 26 | } 27 | } 28 | } 29 | ``` 30 | 31 | Resumes the current playing queue item in the current user's channel. 32 | 33 | **HTTP Request** 34 | 35 | `POST https://api.nightbot.tv/1/song_requests/queue/play` 36 | 37 | **Scope** 38 | 39 | `song_requests_queue` 40 | -------------------------------------------------------------------------------- /includes/song_requests/queue/_post_skip.md: -------------------------------------------------------------------------------- 1 | ## Skip current queue item 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/song_requests/queue/skip" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "item": { 10 | "_id": "5688d2bdc93762323f402b9d", 11 | "createdAt": "2016-01-03T07:50:21.334Z", 12 | "updatedAt": "2016-01-03T07:50:21.334Z", 13 | "track": { 14 | "providerId": "r9gz0Z9yV1k", 15 | "provider": "youtube", 16 | "duration": 197, 17 | "title": "I'm Just a Kid - Simple Plan lyrics", 18 | "artist": "sabrina01021997", 19 | "url": "https://youtu.be/r9gz0Z9yV1k" 20 | }, 21 | "user": { 22 | "name": "test_user_2", 23 | "displayName": "test_user_2", 24 | "providerId": "93854453", 25 | "provider": "twitch" 26 | } 27 | } 28 | } 29 | ``` 30 | 31 | Skips the current playing queue item in the current user's channel. 32 | 33 | **HTTP Request** 34 | 35 | `POST https://api.nightbot.tv/1/song_requests/queue/skip` 36 | 37 | **Scope** 38 | 39 | `song_requests_queue` 40 | -------------------------------------------------------------------------------- /includes/spam_protection/_get.md: -------------------------------------------------------------------------------- 1 | ## Get filters 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/spam_protection" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "filters": [ 10 | { 11 | "enabled": true, 12 | "length": 600, 13 | "blacklist": "◕_◕*\nᴘɪᴢᴢᴀ\nˢʷᵉᵃʳ", 14 | "message": "", 15 | "silent": false, 16 | "exemptUserLevel": "subscriber", 17 | "_type": "blacklist", 18 | "_name": "Blacklist Words/Phrases", 19 | "_description": "This filter allows you to timeout custom words, phrases, and patterns.", 20 | "_docs": "https://docs.nightbot.tv/spam-protection/blacklist" 21 | }, 22 | ... 23 | ] 24 | } 25 | ``` 26 | 27 | Gets the current API user's spam protection filters list 28 | 29 | **HTTP Request** 30 | 31 | `GET https://api.nightbot.tv/1/spam_protection` 32 | 33 | **Scope** 34 | 35 | `spam_protection` -------------------------------------------------------------------------------- /includes/spam_protection/_get_type.md: -------------------------------------------------------------------------------- 1 | ## Get filter by type 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/spam_protection/blacklist" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "filter": { 10 | "enabled": true, 11 | "length": 600, 12 | "blacklist": "◕_◕*\nᴘɪᴢᴢᴀ\nˢʷᵉᵃʳ", 13 | "message": "", 14 | "silent": false, 15 | "exemptUserLevel": "subscriber", 16 | "_type": "blacklist", 17 | "_name": "Blacklist Words/Phrases", 18 | "_description": "This filter allows you to timeout custom words, phrases, and patterns.", 19 | "_docs": "https://docs.nightbot.tv/spam-protection/blacklist" 20 | } 21 | } 22 | ``` 23 | 24 | Looks up a spam protection filter by type 25 | 26 | **HTTP Request** 27 | 28 | `GET https://api.nightbot.tv/1/spam_protection/:type` 29 | 30 | **Scope** 31 | 32 | `spam_protection` -------------------------------------------------------------------------------- /includes/spam_protection/_introduction.md: -------------------------------------------------------------------------------- 1 | # Spam Protection 2 | 3 | The spam protection endpoints allow you to view, edit, enable, and disable spam protection filters. 4 | 5 | ## Filter Resource 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 |
FieldsTypeDescription
_limitMinnumber, optionalIf the filter contains a limit option, this defines its minimum value
_limitMaxnumber, optionalIf the filter contains a limit option, this defines its maximum value
_namestringThe spam protection filter name
_typeenumThe spam protection filter type
blackliststring, optionalNew-line delimited list of blacklisted phrases. Wildcards can be used (`*`). RegEx is also supported (`~/[pattern]/[flags]`). Only can be used with filters supporting a blacklist.
enabledbooleanThe status of the filter. If true, the filter is enabled. If false, the filter is disabled and is nonfunctional.
exemptUserLevelenumThe userlevel required to exempt from the filter
lengthnumberThe length of time in seconds that Nightbot will timeout users for if detected by the filter
limitnumber, optionalThe barrier at which the filter should timeout users, should the filter have one.
messagestringThe timeout message given to a user when they are timed out (if filter is not silenced). If empty string, defaults to Duke Nukem quotes.
silentbooleanIf true, the filter will not emit a message to chat telling to user why they were timed out. If false, the filter is will emit a message.
whiteliststring, optionalNew-line delimited list of whitelisted phrases. For the link whitelist this parses hostnames (like `youtube.com` unless wildcards or regex is used). Wildcards can be used (`*`). RegEx is also supported (`~/[pattern]/[flags]`). Only can be used with filters supporting a whitelist.
78 | -------------------------------------------------------------------------------- /includes/spam_protection/_put_type.md: -------------------------------------------------------------------------------- 1 | ## Edit filter by type 2 | 3 | ```cURL 4 | curl -X PUT "https://api.nightbot.tv/1/spam_protection/blacklist" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "message=testing" 7 | 8 | { 9 | "status": 200, 10 | "filter": { 11 | "enabled": true, 12 | "length": 600, 13 | "blacklist": "◕_◕*\nᴘɪᴢᴢᴀ\nˢʷᵉᵃʳ", 14 | "message": "testing", 15 | "silent": false, 16 | "exemptUserLevel": "subscriber", 17 | "_type": "blacklist", 18 | "_name": "Blacklist Words/Phrases", 19 | "_description": "This filter allows you to timeout custom words, phrases, and patterns.", 20 | "_docs": "https://docs.nightbot.tv/spam-protection/blacklist" 21 | } 22 | } 23 | ``` 24 | 25 | Edits a spam protection filter by its type. 26 | 27 | **HTTP Request** 28 | 29 | `PUT https://api.nightbot.tv/1/spam_protection/:type` 30 | 31 | **Scope** 32 | 33 | `spam_protection` 34 | 35 | **Body Parameters** 36 | 37 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). `PUT` requests usually require the entire model to be included in the request, but we allow partial updates. 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 |
ParameterTypeRequiredDescription
blackliststringOptionalNew-line delimited list of blacklisted phrases. Wildcards can be used (`*`). RegEx is also supported (`~/[pattern]/[flags]`). Only can be used with filters supporting a blacklist.
enabledbooleanOptionalThe status of the filter. If true, the filter is enabled. If false, the filter is disabled and is nonfunctional.
exemptUserLevelenumOptionalThe userlevel required to exempt from the filter
lengthnumberOptionalThe length of time in seconds that Nightbot will timeout users for if detected by the filter
limitnumberOptionalThe barrier at which the filter should timeout users, should the filter have one. Only can be used with filters supporting a limit.
messagestringOptionalThe timeout message given to a user when they are timed out (if filter is not silenced). If empty string, defaults to Duke Nukem quotes.
silentbooleanOptionalIf true, the filter will not emit a message to chat telling to user why they were timed out. If false, the filter is will emit a message.
whiteliststringOptionalNew-line delimited list of whitelisted phrases. For the link whitelist this parses hostnames (like `youtube.com` unless wildcards or regex is used). Wildcards can be used (`*`). RegEx is also supported (`~/[pattern]/[flags]`). Only can be used with filters supporting a whitelist.
99 | -------------------------------------------------------------------------------- /includes/subscribers/_delete_id.md: -------------------------------------------------------------------------------- 1 | ## Delete subscriber by id 2 | 3 | ```cURL 4 | curl -X DELETE "https://api.nightbot.tv/1/subscribers/56739fb5d0c250946ed67448" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200 9 | } 10 | ``` 11 | 12 | Deletes a subscriber by id 13 | 14 | **HTTP Request** 15 | 16 | `DELETE https://api.nightbot.tv/1/subscribers/:id` 17 | 18 | **Scope** 19 | 20 | `subscribers` -------------------------------------------------------------------------------- /includes/subscribers/_get.md: -------------------------------------------------------------------------------- 1 | ## Get subscribers 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/subscribers" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "_total": 30, 9 | "status": 200, 10 | "subscribers": [ 11 | { 12 | "_id": "56739fb5d0c250946ed67448", 13 | "createdAt": "2015-12-18T05:55:01.458Z", 14 | "updatedAt": "2015-12-18T05:55:01.458Z", 15 | "provider": "twitch", 16 | "providerId": "96837452", 17 | "name": "test_user", 18 | "displayName": "Test_User" 19 | }, 20 | ... 21 | ] 22 | } 23 | ``` 24 | 25 | Gets the current API user's subscribers list 26 | 27 | **HTTP Request** 28 | 29 | `GET https://api.nightbot.tv/1/subscribers` 30 | 31 | **Scope** 32 | 33 | `subscribers` 34 | 35 | **Query String Parameters** 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 |
ParameterTypeRequiredDescription
limitnumberOptionalThe is the maximum amount of subscribers to return in the request (minimum 1, maximum 100)
offsetnumberOptionalThis is the subscriber offset count that is used for pagination
qstringOptionalA displayName to search for (case insensitive)
-------------------------------------------------------------------------------- /includes/subscribers/_get_id.md: -------------------------------------------------------------------------------- 1 | ## Get subscriber by id 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/subscribers/56739fb5d0c250946ed67448" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "subscriber": { 10 | "_id": "56739fb5d0c250946ed67448", 11 | "createdAt": "2015-12-18T05:55:01.458Z", 12 | "updatedAt": "2015-12-18T05:55:01.458Z", 13 | "provider": "twitch", 14 | "providerId": "96837452", 15 | "name": "test_user", 16 | "displayName": "Test_User" 17 | } 18 | } 19 | ``` 20 | 21 | Looks up a subscriber by id 22 | 23 | **HTTP Request** 24 | 25 | `GET https://api.nightbot.tv/1/subscribers/:id` 26 | 27 | **Scope** 28 | 29 | `subscribers` 30 | -------------------------------------------------------------------------------- /includes/subscribers/_introduction.md: -------------------------------------------------------------------------------- 1 | # Subscribers 2 | 3 | The subscribers endpoints allow you to view, add, edit, and remove channel subscribers. Subscribers can be granted extra permission for commands and spam protection. 4 | 5 | This subscribers list complements any existing paid subscription service already existing. Twitch/YouTube only give paid subscription programs to some of the broadcasters, leaving many users without a subscription program. Other third party platforms may offer subscription services that offset the need for a subscription program for these affected users. 6 | 7 | ## Subscriber Resource 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 |
FieldsTypeDescription
_idstringsubscriber id
createdAtdateThe time the subscriber was added
displayNamestringUser display name
namestringUser unique name
providerenumThe auth provider for the subscriber (twitch, youtube, trovo, noice, soop)
providerIdstringThe unique id for this user at the auth provider
updatedAtdateThe last time the subscriber was updated
55 | -------------------------------------------------------------------------------- /includes/subscribers/_post.md: -------------------------------------------------------------------------------- 1 | ## Add new subscriber 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/subscribers" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "name=test_user" 7 | 8 | { 9 | "status": 200, 10 | "subscriber": { 11 | "_id": "56739fb5d0c250946ed67448", 12 | "createdAt": "2015-12-18T05:55:01.458Z", 13 | "updatedAt": "2015-12-18T05:55:01.458Z", 14 | "provider": "twitch", 15 | "providerId": "96837452", 16 | "name": "test_user", 17 | "displayName": "Test_User" 18 | } 19 | } 20 | ``` 21 | 22 | Adds a new subscriber to the current user's channel 23 | 24 | **HTTP Request** 25 | 26 | `POST https://api.nightbot.tv/1/subscribers` 27 | 28 | **Scope** 29 | 30 | `subscribers` 31 | 32 | **Body Parameters** 33 | 34 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 |
ParameterTypeRequiredDescription
namestringRequiredThis is the username of the person you wish to add as a subscriber. In the case of YouTube, it would be the user's YouTube channel URL.
54 | -------------------------------------------------------------------------------- /includes/timers/_delete_id.md: -------------------------------------------------------------------------------- 1 | ## Delete timer by id 2 | 3 | ```cURL 4 | curl -X DELETE "https://api.nightbot.tv/1/timers/568a4d15df4510b03deb65fc" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200 9 | } 10 | ``` 11 | 12 | Deletes a timer by id 13 | 14 | **HTTP Request** 15 | 16 | `DELETE https://api.nightbot.tv/1/timers/:id` 17 | 18 | **Scope** 19 | 20 | `timers` -------------------------------------------------------------------------------- /includes/timers/_get.md: -------------------------------------------------------------------------------- 1 | ## Get timers 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/timers" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "_total": 1, 9 | "status": 200, 10 | "timers": [ 11 | { 12 | "_id": "568a4d15df4510b03deb65fc", 13 | "createdAt": "2016-01-04T10:44:37.440Z", 14 | "updatedAt": "2016-01-04T10:44:37.440Z", 15 | "name": "test", 16 | "message": "test", 17 | "interval": "*/15 * * * *", 18 | "nextRunAt": "1970-01-01T00:00:00.000Z", 19 | "lines": 2, 20 | "enabled": true 21 | }, 22 | ... 23 | ] 24 | } 25 | ``` 26 | 27 | Gets the current API user's timers list 28 | 29 | **HTTP Request** 30 | 31 | `GET https://api.nightbot.tv/1/timers` 32 | 33 | **Scope** 34 | 35 | `timers` -------------------------------------------------------------------------------- /includes/timers/_get_id.md: -------------------------------------------------------------------------------- 1 | ## Get timer by id 2 | 3 | ```cURL 4 | curl -X GET "https://api.nightbot.tv/1/timers/568a4d15df4510b03deb65fc" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" 6 | 7 | { 8 | "status": 200, 9 | "timer": { 10 | "_id": "568a4d15df4510b03deb65fc", 11 | "createdAt": "2016-01-04T10:44:37.440Z", 12 | "updatedAt": "2016-01-04T10:44:37.440Z", 13 | "name": "test", 14 | "message": "test", 15 | "interval": "*/15 * * * *", 16 | "nextRunAt": "1970-01-01T00:00:00.000Z", 17 | "lines": 2, 18 | "enabled": true 19 | } 20 | } 21 | ``` 22 | 23 | Looks up a timer by id 24 | 25 | **HTTP Request** 26 | 27 | `GET https://api.nightbot.tv/1/timers/:id` 28 | 29 | **Scope** 30 | 31 | `timers` -------------------------------------------------------------------------------- /includes/timers/_introduction.md: -------------------------------------------------------------------------------- 1 | # Timers 2 | 3 | The timers endpoints allow you to view, add, edit, and remove channel timers. 4 | 5 | ## Timer Resource 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 |
FieldsTypeDescription
_idstringThe timer's unique ID
createdAtdateThe time the timer was created
enabledbooleanThe status of the timer. A value of true means the timer is enabled, while false means the timer is disabled and will not execute.
intervalstringThe timer interval in cron syntax. Minimum interval is once per 5 minutes.
linesnumberThis is the minimum amount of chat lines per 5 minutes required to activate the timer. This is useful in slow chats to prevent Nightbot from spamming in an empty channel.
messagestringThe message Nightbot sends to chat when the command is called. It can contain variables for extra functionality.
namestringThe timer name (has no real significance but gives you a quick reference to what the timer does)
nextRunAtdateThe next scheduled time the timer will execute
updatedAtdateThe last time the timer was updated
63 | -------------------------------------------------------------------------------- /includes/timers/_post.md: -------------------------------------------------------------------------------- 1 | ## Add new timer 2 | 3 | ```cURL 4 | curl -X POST "https://api.nightbot.tv/1/timers" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "message=test%20message" \ 7 | -d "interval=*%2F15%20*%20*%20*%20*" \ 8 | -d "lines=5" \ 9 | -d "name=test" 10 | 11 | { 12 | "status": 200, 13 | "command": { 14 | "createdAt": "2016-01-04T05:26:27.593Z", 15 | "updatedAt": "2016-01-04T05:26:27.593Z", 16 | "name": "test", 17 | "message": "test message", 18 | "_id": "568a02834184d1a07660f380", 19 | "interval": "*/15 * * * *", 20 | "nextRunAt": "1970-01-01T00:00:00.000Z", 21 | "lines": 2, 22 | "enabled": true 23 | } 24 | } 25 | ``` 26 | 27 | Adds a new timer to the current user's channel 28 | 29 | **HTTP Request** 30 | 31 | `POST https://api.nightbot.tv/1/timers` 32 | 33 | **Scope** 34 | 35 | `timers` 36 | 37 | **Body Parameters** 38 | 39 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 |
ParameterTypeRequiredDescription
enabledbooleanOptionalThe status of the timer. A value of true means the timer is enabled, while false means the timer is disabled and will not execute.
intervalstringRequiredThe timer interval in cron syntax. Minimum interval is once per 5 minutes.
linesnumberRequiredThis is the minimum amount of chat lines per 5 minutes required to activate the timer. This is useful in slow chats to prevent Nightbot from spamming in an empty channel.
messagestringRequiredThe message to send to chat. It can contain variables for extra functionality. Maximum length: 400 characters
namestringRequiredThe timer name (has no real significance but gives you a quick reference to what the timer does)
-------------------------------------------------------------------------------- /includes/timers/_put_id.md: -------------------------------------------------------------------------------- 1 | ## Edit timer by id 2 | 3 | ```cURL 4 | curl -X PUT "https://api.nightbot.tv/1/timers/568a02834184d1a07660f380" \ 5 | -H "Authorization: Bearer 4fb1fed8889ec9d1c319d5b3c9a54b23" \ 6 | -d "name=testing" 7 | 8 | { 9 | "status": 200, 10 | "timer": { 11 | "createdAt": "2016-01-04T05:26:27.593Z", 12 | "updatedAt": "2016-01-04T05:26:27.593Z", 13 | "name": "testing", 14 | "message": "test message", 15 | "_id": "568a02834184d1a07660f380", 16 | "interval": "*/15 * * * *", 17 | "nextRunAt": "1970-01-01T00:00:00.000Z", 18 | "lines": 2, 19 | "enabled": true 20 | } 21 | } 22 | ``` 23 | 24 | Edits a timer by its id. 25 | 26 | **HTTP Request** 27 | 28 | `PUT https://api.nightbot.tv/1/timers/:id` 29 | 30 | **Scope** 31 | 32 | `timers` 33 | 34 | **Body Parameters** 35 | 36 | The following parameters can be sent as a URL encoded string or JSON (using the appropriate `Content-Type` header). `PUT` requests usually require the entire model to be included in the request, but we allow partial updates. 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 |
ParameterTypeRequiredDescription
enabledbooleanOptionalThe status of the timer. A value of true means the timer is enabled, while false means the timer is disabled and will not execute.
intervalstringOptionalThe timer interval in cron syntax. Minimum interval is once per 5 minutes.
linesnumberOptionalThis is the minimum amount of chat lines per 5 minutes required to activate the timer. This is useful in slow chats to prevent Nightbot from spamming in an empty channel.
messagestringOptionalThe message to send to chat. It can contain variables for extra functionality. Maximum length: 400 characters
namestringOptionalThe timer name (has no real significance but gives you a quick reference to what the timer does)
-------------------------------------------------------------------------------- /index.html.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Nightbot API Reference 3 | 4 | includes: 5 | - errors 6 | - userlevels 7 | - oauth/introduction 8 | - oauth/basic_steps 9 | - oauth/scopes 10 | - oauth/auth_code_flow 11 | - oauth/implicit_flow 12 | - oauth/refreshing_tokens 13 | - oauth/revoking_tokens 14 | - channel/introduction 15 | - channel/get 16 | - channel/post_join 17 | - channel/post_part 18 | - channel/post_send 19 | - commands/introduction 20 | - commands/get 21 | - commands/post 22 | - commands/get_id 23 | - commands/put_id 24 | - commands/delete_id 25 | - commands/default/get 26 | - commands/default/get_name 27 | - commands/default/put_name 28 | - me/introduction 29 | - me/get 30 | - regulars/introduction 31 | - regulars/get 32 | - regulars/post 33 | - regulars/get_id 34 | - regulars/delete_id 35 | - song_requests/introduction 36 | - song_requests/get 37 | - song_requests/put 38 | - song_requests/playlist/get 39 | - song_requests/playlist/post 40 | - song_requests/playlist/delete 41 | - song_requests/playlist/post_import 42 | - song_requests/playlist/get_id 43 | - song_requests/playlist/delete_id 44 | - song_requests/queue/get 45 | - song_requests/queue/post 46 | - song_requests/queue/delete 47 | - song_requests/queue/post_play 48 | - song_requests/queue/post_pause 49 | - song_requests/queue/post_skip 50 | - song_requests/queue/get_id 51 | - song_requests/queue/delete_id 52 | - song_requests/queue/post_id_promote 53 | - spam_protection/introduction 54 | - spam_protection/get 55 | - spam_protection/get_type 56 | - spam_protection/put_type 57 | - subscribers/introduction 58 | - subscribers/get 59 | - subscribers/post 60 | - subscribers/get_id 61 | - subscribers/delete_id 62 | - timers/introduction 63 | - timers/get 64 | - timers/post 65 | - timers/get_id 66 | - timers/put_id 67 | - timers/delete_id 68 | 69 | language_tabs: 70 | - cURL 71 | 72 | toc_footers: 73 | - Contribute to these docs 74 | - (Docs Powered by Slate) 75 | 76 | search: true 77 | --- 78 | 79 | # Introduction 80 | 81 | Nightbot provides a simple and extensible JSON REST API to integrate Nightbot into third party applications and services. 82 | 83 | This API Reference will provide information on all publicly available endpoints and how to interact with them. 84 | --------------------------------------------------------------------------------