Downstream Messages

GET request will return a JSON object with one elment, named messages. The value of messages will be a list of objects, which will always have an element named type that will match one of the message types in the list below. Messages marked as channel messages will always include a channelId field that is the ID of this channel.

HELLO

Always the first message you receive.

Field	Meaning
versionMajor	Major version number of server.
versionMinor	Minor version number of server.
versionBugfix	Bugfix version number of server.
jsonClientBuild	A string with the date and time of this JSON translator build.

USER_UPDATE

Letting you know that a user's flags have changed.

Field	Meaning
user	The user information.

LOGIN_FAILED_NO_SUCH_USER

Your user name is not on the server.

LOGIN_FAILED_BAD_PASSWORD

Your password did not match.

LOGIN_FAILED_USER_ALREADY_EXISTS

An attempt to log in as a guest failed because the user name selected is already present.

RECONNECT

You have been disconnected because somebody logged in with your account on another system. Note: Despite the name of this message, you should not reconnect automatically when you get this. Most likely the user is gone and has logged in from another system, and reconnecting here will kick them back out.

LOGIN_SUCCESS

You have logged in successfully.

Field	Meaning
you	A user that describes you.
friends	Optional. A list of friends; see below for how each friend is structured.
subscriptions	Optional. List of KGS Plus subscriptions that this account has.
roomCategoryChannelIds	An object that maps room categories to the channel that has the master room list for that category.
rooms	A list of all rooms on the server. See below for per-room information.
Elements of friend list
friendType	One of `buddy`, `censored`, `fan`, or `admin_track`.
user	A user giving information on the friend.
notes	Optional. String information about the friend.
Elements of room list
channelId	The channel ID of the room.
category	The category of the room.

ARCHIVE_JOIN, TAG_ARCHIVE_JOIN

Field	Meaning
user	The user whose archive this is.
games	An array of game summaries.

UNJOIN

Indicates that you are no longer in this channel.

ARCHIVE_GAMES_CHANGED

One or more games in the archive have changed.

Field	Meaning
games	An array of game summaries that have changed.

ARCHIVE_GAME_REMOVED

A game in this archive has been removed.

Field	Meaning
timestamp	The time stamp of the game that was removed.

CLOSE

The channel has been closed, and no longer exists.

ARCHIVE_NONEXISTANT

The archive you have requested does not exist.

Field	Meaning
name	The name of the user whose archive you requested.

JOIN_ARCHIVE_REQUEST.

ROOM_NAMES

Provides the names of one or more rooms.

Field	Meaning
rooms	An array of room information
Room Information
channelId	The channel ID of the room
name	The name of the room.
private	Optional. If set, the room is private.
tournOnly	Optional. If set, only tournament games in this room.
globalGamesOnly	Optional. If set, all games in this room must be on the global game lists.

PRIVATE_KEEP_OUT

You tried to join a channel that is private.

Field	Meaning
channelId	The channel that you tried to join.

ROOM_JOIN

Indicates that you have joined a room.

Field	Meaning
games	A list of game channels that are in the room.
users	A list of users in this room.

GAME_JOIN

You joined a game channel.

Field	Meaning
users	List of users in this room.
sgfEvents	A list of SGF events that will rebuild the game to its current point.
Various	All fields from a GAME_STATE message will be present as well.
gameSummary	A game summary for this game.

CHALLENGE_JOIN

You joined a challenge.

Field	Meaning
users	List of users in this room.
gameSummary	The game summary for this game.
Various	All fields from a GAME_STATE message will be present as well.

USER_ADDED

Field	Meaning
user	The user who has been added to this channel.

CHAT, ANNOUNCE, MODERATED_CHAT

A chat message from the channel. Announcements should be in bold, they are from admins and are meant to stand out. Moderated chat means that the message is coming from the current channel moderator on behalf of the user specified in the message.

Field	Meaning
user	The user who made the announcement.
text	The text of the chat or announcement.

USER_REMOVED

A user has been removed from the channel.

Field	Meaning
user	The user.

DETAILS_JOIN

Field	Meaning
user	The user whose details channel this is.
Various	All fields from DETAILS_UPDATE are present.

DETAILS_UPDATE

If you are in a details channel when anything about the user changes, you get this update.

