Upstream Messages

Upstream messages are sent one per request; just post the text of the JSON object. Currently the JSON parser is the org.json Java JSON parser, which is fairly accepting of nonstandard JSON, but I may change it in the future so try to submit correct JSON in all requests.

Messages marked as "channel messages" must always include a channelId value, indicating the channel that they are referring to. This is not listed in their tables. Messages with no data (other than type and, if relevant, channelId) will not have a table of fields.

Some messages have a field named callbackKey. This is an arbitrary 16 bit number you can send, and the same number will be contained in the response to your message. This is present because in some cases, you may want to send out several similar messages at once, and the callbackKey lets you figure out which response goes with which request. If you don't need or care, then you can just pass in 0 as the callback key.

Sorry that this list is in such a random order. Trying to get it all down quickly, and I'm not sure the best way to arrange it.

LOGIN

Must be the first message sent. Starts the login process.

LOGIN_SUCCESS, LOGIN_FAILED_NO_SUCH_USER, LOGIN_FAILED_BAD_PASSWORD, LOGIN_FAILED_USER_ALREADY_EXISTS.

UNJOIN_REQUEST

Requests to leave a channel.

UNJOIN.

JOIN_ARCHIVE_REQUEST, JOIN_TAG_ARCHIVE_REQUEST, DETAILS_JOIN_REQUEST

Requests to join a user's archive channel or "user details" channel. These channels exist for each user, whether they are logged in or not, and by joining the channel you can get the information contained within.

ARCHIVE_JOIN, ARCHIVE_NONEXISTANT.

CHAT, ANNOUNCE, ANNOUNCE_TO_PLAYERS

Send a chat message to other users. CHAT is the standard message from one player to the others in the channel. ANNOUNCE is the same, but it is in bold; only admins and channel owners can submit this message. ANNOUNCE_TO_PLAYERS is an announcement that even players can see (usually players in a game do not see CHAT or ANNOUNCE messages).

ROOM_NAMES_REQUEST

Requests the names of one or more rooms, specified by their room ID. When a room name changes, all users on the server are notified, so once you have a room name you don't need to request it again unless you log out and back in.

ROOM_NAMES.

AVATAR_REQUEST

Request a user's avatar data. This probably isn't needed for a HTML-based client; they can just download the avatar directly at http://goserver.gokgs.com/avatars/userName.jpg.

AVATAR.

DETAILS_CHANGE

Change a user's detail. After you join the user's details channel, send this to do the update. Sr. Admins can change anybody's details; otherwise you can only change your own.

SET_PASSWORD

Change a user's password. Only sr. admins can change other people's passwords.

DETAILS_RANK_GRAPH_REQUEST

Request the rank graph data of the user whose channel this is.

DETAILS_RANK_GRAPH.

ROOM_DESC_REQUEST

