├── sticky.md ├── README.md ├── connection.md ├── misc.md ├── poll.md ├── moderation.md ├── giveaway.md └── user.md /sticky.md: -------------------------------------------------------------------------------- 1 | # Sticky (MOTD) Commands 2 | 3 | **Table of Contents** 4 | 5 | - [Create Sticky (Admin)](#create-sticky-admin) 6 | 7 | The sticky message is basically a MOTD (Message of the day) which shows up at the top of the Website UI. 8 | 9 | #### Create Sticky (Admin) 10 | 11 | To set the sticky message you must be an admin and send this message to the server: 12 | 13 | ```javascript 14 | 5:::{ 15 | "name":"message", 16 | "args":[ 17 | { 18 | "method":"motdMsg", 19 | "params":{ 20 | "channel":"CHANNEL", 21 | "name":"USERNAME", 22 | "nameColor":"hexcode for color", 23 | "text":"Text of sticky message", 24 | "time":"2015-08-16T08:36:45.529Z" 25 | } 26 | } 27 | ] 28 | } 29 | ``` 30 | 31 | The chat server will send the following message to the channel, this message will be sent to each user on login. 32 | 33 | ```javascript 34 | 5:::{ 35 | "name":"message", 36 | "args":[ 37 | { 38 | "method":"motdMsg", 39 | "params":{ 40 | "channel":"CHANNEL", 41 | "name":"USERNAME", 42 | "nameColor":"hexcode for color", 43 | "text":"Text of sticky message", 44 | "time":"Timestamp in Epoch", 45 | "image":"path to channel owner image" 46 | } 47 | } 48 | ] 49 | } 50 | ``` 51 | 52 | To remove a sticky message just send the same motdMsg command with an empty text field. Users will also recieve another motdMsg with empty text. 53 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Hitbox-Chat-Doc 2 | 3 | ### DEPRECATED 4 | 5 | I now work on the [official documentation](http://developers.hitbox.tv/), so please use that. This document is deprecated. 6 | 7 | *README* - Please read the [connection](connection.md) doc (Notably the Message Format) as you most likely need to encapsulate the WebSocket messages. 8 | 9 | hitbox Web API: https://github.com/Hitakashi/Hitbox-API 10 | 11 | Most headers will contain the lowest role that can access or see the command. 12 | 13 | | Role | Description | 14 | | ---- | ---- | 15 | | guest | You are a unregistered user. You cannot write in chat and any messages you send will be dropped. User list is also disallowed. | 16 | | anon | You are a normal viewer. You write and see the user list. **Strict** messages/second limits apply. Duplicate messages are disallowed. | 17 | | user | You are a moderator. You can kick/ban other users, set slow and sub mode but cannot IP ban a user. | 18 | | admin | You have full permission in chat. You can add/remove moderators and IP ban a user.* | 19 | 20 | | chatMsg/infoMsg Role | Description | 21 | | ---- | ---- | 22 | | isFollower | If this user is following this channel. | 23 | | isSubscriber | If this user is subscribed to this channel. | 24 | | isOwner | If this is the channel owner, If so you can get the image of the owner in the "image" key. | 25 | | isStaff | If this user is a member of the hitbox staff and has admin rights | 26 | | isCommunity | If this user is a hitbox Ambassador and has admin rights | 27 | 28 | [*] Any user that is admin but isn't staff/community and does not have the owner flag is an editor. 29 | -------------------------------------------------------------------------------- /connection.md: -------------------------------------------------------------------------------- 1 | # How to connect to hitbox Chat. 2 | 3 | **Table of Contents** 4 | 5 | - [Pre-Server Connection (Step 1)](#pre-server-connection-step-1) 6 | - [Websocket ID (Step 2)](#websocket-id-step-2) 7 | - [Server Connection (Step 3)](#server-connection-step-3) 8 | - [Limits](#limits) 9 | - [Post-Server Connection](#post-server-connection) 10 | 11 | #### Pre-Server Connection (Step 1) 12 | 13 | To start connecting to hitbox chat you should first initiate a HTTP GET request to http://api.hitbox.tv/chat/servers the result should be the following Json Object 14 | 15 | ```javascript 16 | [ 17 | { 18 | "server_ip":"ec2-54-91-252-98.compute-1.amazonaws.com" 19 | }, 20 | { 21 | "server_ip":"ec2-54-87-101-9.compute-1.amazonaws.com" 22 | }, 23 | { 24 | "server_ip":"ec2-54-221-0-139.compute-1.amazonaws.com" 25 | }, 26 | { 27 | "server_ip":"ec2-54-211-95-56.compute-1.amazonaws.com" 28 | }, 29 | { 30 | "server_ip":"ec2-54-87-229-245.compute-1.amazonaws.com" 31 | } 32 | ] 33 | ``` 34 | 35 | You can pick whatever server from the response, but you should never save the address. The servers are ever changing and getting it via the API is the safest method. 36 | 37 | At this point you should also get your [auth token](https://github.com/Hitakashi/Hitbox-API/blob/master/auth/login.md#post-authtoken) for the user unless you are planning to login as a guest. 38 | 39 | If you're using a Socket.IO v0.9.17, The following steps shouldn't be necessary as it's handled by the library. 40 | 41 | #### Websocket ID (Step 2) 42 | 43 | Once you get the server address from above, you should append `/socket.io/1/` to the address. After that you need to send a HTTP GET request to that address, for example http://ec2-54-87-229-245.compute-1.amazonaws.com/socket.io/1/ which will return the following text. 44 | 45 | ```text 46 | 7_wKSaZndijMFrJYCziZ:60:60:websocket 47 | ``` 48 | 49 | You then need to get everything before the first colon : which will be your connection ID. Ex: `7_wKSaZndijMFrJYCziZ` 50 | 51 | #### Server Connection (Step 3) 52 | 53 | Now you can get on to actually connecting with all the previous information. You should initiate a WebSocket connection to the finalized WS URL `ws://ec2-54-87-229-245.compute-1.amazonaws.com/socket.io/1/websocket/7_wKSaZndijMFrJYCziZ` 54 | 55 | If you cannot connect after 8 seconds you should grab another server from Step 1 and as a precaution get a new Connection ID from Step 2. 56 | 57 | #### Limits 58 | 59 | There are limits on how many connections can be made from one IP/one user within a time frame. The same applies to chat messages and all other functions. More information will be provided in the loginMsg doc. 60 | 61 | #### Post-Server Connection 62 | 63 | Once you are connected to the server you should recieve a `1::`, after that you need to send a joinChannel message along with whatever else you want. You will also recieve a `2::` every so often and should respond with a `2::` 64 | -------------------------------------------------------------------------------- /misc.md: -------------------------------------------------------------------------------- 1 | # Miscellaneous Commands 2 | 3 | **Table of Contents** 4 | 5 | - [Stream Resource Update](#stream-resource-update) 6 | - [Host Mode Update](#host-mode-update) 7 | - [Viewer Count Server](#viewer-count-server) 8 | 9 | #### Stream Resource Update 10 | 11 | This message is sent whenever the stream title or game is updated. 12 | 13 | ```javascript 14 | 5:::{ 15 | "name":"message", 16 | "args":[ 17 | { 18 | "method":"serverMsg", 19 | "params":{ 20 | "channel":"CHANNEL", 21 | "text":{ 22 | "media":{ 23 | "category_id":"933", 24 | "category_name":"Blacklight Retribution", 25 | "category_name_short":null, 26 | "category_seo_key":"blacklight-retribution", 27 | "category_viewers":"0", 28 | "category_media_count":"1", 29 | "category_channels":null, 30 | "category_logo_small":null, 31 | "category_logo_large":"/static/img/games/2578159-box_blr.png", 32 | "category_updated":"2015-08-15 02:10:58", 33 | "media_status":"This is a stream title!", 34 | "media_category_id":"933" 35 | } 36 | }, 37 | "type":"resourceUpdate", 38 | "time":1439714353 39 | } 40 | } 41 | ] 42 | } 43 | ``` 44 | 45 | #### Host Mode Update 46 | 47 | This message is sent whenever a host update has occured. 48 | 49 | ```javascript 50 | 5:::{ 51 | "name":"message", 52 | "args":[ 53 | { 54 | "method":"serverMsg", 55 | "params":{ 56 | "channel":"hitakashi", 57 | "text":{ 58 | "media":{ 59 | 60 | } 61 | }, 62 | "type":"hostModeUpdate", 63 | "mode":"on", 64 | "time":1439714454 65 | } 66 | } 67 | ] 68 | } 69 | ``` 70 | 71 | The media object contains an exact copy of the [Media API](https://github.com/Hitakashi/Hitbox-API/blob/master/media/live.md#get-medialivechannel) for the channel you're hosting. 72 | 73 | When you turn host mode off, It sends the same message with the media object as your own channel and `mode` set to `off` 74 | 75 | #### Viewer Count Server 76 | 77 | This is a seperate server from from the chat server which returns infoMsg with viewer counts. 78 | 79 | To get started you need to get one server from the [Player Server API](http://www.hitbox.tv/api/player/server). Then get `wsUrl`, `wsChannel`, `wsToken`, `userName` and `uuid` from plugins->pingback object* on the [Live Player API](https://github.com/Hitakashi/Hitbox-API/blob/master/player/player.md#get-playerconfiglivemedia_id). 80 | 81 | [*] It looks like the only required field in the joinChannel message is the channel. So you can either fill the whole message out or just send one with the channel filled out. 82 | 83 | Once you have those values you can initiate a WebSocket connection to `wsUrl` and send the following message: 84 | 85 | You DO NOT add 'name' or 'args' values like all the other messages. 86 | 87 | ```javascript 88 | { 89 | "method":"joinChannel", 90 | "params":{ 91 | "channel":"", 92 | "name":"", 93 | "token":"", 94 | "country":"", 95 | "uuid":"", 96 | "isSubscriber":"false", 97 | "isFollower":"false", 98 | "embed":"false", 99 | "referrer":"" 100 | } 101 | } 102 | ``` 103 | 104 | `channel` = `wsChannel` 105 | 106 | `name` = `userName` 107 | 108 | `token` = `wsToken` 109 | 110 | `uuid` = `uuid` 111 | 112 | You will then recieve the following message every time the viewer counts are changed. 113 | 114 | ```javascript 115 | { 116 | "method":"infoMsg", 117 | "params":{ 118 | "channel":"hitakashi", 119 | "viewers":1, 120 | "subscribers":0, 121 | "followers":1, 122 | "registered":1, 123 | "embed":0, 124 | "online":false 125 | } 126 | } 127 | ``` 128 | -------------------------------------------------------------------------------- /poll.md: -------------------------------------------------------------------------------- 1 | # Poll Commands 2 | 3 | **Table of Contents** 4 | 5 | - [Start Poll (Admin)](#start-poll-admin) 6 | - [Poll Info (Guest)](#poll-info-guest) 7 | - [Poll Vote (Anon)](#poll-vote-anon) 8 | - [Pause/Restart Poll (Admin)](#pauserestart-poll-admin) 9 | - [End Poll (Admin)](#end-poll-admin) 10 | 11 | A poll can only be created by a chat admin. It's possible to create a poll and giveaway but the website UI will only show the latest. 12 | 13 | #### Start Poll (Admin) 14 | 15 | To start a poll you must be an admin and send the following command. 16 | 17 | ```javascript 18 | 5:::{ 19 | "name":"message", 20 | "args":[ 21 | { 22 | "method":"createPoll", 23 | "params":{ 24 | "channel":"CHANNEL", 25 | "question":"Question to ask", 26 | "choices":[ 27 | { 28 | "text":"Answer 1" 29 | }, 30 | { 31 | "text":"Answer 2" 32 | }, 33 | ... Up to ten choices 34 | ], 35 | "subscriberOnly":true/false, 36 | "followerOnly":true/false, 37 | "start_time":"2015-08-16T07:57:43.131Z", 38 | "nameColor":"HEXCOLOR" 39 | } 40 | } 41 | ] 42 | } 43 | ``` 44 | You can decide if it's open to only followers or subscribers by toggling the flags. 45 | 46 | This will start the poll, add it to the website UI and you will recieve the following message in the channel: 47 | 48 | #### Poll Info (Guest) 49 | 50 | ```javascript 51 | 5:::{ 52 | "name":"message", 53 | "args":[ 54 | { 55 | "method":"pollMsg", 56 | "params":{ 57 | "channel":"CHANNEL", 58 | "question":"Question", 59 | "choices":[ 60 | { 61 | "text":"Answer 1", 62 | "votes":12 63 | }, 64 | { 65 | "text":"Answer 2", 66 | "votes":40 67 | } 68 | ], 69 | "start_time":"2015-08-16T07:57:43.131Z", 70 | "status":"started", 71 | "voters":[ 72 | "List of", 73 | "voters" 74 | ], 75 | "nameColor":"000000", 76 | "subscriberOnly":false, 77 | "followerOnly":false, 78 | "votes":52 79 | } 80 | } 81 | ] 82 | } 83 | ``` 84 | 85 | #### Poll Vote (Anon) 86 | 87 | ```javascript 88 | 5:::{ 89 | "name":"message", 90 | "args":[ 91 | { 92 | "method":"voteMsg", 93 | "params":{ 94 | "name":"USERNAME", 95 | "channel":"CHANNEL", 96 | "choice":"Vote Choice Integer. Starts at 0 for choice 1", 97 | "token":"USERS_AUTH_TOKEN" 98 | } 99 | } 100 | ] 101 | } 102 | ``` 103 | 104 | After you send a voteMsg, the server will broadcast a [pollMsg](#Poll-Info-Guest) to all anon and above users. 105 | 106 | #### Pause/Restart Poll (Admin) 107 | 108 | To pause a poll you must be an admin and send the following message. 109 | 110 | ```javascript 111 | 5:::{ 112 | "name":"message", 113 | "args":[ 114 | { 115 | "method":"pausePoll", 116 | "params":{ 117 | "channel":"CHANNEL", 118 | "token":"USERS_AUTH_TOKEN" 119 | } 120 | } 121 | ] 122 | } 123 | ``` 124 | 125 | The server will then broadcast a [pollMsg](#Poll-Info-Guest) with the status set to `paused`. This is the last time to get poll results unless the poll is restarted. To restart the poll send the following message. 126 | 127 | ```javascript 128 | 5:::{ 129 | "name":"message", 130 | "args":[ 131 | { 132 | "method":"startPoll", 133 | "params":{ 134 | "channel":"CHANNEL", 135 | "token":"USERS_AUTH_TOKEN" 136 | } 137 | } 138 | ] 139 | } 140 | ``` 141 | 142 | The server will then broadcast a [pollMsg](#Poll-Info-Guest) with the status set to `started`. 143 | 144 | #### End Poll (Admin) 145 | 146 | To end a poll you need to be an admin and send the following message. 147 | 148 | ```javascript 149 | 5:::{ 150 | "name":"message", 151 | "args":[ 152 | { 153 | "method":"endPoll", 154 | "params":{ 155 | "channel":"CHANNEL", 156 | "token":"USERS_AUTH_TOKEN" 157 | } 158 | } 159 | ] 160 | } 161 | ``` 162 | 163 | The server will then send the following message: 164 | 165 | ```javascript 166 | 5:::{ 167 | "name":"message", 168 | "args":[ 169 | { 170 | "method":"pollMsg", 171 | "params":{ 172 | "channel":"CHANNEL", 173 | "status":"ended" 174 | } 175 | } 176 | ] 177 | } 178 | ``` 179 | -------------------------------------------------------------------------------- /moderation.md: -------------------------------------------------------------------------------- 1 | # Moderation Commands 2 | 3 | **Table of Contents** 4 | 5 | - [Timeout a user (User)](#timeout-a-user-user) 6 | - [Ban a user (User)](#ban-a-user-user) 7 | - [IP-Ban a user (Admin)](#ip-ban-a-user-admin) 8 | - [Un-Ban a user (User)](#un-ban-a-user-user) 9 | - [Add a moderator (Broadcaster)](#add-a-moderator-broadcaster) 10 | - [Remove a moderator (Broadcaster)](#remove-a-moderator-broadcaster) 11 | - [Slow Mode/Subscriber Only Mode (User)](#slow-modesubscriber-only-mode-user) 12 | 13 | The moderator/admin commands can of course only be used by moderators and/or admins. 14 | 15 | #### Timeout a user (User) 16 | 17 | To kick a user (ban it temporarily for a specified amount of time) you must be at least a moderator and send the following message to the server: 18 | 19 | ```javascript 20 | 5:::{ 21 | "name":"message", 22 | "args":[ 23 | { 24 | "method":"kickUser", 25 | "params":{ 26 | "channel":"CHANNEL", 27 | "name":"Name of user to timeout", 28 | "token":"Token of moderator", 29 | "timeout":"10" 30 | } 31 | } 32 | ] 33 | } 34 | ``` 35 | 36 | The timeout is in seconds. If everything is correct the chat server sends a infoMsg with `action` set to `kickUser` 37 | 38 | #### Ban a user (User) 39 | 40 | To ban a user so that he/she is unable to write in a chat you must send the following message to the server: 41 | 42 | ```javascript 43 | 5:::{ 44 | "name":"message", 45 | "args":[ 46 | { 47 | "method":"banUser", 48 | "params":{ 49 | "channel":"CHANNEL", 50 | "name":"Name of user to ban" 51 | } 52 | } 53 | ] 54 | } 55 | ``` 56 | 57 | The ban will be announced in the chat via an infoMsg with `action` set to `ban`, it will also send a [userList](./user.md#user-list) and ban list: 58 | 59 | ```javascript 60 | 5:::{ 61 | "name":"message", 62 | "args":[ 63 | { 64 | "method":"banList", 65 | "params":{ 66 | "channel":"CHANNEL", 67 | "data":[ 68 | "test-account", 69 | "test-account-2" 70 | ] 71 | } 72 | } 73 | ] 74 | } 75 | ``` 76 | 77 | This is a list with all the banned user in the chat. When there are banned users you will also get this list when you call the user list. 78 | 79 | #### IP-Ban a user (Admin) 80 | 81 | To IP-Ban a user you must be an admin in the channel. You send the same command for banning but add a flag: 82 | 83 | ```javascript 84 | 5:::{ 85 | "name":"message", 86 | "args":[ 87 | { 88 | "method":"banUser", 89 | "params":{ 90 | "channel":"CHANNEL", 91 | "name":"Name of user to ban", 92 | "token":"Token of admin", 93 | "banIP":true 94 | } 95 | } 96 | ] 97 | } 98 | ``` 99 | 100 | Be careful with IP-Bans, You don't know how many users you can block with it. (Universities often use one public IP) 101 | 102 | #### Un-Ban a user (User) 103 | 104 | To un-ban a user you must be moderator and send the following message to the server: 105 | 106 | ```javascript 107 | 5:::{ 108 | "name":"message", 109 | "args":[ 110 | { 111 | "method":"unbanUser", 112 | "params":{ 113 | "channel":"CHANNEL", 114 | "name":"Name of user to un-ban", 115 | "token":"Token of moderator" 116 | } 117 | } 118 | ] 119 | } 120 | ``` 121 | 122 | #### Add a moderator (Broadcaster) 123 | 124 | To make a user a moderator you must be the broadcaster (No, Editors don't count)* and send the following message to the server: 125 | 126 | * Currently editors can create temporary mods, but the user loses the mod on a refresh. 127 | 128 | ```javascript 129 | 5:::{ 130 | "name":"message", 131 | "args":[ 132 | { 133 | "method":"makeMod", 134 | "params":{ 135 | "channel":"CHANNEL", 136 | "name":"Name of user to mod", 137 | "token":"Token of broadcaster" 138 | } 139 | } 140 | ] 141 | } 142 | ``` 143 | 144 | The result will be announced in a infoMsg with `action` set as `isAdmin`. 145 | 146 | #### Remove a moderator (Broadcaster) 147 | 148 | To remove a moderator you must be the broadcaster (No, Editors don't count) and send the following message to the server: 149 | 150 | ```javascript 151 | 5:::{ 152 | "name":"message", 153 | "args":[ 154 | { 155 | "method":"removeMod", 156 | "params":{ 157 | "channel":"CHANNEL", 158 | "name":"Name of user to unmod", 159 | "token":"Token of broadcaster" 160 | } 161 | } 162 | ] 163 | } 164 | ``` 165 | 166 | The result will be announced in a infoMsg with `action` set as `isAdmin`. 167 | 168 | #### Slow Mode/Subscriber Only Mode (User) 169 | 170 | To set a slow mode in chat (So that every normal user can only post one message every X seconds or only subscribed users can chat) you must be at least moderator and send the following message to the server: 171 | 172 | ```javascript 173 | 5:::{ 174 | "name":"message", 175 | "args":[ 176 | { 177 | "method":"slowMode", 178 | "params":{ 179 | "channel":"CHANNEL", 180 | "time":10, 181 | OR 182 | "subscriber":true, 183 | "rate":0 184 | } 185 | } 186 | ] 187 | } 188 | ``` 189 | Only send rate when your setting sub only mode. It should also only be 0 for now. 190 | 191 | You can (currently) only have slow mode or subscriber mode active at the same time. You can send the subscriber flag as false, but not true while time is greater than 0. 192 | 193 | To disable slow mode send time as 0. To disable subscriber mode toggle the flag. 194 | 195 | The result will be announced in a slowMsg (Identical to infoMsg) with `action` set as `isAdmin`. If you're setting slow mode it will add a `slowTime` variable with its value as the slow time. 196 | -------------------------------------------------------------------------------- /giveaway.md: -------------------------------------------------------------------------------- 1 | # Raffle Commands 2 | 3 | **Table of Contents** 4 | 5 | - [Create a giveaway (Admin)](#create-a-giveaway-admin) 6 | - [Giveaway Info (Guest)](#giveaway-info-guest) 7 | - [Pause a giveaway (Admin)](#pause-a-giveaway-admin) 8 | - [End a giveaway (Admin)](#end-a-giveaway-admin) 9 | - [Resume a giveaway (Admin)](#resume-a-giveaway-admin) 10 | - [Vote in a giveaway (Anon)](#vote-in-a-giveaway-anon) 11 | - [Pick a winner (Admin)](#pick-a-winner-admin) 12 | - [Hide a giveaway (Admin)](#hide-a-giveaway-admin) 13 | - [Cleanup a giveaway (Admin)](#cleanup-a-giveaway-admin) 14 | 15 | A giveaway is like a [poll](./poll.md) but you can pick a winner and have to announce a prize. 16 | 17 | #### Create a giveaway (Admin) 18 | 19 | To create a giveaway you must be an admin and send the following message: 20 | 21 | ```javascript 22 | 5:::{ 23 | "name":"message", 24 | "args":[ 25 | { 26 | "method":"createRaffle", 27 | "params":{ 28 | "channel":"CHANNEL", 29 | "question":"QUESTION", 30 | "prize":"Description of Prize", 31 | "choices":[ 32 | { 33 | "text":"Answer 1" 34 | }, 35 | { 36 | "text":"Answer 2" 37 | } 38 | ], 39 | "subscriberOnly":true/false, 40 | "followerOnly":true/false, 41 | "start_time":"2015-08-16T08:11:34.581Z", 42 | "nameColor":"Hexcode for color" 43 | } 44 | } 45 | ] 46 | } 47 | ``` 48 | 49 | You can decide if the giveaway will only be accessible by followers, subscribers or all users. 50 | 51 | The server will then send a message like this to the channel: 52 | 53 | #### Giveaway Info (Guest) 54 | 55 | ```javascript 56 | 5:::{ 57 | "name":"message", 58 | "args":[ 59 | { 60 | "method":"raffleMsg", 61 | "params":{ 62 | "channel":"CHANNEL", 63 | "question":"QUESTION", 64 | "prize":"Description of Prize", 65 | "choices":[ 66 | { 67 | "text":"Answer 1", 68 | "count":0 69 | }, 70 | { 71 | "text":"Answer 2", 72 | "count":0 73 | } 74 | ], 75 | "start_time":"2015-08-16T08:11:34.581Z", 76 | "status":"started", 77 | "forAdmin":true/false, 78 | "nameColor":"Hexcode for color", 79 | "subscriberOnly":true/false, 80 | "followerOnly":true/false 81 | } 82 | } 83 | ] 84 | } 85 | ``` 86 | 87 | Counts will be removed if you aren't an admin. 88 | 89 | This message is always sent on connection until the giveaway is [cleaned up](#cleanup-a-giveaway-admin). 90 | 91 | #### Pause a giveaway (Admin) 92 | 93 | To pause a giveaway send the following message: 94 | 95 | ```javascript 96 | 5:::{ 97 | "name":"message", 98 | "args":[ 99 | { 100 | "method":"pauseRaffle", 101 | "params":{ 102 | "channel":"CHANNEL" 103 | } 104 | } 105 | ] 106 | } 107 | ``` 108 | 109 | After you send a pauseRaffle, the server will broadcast a [raffleMsg](#Giveaway-Info-Guest) to all anon and above users with the status value set to `paused`. 110 | 111 | ### End a giveaway (Admin) 112 | 113 | To end a giveaway send the following message: 114 | 115 | ```javascript 116 | 5:::{ 117 | "name":"message", 118 | "args":[ 119 | { 120 | "method":"endRaffle", 121 | "params":{ 122 | "channel":"hitakashi" 123 | } 124 | } 125 | ] 126 | } 127 | ``` 128 | 129 | After you send a endRaffle, the server will broadcast a [raffleMsg](#Giveaway-Info-Guest) to all anon and above users with the status value set to `ended`. The giveaway must be in this state to roll a winner. 130 | 131 | 132 | #### Resume a giveaway (Admin) 133 | 134 | You can also resume a giveaway if it's still in a paused state. 135 | 136 | ```javascript 137 | 5:::{ 138 | "name":"message", 139 | "args":[ 140 | { 141 | "method":"startRaffle", 142 | "params":{ 143 | "channel":"CHANNEL" 144 | } 145 | } 146 | ] 147 | } 148 | ``` 149 | 150 | After you send a startRaffle, the server will broadcast a [raffleMsg](#Giveaway-Info-Guest) to all anon and above users with the status value set to `started`. 151 | 152 | #### Vote in a giveaway (Anon) 153 | 154 | To vote in a giveaway a user must send this message to the server: 155 | 156 | ```javascript 157 | 5:::{ 158 | "name":"message", 159 | "args":[ 160 | { 161 | "method":"voteRaffle", 162 | "params":{ 163 | "name":"USERNAME", 164 | "channel":"CHANNEL", 165 | "choice":"Number of answer, starts at 0" 166 | } 167 | } 168 | ] 169 | } 170 | ``` 171 | 172 | After you send a voteRaffle, the server will broadcast a [raffleMsg](#Giveaway-Info-Guest) to all anon and above users. 173 | 174 | #### Pick a winner (Admin) 175 | 176 | To pick a winner you must end the giveaway first and then send the following message: 177 | 178 | ```javascript 179 | 5:::{ 180 | "name":"message", 181 | "args":[ 182 | { 183 | "method":"winnerRaffle", 184 | "params":{ 185 | "channel":"CHANNEL", 186 | "answer":"Number of answer, starts at 0" 187 | } 188 | } 189 | ] 190 | } 191 | ``` 192 | 193 | The server will respond twice the following message, one for all users without the email (with forAdmin set to false) and one for admins (with forAdmin set to true) with the email: 194 | 195 | ```javascript 196 | 5:::{ 197 | "name":"message", 198 | "args":[ 199 | { 200 | "method":"winnerRaffle", 201 | "params":{ 202 | "channel":"CHANNEL", 203 | "winner_name":"Test-Account", 204 | "winner_email":"example@example.com", 205 | "winner_picked":true, 206 | "forAdmin":true, 207 | "answer":"Number of answer, starts at 0" 208 | } 209 | } 210 | ] 211 | } 212 | ``` 213 | 214 | ### Hide a giveaway (Admin) 215 | 216 | To hide a giveaway from the UI send the following message: 217 | 218 | ```javascript 219 | 5:::{ 220 | "name":"message", 221 | "args":[ 222 | { 223 | "method":"hideRaffle", 224 | "params":{ 225 | "channel":"hitakashi" 226 | } 227 | } 228 | ] 229 | } 230 | ``` 231 | 232 | After you send a hideRaffle, the server will broadcast a [raffleMsg](#Giveaway-Info-Guest) to all anon and above users with the `status` set to `hidden`. 233 | 234 | #### Cleanup a giveaway (Admin) 235 | 236 | To end a giveaway send this message to the server: 237 | 238 | ```javascript 239 | 5:::{ 240 | "name":"message", 241 | "args":[ 242 | { 243 | "method":"cleanupRaffle", 244 | "params":{ 245 | "channel":"CHANNEL" 246 | } 247 | } 248 | ] 249 | } 250 | ``` 251 | 252 | After you send a cleanupRaffle, the server will broadcast the following to all users. 253 | 254 | ```javascript 255 | 5:::{ 256 | "name":"message", 257 | "args":[ 258 | { 259 | "method":"raffleMsg", 260 | "params":{ 261 | "status":"delete" 262 | } 263 | } 264 | ] 265 | } 266 | ``` 267 | -------------------------------------------------------------------------------- /user.md: -------------------------------------------------------------------------------- 1 | # General Commands 2 | 3 | **Table of Contents** 4 | 5 | - [Login Command](#login-command) 6 | - [Logout Command](#logout-command) 7 | - [Chat Messages](#chat-messages) 8 | - [Direct Messages](#direct-messages) 9 | - [System Messages](#system-messages) 10 | - [User List](#user-list) 11 | - [User Info](#user-info) 12 | - [Media Log](#media-log) 13 | 14 | 15 | #### Login Command 16 | 17 | To login to the hitbox chat system you need to send the following message: 18 | 19 | ```javascript 20 | 5:::{ 21 | "name":"message", 22 | "args":[ 23 | { 24 | "method":"joinChannel", 25 | "params":{ 26 | "channel":"CHANNEL", 27 | "name":"USERNAME or don't send this", 28 | "token":"Users Auth Token or don't send this", 29 | "isAdmin":false 30 | } 31 | } 32 | ] 33 | } 34 | ``` 35 | 36 | When you don't have a token (You can get a token via the API [here](https://github.com/Hitakashi/Hitbox-API/blob/master/auth/login.md#post-authtoken)) you can login as a guest but cannot send messages or get the user list. 37 | 38 | You should always send a lower case channel name. 39 | 40 | The client must wait until it gets the login confirmation which looks like this: 41 | 42 | ```javascript 43 | 5:::{ 44 | "name":"message", 45 | "args":[ 46 | { 47 | "method":"loginMsg", 48 | "params":{ 49 | "channel":"CHANNEL", 50 | "name":"USERNAME or UnknownSoldier", 51 | "role":"guest, anon, user or admin" 52 | } 53 | } 54 | ] 55 | } 56 | ``` 57 | 58 | The `name` value is the name in the chat. You can customized the casing however you want. When it is "UnknownSoldier" you are logged in as a guest. When you don't get a response in 10 seconds your credentials are either wrong or the chat server is not responding, so disconnect the chat server and try another one or check if your credentials are ok. If you supplied a name and token but your `role` is still "guest", your credentials are incorrect, so you should disconnect the server and check your credentials. You will never get a error message from the chat server. 59 | 60 | The roles can be found in the (README)[./README.md] 61 | 62 | It is important to know that one Socket.IO/Websocket connection can only connect to one channel. You must open a new Socket.io/Websocket connection for every channel you want to connect to. 63 | 64 | After a successful login the chat server sends you a backlog of the latest 6 chat messages in the last X(Confirmation soon) minutes and other info like stick messages, polls or giveaways are running. 65 | 66 | 67 | #### Logout Command 68 | 69 | To logout you can either close the Socket.IO/Websocket connection or send: 70 | 71 | ```javascript 72 | 5:::{ 73 | "name":"message", 74 | "args":[ 75 | { 76 | "method":"partChannel", 77 | "params":{ 78 | "name":"USERNAME or UnknownSoldier" 79 | } 80 | } 81 | ] 82 | } 83 | ``` 84 | 85 | There will be no response but the connection will be closed from the server. 86 | 87 | 88 | #### Chat Messages 89 | 90 | To send a message to the chat use this format. `text` is limited to about 255-300 characters: 91 | 92 | ```javascript 93 | 5:::{ 94 | "name":"message", 95 | "args":[ 96 | { 97 | "method":"chatMsg", 98 | "params":{ 99 | "channel":"CHANNEL", 100 | "name":"USERNAME", 101 | "nameColor":"Hexcode for color, or don't send it.", 102 | "text":"Text of your message" 103 | } 104 | } 105 | ] 106 | } 107 | ``` 108 | If your message was successfully sent to the channel the chat server sends it back to you like this (And every other chat message) 109 | 110 | If your message was rejected by the server due to slow mode or subscriber only, you will get back an infoMsg. 111 | 112 | ```javascript 113 | 5:::{ 114 | "name":"message", 115 | "args":[ 116 | { 117 | "method":"chatMsg", 118 | "params":{ 119 | "channel":"CHANNEL", 120 | "name":"USERNAME", 121 | "nameColor":"Hexcode for color, or don't send it.", 122 | "text":"Text of your message", 123 | "time":EpochTimestamp, 124 | "role":"role in chat", 125 | "isFollower":true/false, 126 | "isSubscriber":true/false, 127 | "isOwner":true/false, 128 | "isStaff":true/false, 129 | "isCommunity":true/false, 130 | "media":true/false, 131 | "image":"Path to channel owner/subscriber image", 132 | "buffer":true, 133 | "buffersent":true 134 | } 135 | } 136 | ] 137 | } 138 | ``` 139 | 140 | `buffer` and `buffersent` are only added when it's a backlog message. The owner will not have isSubscriber but still has access to subscriber emotes. 141 | 142 | 143 | ### Direct Messages 144 | 145 | To send a direct message to another hitbox user you need to send the following message: 146 | 147 | ```javascript 148 | 5:::{ 149 | "name":"message", 150 | "args":[ 151 | { 152 | "method":"directMsg", 153 | "params":{ 154 | "channel":"CHANNEL", 155 | "from":"USERNAME", 156 | "to":"RECIPENT", 157 | "nameColor":"HEXCOLOR", 158 | "text":"This is a direct message." 159 | } 160 | } 161 | ] 162 | } 163 | ``` 164 | 165 | You will then get back a confirmation that the message was sent. You can also get a infoMsg back that you are sending too fast. 166 | 167 | ```javascript 168 | 5:::{ 169 | "name":"message", 170 | "args":[ 171 | { 172 | "method":"infoMsg", 173 | "params":{ 174 | "text":"Direct message to RECIPENT sent.", 175 | "channel":"CHANNEL", 176 | "timestamp":1426785188, 177 | "action":"directmsg" 178 | } 179 | } 180 | ] 181 | } 182 | ``` 183 | 184 | The recipient will then receive the following message: 185 | 186 | ```javascript 187 | 5:::{ 188 | "name":"message", 189 | "args":[ 190 | { 191 | "method":"directMsg", 192 | "params":{ 193 | "from":"SENDER", 194 | "nameColor":"HEXCOLOR", 195 | "text":"This is a direct message.", 196 | "time":1426785188, 197 | "isStaff":false, 198 | "isCommunity":false, 199 | "channel":"CHANNEL SENT FROM", 200 | "type":"info" 201 | } 202 | } 203 | ] 204 | } 205 | ``` 206 | 207 | #### System Messages 208 | 209 | The chat server sends system messages, for example adding or removing a moderator, that have the following format: 210 | 211 | The name field is only sent on ban. 212 | 213 | ```javascript 214 | 5:::{ 215 | "name":"message", 216 | "args":[ 217 | { 218 | "method":"infoMsg", 219 | "params":{ 220 | "text":"Text of your message", 221 | "lang":"view.chat.text.has_been_banned", 222 | "variables":{ 223 | "user":"test" 224 | }, 225 | "channel":"CHANNEL", 226 | "timestamp":EpochTimeStamp, 227 | "name":"USER ACTED UPON", 228 | "action":"Optional, Example ban, kickUser, isAdmin" 229 | } 230 | } 231 | ] 232 | } 233 | ``` 234 | 235 | There is also a special infoMsg for new subscribers that pops up in the website UI (like a poll) 236 | 237 | To change the 'lang' key to one on /translate API, You should change . to _ and _ to -. 238 | 239 | ```javascript 240 | 5:::{ 241 | "name":"message", 242 | "args":[ 243 | { 244 | "method":"infoMsg", 245 | "params":{ 246 | "text":"Test-Account just subscribed to this channel", 247 | "channel":"CHANNEL", 248 | "subscriber":"Test-Account", 249 | "type":"subChannel", 250 | "time":EpochTimeStamp 251 | } 252 | } 253 | ] 254 | } 255 | ``` 256 | 257 | There is also a special chatLog for broadcasters and editors that is sent on multiple actions. (Subscriptions, Followers, Bans, etc) Buffer is only sent on history chatLogs. 258 | 259 | ```javascript 260 | 5:::{ 261 | "name":"message", 262 | "args":[ 263 | { 264 | "method":"chatLog", 265 | "params":{ 266 | "text":"Hitakashi banned Claptrap", 267 | "timestamp":EpochTimeStamp, 268 | "channel":"CHANNEL", 269 | "buffer":true 270 | } 271 | } 272 | ] 273 | } 274 | ``` 275 | 276 | #### User List 277 | 278 | To get the user list of a channel you must be logged in with an authToken and then send this message: 279 | 280 | ```javascript 281 | 5:::{ 282 | "name":"message", 283 | "args":[ 284 | { 285 | "method":"getChannelUserList", 286 | "params":{ 287 | "channel":"CHANNEL" 288 | } 289 | } 290 | ] 291 | } 292 | ``` 293 | 294 | You will then get the following list from the server: 295 | 296 | ```javascript 297 | 5:::{ 298 | "name":"message", 299 | "args":[ 300 | { 301 | "method":"userList", 302 | "params":{ 303 | "channel":"CHANNEL", 304 | "data":{ 305 | "Guests":null, 306 | "admin":["Broadcaster","Staff-Member","Community-Member","Editor"], 307 | "user":["Moderator"], 308 | "anon":["test-account"], 309 | "isFollower":["Moderator","test-account","Staff-Member"], 310 | "isSubscriber":["Staff-Member","test-account"], 311 | "isStaff":["Staff-Member"], 312 | "isCommunity":["Community-Member"] 313 | } 314 | } 315 | } 316 | ] 317 | } 318 | ``` 319 | 320 | The server automatically sends a userList when a chat admin leaves a channel. 321 | 322 | This is the user list for this channel, divided in the different roles and extra flags. Staff members are always listed in `admin`, `isStaff` and `isSubscriber`. Ambassadors are listed in `admin` and `isCommunity`. `Guests` contain an integer of the number of unregistered chatters. 323 | 324 | #### User Info 325 | 326 | To get info for one user send this command: 327 | 328 | ```javascript 329 | 5:::{ 330 | "name":"message", 331 | "args":[ 332 | { 333 | "method":"getChannelUser", 334 | "params":{ 335 | "channel":"CHANNEL", 336 | "name":"Username to query" 337 | } 338 | } 339 | ] 340 | } 341 | ``` 342 | 343 | As a response you should get something like this: 344 | 345 | ```javascript 346 | 5:::{ 347 | "name":"message", 348 | "args":[ 349 | { 350 | "method":"userInfo", 351 | "params":{ 352 | "channel":"CHANNEL", 353 | "name":"Username", 354 | "timestamp":EpochTimeStamp, 355 | "role":"Role of user", 356 | "isFollower":true/false, 357 | "isSubscriber":true/false, 358 | "isOwner":true/false, 359 | "isStaff":true/false, 360 | "isCommunity":true/false 361 | } 362 | } 363 | ] 364 | } 365 | ``` 366 | 367 | If you query a banned user, `role` is set as `banned`, the is flags are removed and there's an added "banned":true value 368 | 369 | #### Media Log 370 | 371 | To get list of media (Currently only images) send this command: 372 | 373 | ```javascript 374 | 5:::{ 375 | "name":"message", 376 | "args":[ 377 | { 378 | "method":"mediaLog", 379 | "params":{ 380 | "channel":"CHANNEL", 381 | "type":"image", 382 | "name":"USERNAME", 383 | "token":"SuperSecret" 384 | } 385 | } 386 | ] 387 | } 388 | ``` 389 | 390 | As a response you should get something like this: 391 | 392 | ```javascript 393 | 5:::{ 394 | "name":"message", 395 | "args":[ 396 | { 397 | "method":"mediaLog", 398 | "params":{ 399 | "channel":"CHANNEL", 400 | "type":"image", 401 | "data":[ 402 | { 403 | "channel":"CHANNEL", 404 | "name":"USERNAME", 405 | "nameColor":"HEXCOLOR", 406 | "time":1444420588, 407 | "url":"https://upload.wikimedia.org/wikipedia/commons/thumb/f/f4/B_menziesii_gnangarra_19.jpg/1280px-B_menziesii_gnangarra_19.jpg", 408 | "size":{ 409 | "x":1280, 410 | "y":960 411 | }, 412 | "proxyUrl":"http://chatimages.hitbox.tv/beb3f3db9673ee63d8ce4256fb2ba36b" 413 | } 414 | ] 415 | } 416 | } 417 | ] 418 | } 419 | ``` 420 | --------------------------------------------------------------------------------