Field	Meaning
forcedNoRank	Boolean. If set, then this user's rank has been shut off by admins.
privateEmail	Boolean. If set, then this user is keeping their email address private
emailWanted	Boolean. If set, the user wants email from KGS.
lastOn	The time when they were last logged in.
regStartDate	When they registered this account.
personalName	Their "real name."
personalInfo	A block of text where they can put whatever they want.
locale	The locale passed in on their last login.
email	Optional. Their email address. Missing if they have it private, unless you are an admin, in which case it is provided anyway.
subscriptions	Optional. If this is your account or if you are an admin, your subscriptions are here. See LOGIN_SUCCESS.

DETAILS_JOIN_REQUEST.

DETAILS_NONEXISTANT

Sent if you ask for details on a nonexistant user.

Field	Meaning
name	The name for which you asked for a details channel.

DETAILS_JOIN_REQUEST.

AVATAR

Image data for a user's avatar.

Field	Meaning
name	The name of the user whose image this is. Note that this message is unique in downstream messages, in that it has a name instead of a user.
imageData	base64 encoded JPEG image data. If this is missing, it means that the user has no avatar.

AVATAR_REQUEST.

DETAILS_RANK_GRAPH

Rank graph data for a user details channel.

Field	Meaning
rankData	An array of rank graph data. One value per day, last value is for midnight GMT from yesterday. 30k is 0..99, 29k is 100..199, etc. 0x7fff indicates "no rank for this day."

DETAILS_RANK_GRAPH_REQUEST.

ROOM_CAT_COUNTERS

If you join a room category channel, you get these periodically.

Field	Meaning
rooms	A list of room entries.
Room Entry Values
channelId	The room's channel ID.
numUsers	The number of users in the room.
numGames	The number of games in the room.

ROOM_DESC

Gives the room descripton text for a room, and the list of owners.

Field	Meaning
description	The room description text
owners	Optional. A list of users.

ROOM_NAME_FLUSH

The name of this room has changed. If you aren't in the room, you need to re-request the name (or just forget about it).

ROOM_CREATED

You successfully created a room.

Field	Meaning
callbackKey	The callback key for your request.

CREATE_ROOM_REQUEST

CONVO_JOIN

Field	Meaning
callbackKey	Optional. If you were the one to request this convo, you will see your callback key here.
user	The other user in this convo.

CONVO_NO_SUCH_USER

Can't make your convo. User doesn't exist.

Field	Meaning
callbackKey	Your callback key.

MESSAGES

Contains your messages from your mailbox.

Field	Meaning
messages	A list of messages.
Message Contents
time	The timestamp of the message creation.
user	The user who sent the message.
text	The text of the message.

MESSAGE_CREATE_SUCCESS

You successfully sent somebody a message.

Field	Meaning
callbackKey	The callback key.

MESSAGE_CREATE_NO_USER, MESSAGE_CREATE_FULL

The user who you tried to send a message to does not exist or has a full mailbox.

Field	Meaning
callbackKey	Your callback key.

MESSAGE_CREATE_CONNECTED

The user is connected. Instead of leaving them a message, a convo will be created.

Field	Meaning
callbackKey	Your callback key.

FRIEND_CHANGE_NO_USER

You tried to change somebody's friend (buddy, fan, etc.) state, but they don't exist!

Field	Meaning
callbackKey	Your callback key.

FRIEND_ADD_SUCCESS, FRIEND_REMOVE_SUCCESS

You successfully changed somebody's friend state.

Field	Meaning
callbackKey	Your callback key.
friendType	The friend type they are or were.
user	The user who you changed.
notes	Optional. Your notes for the user.

CHALLENGE_CREATED

Informs you that your challenge has been created.

Field	Meaning
callbackKey	Your callback key.
game	The game channel for the new game.

CHALLENGE_CREATE.

CHALLENGE_NOT_CREATED

Indicates that you could not create the challenge you wanted.

Field	Meaning
callbackKey	Your callback key.
gameId	Optional. Honestly I'm not sure what this means. The Java client ignores it. The server fills it in sometimes, but it's very hard for me to tell exactly when or why.

CHALLENGE_CANT_PLAY_RANKED

Indicates that your game proposal was invalid, because it specified a ranked game but the rules were incompatible with ranked.