Request the room description (the big block of text that appears when you first join a room). Like the room name, you will be notified when this changes (even if you aren't in the room), so you only need to request it once.

ROOM_DESC.

JOIN_REQUEST

Request to join the channel that this message is sent to.

JOIN.

CREATE_ROOM_REQUEST

Create a room.

ROOM_CREATE_NAME_TAKEN, ROOM_CREATE_TOO_MANY_ROOMS, ROOM_CREATED.

ROOM_EDIT

Edit room name, description, and flags.

ROOM_ADD_OWNER, ROOM_REMOVE_OWNER

Add or remove a user to the owner list of the room.

CHANNEL_CHANGE_NO_SUCH_USER.

CHANNEL_ADD_ACCESS, CHANNEL_REMOVE_ACCESS

Add or remove a user to the access list of the channel. Used for private rooms, games, etc.

CHANNEL_CHANGE_NO_SUCH_USER.

ACCESS_LIST_REQUEST

Request the list of users who have access to this channel. Can only be made by senior admins and channel owners.

ACCESS_LIST.

CONVO_REQUEST

Request a channel for a private conversation with another user. Does nothing if you already have a channel for this user.

CONVO_JOIN, CONVO_NO_SUCH_USER.

MESSAGE_CREATE

Create a message to leave in another user's mailbox.

MESSAGE_CREATE_NO_USER, MESSAGE_CREATE_CONNECTED (in which case a private convo will be created), MESSAGE_CREATE_FULL, MESSAGE_CREATE_SUCCESS.

MESSAGE_DELETE

Delete a message left for you. It contains a list of messages to delete; if the list is missing, then all messages are deleted.

FRIEND_ADD, FRIEND_REMOVE

Add or remove somebody from one of your four "buddy" lists. admin_track is usable by admins only.

FRIEND_CHANGE_NO_USER, FRIEND_ADD_SUCCESS, FRIEND_REMOVE_SUCCESS.

CHALLENGE_CREATE

Create a challenge.

Sample message:

{
  "type": "CHALLENGE_CREATE",
  "channelId": 4794601,
  "callbackKey": 1,
  "global": false,
  "text": "Test Challenge",
  "proposal": {
    "gameType": "free",
    "nigiri": true,
    "rules": {
      "rules": "japanese",
      "size": 19,
      "komi": 6.5,
      "timeSystem": "30:00+5×30"
    },
    "players": [{
      "role": "white",
      "name": "wms"
    },{
      "role": "black"
    }]
  }
}

SYNC_REQUEST

Send a sync, get a sync back. Useful if you want to know when for sure an earlier command has been completed by the server (each player's commands are processed in order, one command being completely finished before the next is started).

SYNC

CHALLENGE_PROPOSAL

Change the default proposal for a challenge. Can only be sent by the challenge owner.

CHALLENGE_PROPOSAL

GAME_MOVE

Make a move in your game. Leaving out x and y indicates a pass.

GAME_RESIGN

Resign the game.

GAME_UNDO_REQUEST, GAME_UNDO_ACCEPT

Request an undo in a game, or grant an undo. To reject an undo, simply ignore it.

GAME_UNDO_REQUEST (sent to your opponent when you send your undo request)

MODERATED_COMMENT

Sent when a moderator in a channel accepts a message.

SET_CHAT_MODE

Set the mode (moderated, normal, etc.) of a channel. Only available to teachers.

GAME_TIME_EXPIRED

Sent in response to GAME_TIME_EXPIRED. Indicates that you are still connected.

GAME_ADD_TIME

Add time to your opponent's clock.

WAKE_UP

Reset our idle clock. Most commands do this, but if this command does nothing else.

GAME_SET_ROLES

Set the roles of players in a demo/review. This will temporarily change the effective roles of players. Any number of roles can be set.

GAME_START_REVIEW

Change a game into review mode. This actually creates a new channel, with the review in it, moves everybody into the new channel, then closes out the old one.

CHALLENGE_RETRY

Sent from the challenge owner. Indicates that the owner wants to go back and edit the proposal before accepting any offers.

GAME_LIST_ENTRY_SET_FLAGS

Change the flags of a game or challenge. Some can only be set by admins. Any number can be changed at once. Any flags not present will be left unchanged.

GAME_AUDIO

A block of audio for the game.

START_PLAYBACK

Create a new channel to play a recorded lecture.

REQUEST_PLAYBACK_LIST

Request a list of playbacks available.

PLAYBACK_SET

Set the position and speed of a playback.

GLOBAL_LIST_JOIN_REQUEST

Request to join a global game list channel.

UPLOAD_AVATAR

Upload new avatar data. The avatar must be a jpeg file sized 141×200 pixels and under 8KB.

GAME_SET_ALLOW_CHAT

Set whether or not a given user can talk during moderated mode. By default, nobody can except the moderator.

ANNOUNCEMENT

Send an announcement to every channel on the server. Admin only.

REQUEST_SERVER_STATS

Request some miscellaneous server statistics.

SERVER_STATS

DELETE_ACCOUNT

Delete an account. Admin only.

DELETE_ACCOUNT_ALREADY_GONE, DELETE_ACCOUNT_SUCCESS

KEEP_OUT_REQUEST

Request that the server block a user for a while. Admin only.

KEEP_OUT_LOGIN_NOT_FOUND, KEEP_OUT_SUCCESS.

CLEAR_KEEP_OUT

Clear a keep out request. Admin only.

CLEAR_KEEP_OUT_SUCCESS, CLEAR_KEEP_OUT_FAILURE

JOIN_GAME_BY_ID

Join a game by giving the timestamp of the game start.

ROOM_LOAD_GAME

Load a saved game in a room.

SHUTDOWN

Shut down the server. Admin only. Duh.

CHANNEL_DELETE

Delete the channel. Admin only. Generally channels go away on their own, this is only when there is some urgent reason to delete a game etc.

REGISTER

For guests to get a permanent account.

REGISTER_SUCCESS, REGISTER_BAD_EMAIL.

ROOM_CLONE_GAME

Clone a game into this room.

CHALLENGE_ACCEPT

Sent by challengers to indicate that they accept the proposal as it stands.

CHALLENGE_SUBMIT

Sent by challengers to submit themselves as players.

CONVO_NO_CHATS

Indicates that we do not want to receive any more chats in this conversation until further notice.

CHALLENGE_DECLINE

Sent by the creator of a challenge to indicate that they do not accept a submitted proposal.

AUTOMATCH_CREATE, AUTOMATCH_SET_PREFS

Turn on automatch or set our default preferences.

AUTOMATCH_CANCEL

Do not accept automatch games.

IDLE_ON

Immediately set us as idle (greyed out).

TAG_GAME

Apply a tag to a game.

FETCH_TAGS

Fetch your database of tags.

FETCH_TAGS_RESULT.

ADMIN_CLEAR_TAG

Erase a tag. Admin only.

GAME_MARK_LIFE

Mark whether a stone is alive or dead.

GAME_SCORING_DONE

Indicate that you are satisfied with the current alive/dead marks.

KGS_SGF_CHANGE

Add one or more SGF events to the game.

GAME_SET_SCORES

Set the scores for the game. These scores will be visible until the SGF node changes.

LOGOUT

Indicates you want to log out of the server.

LOGOUT

• Example JSON HTML client
• Protocol summary
• Upstream message reference
• Downstream message reference
• Data types used