Field	Meaning
field	One of `SIZE`, `HANDICAP`, `KOMI`, or `TIME`.
tooBig	Boolean. If set, your value was too big for ranked; if clear, your value was too small.
limit	The value you need to move to in order to play ranked.

IDLE_WARNING

You have not done anything in a long time, and will be disconnected in 10 minutes.

GAME_LIST

Updates the list of games in a room or global game list.

Field	Meaning
games	A list of game channels.

SYNC

No data, just lets you know that your SYNC_REQUEST has been processed and returned.

Field	Meaning
callbackKey	The callback key from the request.

SYNC_REQUEST.

CHALLENGE_PROPOSAL

A player in a challenge has proposed a game.

Field	Meaning
proposal	The proposal.

GAME_NOTIFY

When you are about to join a game but may not know about it (e.g., if you are not in a room with the game), this will be sent first.

Field	Meaning
game	The game channel.

GAME_STATE

Updates with more information about the game.

Field	Meaning
Various	The game flags for this game.
actions	A list of the actions available to each player in the game. See below for the format for each action.
clocks	An object mapping role to the current state of that role's clock. See below for the format of each clock. May not be present when there are no clocks involved in the game.
score	The final score from the game. Only present if the game has been scored.
whiteDoneSent	Boolean. Indicates whether or not white has OKed the current score. Only present when scoring.
blackDoneSent	Boolean. Indicates whether or not black has OKed the current score. Only present when scoring.
whiteScore	The white score. Only present during scoring.
blackScore	The black score. Only present during scoring.
doneId	The current "done ID." Each time a player changes the life and death of stones in the game, the done ID is incremented, and the "doneSent" flag for each player is cleared. When sending a GAME_SCORING_DONE message, you must include the done ID, and if it is not up to date the message will be ignored by the server.
Action Format
action	One of: `MOVE`, `EDIT`, `SCORE`, `CHALLENGE_CREATE`, `CHALLENGE_SETUP`, `CHALLENGE_WAIT`, `CHALLENGE_ACCEPT`, `CHALLENGE_SUBMITTED`, `EDIT_DELAY`.
user	The user who can perform this action. Multiple users may have the same action available.
Clock Format
paused	Boolean. If present, the clock has been paused, e.g. because the player has left the game.
running	Boolean. If present, the clock is running. A clock is only running when it is the turn of the player who owns this clock.
time	Double. The seconds left in the current period of the clock.
periodsLeft	Only present for byo-yomi clocks. The number of periods left on the clock.
stonesLeft	Only present for Canadian clocks. The number of stones left in the current period.

GAME_UPDATE, PLAYBACK_DATA

Moves have been made in the game or playback.

Field	Meaning
sgfEvents	The SGF events needed to represent the changes in the game.

GAME_UNDO_REQUEST

User requested an undo. Ignore it to reject it, or send GAME_UNDO_ACCEPT to let the undo happen.

Field	Meaning
role	The role of the user requesting an undo.

GAME_UNDO_REQUEST, GAME_UNDO_ACCEPT.

SET_CHAT_MODE

For teachers only. Set whether the chat is moderated or not.

Field	Meaning
mode	One of `NORMAL`, `QUIET`, or `MODERATED`.
user	Optional. If the mode is `MODERATED` then this says who the moderator is.

GAME_TIME_EXPIRED

Indicates that your clock has run out. This is a test message to determine whether or not you are still connected. The client must immediately send a GAME_TIME_EXPIRED back to the server.

GAME_TIME_EXPIRED.

GAME_OVER

The game has ended.

Field	Meaning
score	The final score of the game.

GAME_REVIEW

A game review has started. The review will be in a new channel.

Field	Meaning
originalId	The channel ID of the game.
review	The game channel of the new review.

LOAD_FAILED

An attempt to load a game from archives has failed.

Field	Meaning
gameSummary	The game summary of the game that failed to load.

CHANNEL_AUDIO

A block of audio for a channel you're in.

Field	Meaning
audio	Base64-encoded SPEEX audio data.

PLAYBACK_ADD

Add one or more playbacks to those you know about.

Field	Meaning
playbacks	A list of playbacks.
Playback Format
dateStamp	The date stamp of the playback.
subscribersOnly	Boolean. If set, only KGS Plus subscribers can see the playback.
gameSummary	The game summary of the playback.

PLAYBACK_SETUP

A playback has been set up for you to watch.

Field	Meaning
gameSummary	The game summary of the playback.

PLAYBACK_JOIN

You have joined a playback. No information, it all came in the prior PLAYBACK_SETUP message.

GLOBAL_GAMES_JOIN

You have joined a global games list.

Field	Meaning
containerType	One of `CHALLENGES`, `ACTIVES`, or `FANS`.
games	A list of game channels.

SUBSCRIPTION_UPDATE

Field	Meaning
subscriptions	A list of your subscriptions.

CHALLENGE_FINAL

A matching proposal has been uploaded by all players involved, and the game is starting.

Field	Meaning
gameChannelId	The channel ID of the new game.
proposal	The accepted proposal.

ANNOUNCEMENT

A message sent to all channels, all users. This should be displayed very prominently.

Field	Meaning
text	The text of the announcement.

SERVER_STATS

Random server statistics.

Field	Meaning
versionMajor	Same as HELLO.
versionMinor	Same as HELLO.
versionBugfix	Same as HELLO.
serverStartTime	The time when the server last started up.
bytesIn	Total bytes sent to the server (in the binary protocol) since it started.
messagesIn	Total messages received by the server since it started.
bytesOut	Total bytes sent out from the server (in the binary protocol).
messagesOut	Total messages sent out from the server.
logins	Number of users logged in right now.
loginsMax	Most logins at any one time since server restart.
accounts	Number of current accounts on the system.
accountsMax	Most accounts ever in the server since it last started.
rooms	Number of rooms on the server.
roomsMax	Most rooms on the server at one one time since last restart.
games	Number of games on the server.
gamesMax	Most games on the server at once since last restart.

DELETE_ACCOUNT_ALREADY_GONE, DELETE_ACCOUNT_SUCCESS

Indicates whether your attempt to delete an account succeeded or failed.

Field	Meaning
name	The name that you tried to delete.

CHANNEL_SUBSCRIBERS_ONLY

You can't join that channel! It's for subscribers only.

GAME_ALL_PLAYERS_GONE

All players have left the game.

GAME_EDITOR_LEFT

The editor of this review or demonstration game has left.

Field	Meaning
user	The editor (in user format) who left the game.

CHANNEL_NO_TALKING

This channel doesn't allow talking.

LOGIN_FAILED_KEEP_OUT

You can't log in, an admin has blocked you.

Field	Meaning
text	The reason the admin gave for blocking you.

TOO_MANY_KEEP_OUTS

You have blocked too many users. You can't do it any more.

Field	Meaning
name	The user who you were not able to block.

KEEP_OUT_SUCCESS, KEEP_OUT_LOGIN_NOT_FOUND

Success or failure of your blocking somebody.

Field	Meaning
name	The name of the user you tried to block.

CLEAR_KEEP_OUT_SUCCESS, CLEAR_KEEP_OUT_FAILURE

Success or failure of your attempt to life the block of a user.

Field	Meaning
name	The name of the user whose block you tried to lift.

CANT_PLAY_TWICE

You tried to play, but you are already playing in a game. Use simul if you want to play in several games at once.

Field	Meaning
callbackKey	Your callback key.

ALREADY_IN_PLAYBACK

You tried to start up a playback, but you are already watching one.

GAME_STARTED

A game you played in has been started/loaded.

Field	Meaning
gameSummary	The game summary of the started game.

REGISTER_SUCCESS, REGISTER_BAD_EMAIL

Indicates whether your account to register succeeded or failed.

GAME_CONTAINER_REMOVE_GAME

A game has been removed from this room or global game list.

Field	Meaning
gameId	The channel of the game that was removed.

PLAYBACK_ERROR

Same error happened while trying to do a playback.

ROOM_CREATE_TOO_MANY_ROOMS, ROOM_CREATE_NAME_TAKEN

Reasons why creating a room would fail.

Field	Meaning
callbackKey	Your callback key.

ROOM_CHANNEL_INFO

Gives you the category of a room. Sent when a room changes categories.

Field	Meaning
category	The new category of the room.

CHANNEL_CHANGE_NO_SUCH_USER

Your attempt to add/remove a user as an owner or somebody with access to a private room has failed.

Field	Meaning
name	The user you tried to add or remove.

ACCESS_LIST

Field	Meaning
users	A list of users who have access to this private room or game.

PLAYBACK_DELETE

A playback has been deleted from the system.

Field	Meaning
timeStamp	The time stamp of the playback thas has been deleted.

CHALLENGE_SUBMIT

Another user has submitted a proposal in a challenge channel you own.

Field	Meaning
user	The user who submitted the proposal.
proposal	The proposal.

SUBSCRIPTION_LOW

Your subscription will expire soon!

Field	Meaning
days	The number of days before your subscription expires.

ROOM_CAT_ROOM_GONE

A room has left this category list.

Field	Meaning
roomId	The channel ID of the room that left.

CONVO_NO_CHATS

The other person in this convo does not want to talk.

GAME_SET_ROLES_UNKNOWN_USER, GAME_SET_ROLES_NOT_MEMBER

You tried to set up roles for this game, but one of the players who you named does not exist or is not in this game.

Field	Meaning
name	The name of the user you tried to assign a role to.

CHALLENGE_DECLINE

Your proposal has been declined.

GAMELISTENTRY_PLAYER_REPLACED

One player has been swapped in for another.

Field	Meaning
role	The role that has changed users.
user	The user who is now filling the role.

CHANNEL_AD, AD

(for CHANNEL_AD)

Everybody likes ads, right?

Field	Meaning
locationId	A number indicating where the ad should be shown.
adId	Clicking the ad should take you to `http://www.gokgs.com/servlet/ad/adId`.
imageData	Base64 encoded image data for the ad.

CHANNEL_CHAT_ALLOWED

Indicates that chat is now enabled in this channel.

CHANNEL_ALREADY_JOINED

You attempted to join this channel when you were already in it.

TOURN_NOTIFY

A tournament game that you are playing in has started.

Field	Meaning
gameChannelId	The channel ID of the tournament game that has started.
roomChannelId	The channel ID of the room that contains the tournament game.
clocksStarted	Boolean. If set, the setup time is over, the clocks are ticking.

GAME_PREP_STATUS

Indicates that a game is paused (in "prepare" mode).

Field	Meaning
prepType	One of `END`, `TOURNAMENT`, or `AUTOMATCH`.
time	Optional. Floating point. The time (in seconds) until the game goes back to normal. Not present when `prepType` is `END`.

PLAYBACK_SEEK_START

You are about to start a playback seek.

PLAYBACK_SEEK_COMPLETE

When you do a playback seek, you get a big pile of SGF events. This message indicates that you have gotten all you need, you are at the seek position you wanted.

AUTOMATCH_PREFS

Tells you the auotmatch preferences that this user has uploaded before.

Field	Meaning
maxHandicap	The maximum number of handicap stones accepted in an automatch game.
estiamtedRank	The rank we claim to be. `1k` is the highest allowed.
freeOk	If set, free (unrated) games are OK.
rankedOk	If set, rated games are OK.
robotOk	If set, games against robots are OK.
humanOk	If set, games against humans are OK.
blitzOk	If set, blitz games are OK.
fastOk	If set, fast games are OK.
mediumOk	If set, medium speed games are OK.
unrankedOk	If set, playing against unranked players are OK.

AUTOMATCH_STATUS

Tells you whether or not automatch is on right now.

Field	Meaning
enabled	Boolean

GAME_NAME_CHANGE

The name of a game has changed.

Field	Meaning
name	Optional. The new name of the game. If this is missing, the game no longer has a name.

FETCH_TAGS_RESULT

Returns your tags. This object returns, in addition to the type field, a mapping from game time stamp to the tag of that game.

TAG_ARCHIVE_NONEXISTANT

You want a tag archive for a user who does not exist.

Field	Meaning
name	The name of the user whose tag archive you tried to view.

JOIN_COMPLETE

Some channels give you a burst of messages when you first join. This message indicates that the burst is over, you have all the information you will get about the channel.

GAME_LOOP_WARNING

Indicates that you have had the game in this exact position before. If you repeat it twice more, the game will be scored as no result. Only appears for Japanese-rules games.

LOGOUT

Your connection has closed.

Field	Meaning
text	Optional. An English-language message indicating why the connection closed. Empty when the connection closes for "obvious" reasons, e.g. if you sent a LOGOUT message up to the server.

LOGOUT