Kongregate Developers

Suggest Edits

Chat.AddEventListener

Listen for chat messages from the user
addEventListener(event_type, callback)

 

Listening for chat text entry

The chat property on the Kongregate API object broadcasts several different types of events. The message event lets you know when the player has submitted a message in the custom chat tab, while the room.message event notifies you of messages from other users in game chat, allowing you to listen in and react.

The addEventListener method takes two arguments, the event type, and a callback function:

Name
Type
Description

event_type

String

Type of event to listen for

callback

Function

Function to call when the event is triggered

The message event

The message event is broadcast when the player submits text in the entry box on your custom tab. It has a single data field with the following properties:

Name
Type
Description

username

String

The username of the user who sent the message (will always be the current user)

message

String

The message content

Example: Listen for the player submitting a chat message in a custom tab

function onPlayerMessage(event:*):void {
  trace("Message from " + event.data.username + ": " + event.data.message);
}

kongregate.chat.addEventListener("message", onPlayerMessage);
 
function onPlayerMessage(event) {
  console.log("Message from " + event.data.username + ": " + event.data.message);
}

kongregate.chat.addEventListener("message", onPlayerMessage);

The room.message event

The room.message event is broadcast when a game chat message is received. It has a single data field with the following properties:

Name
Type
Description

username

String

The username of the user who sent the message

room

Object

An object with name and id properties

message

String

The message content

history

Boolean

A flag indicating whether or not the message was retrieved from the room history or not

Example: Listen for game chat messages

function onRoomMessage(event:*):void {
  trace("GameChat: " + event.data.username + ": " + event.data.message);
}

kongregate.chat.addEventListener("room.message", onRoomMessage);
 
function onRoomMessage(event) {
  trace("GameChat: " + event.data.username + ": " + event.data.message);
}

kongregate.chat.addEventListener("room.message", onRoomMessage);

The tab_visible event

The tab_visible event is broadcast when a custom tab has been shown after a call to showTab

function onTabVisible(event:*):void {
  trace("Tab visible!");
}

kongregate.chat.addEventListener("tab_visible", onTabVisible);
 
function onTabVisible() {
  console.log("Tab visible!");
}

kongregate.chat.addEventListener("tab_visible", onTabVisible);

Related:

Suggest Edits

Chat.ClearMessages

Remove all chat messages from the custom tab
clearMessages()

 

This function clears all messages in a previously opened custom chat tab.

kongregate.chat.clearMessages();
 
kongregate.chat.clearMessages();

Related:

Suggest Edits

Chat.CloseTab

Close a custom chat tab
closeTab()

 

This function closes a previously opened custom chat tab.

kongregate.chat.closeTab();
 
kongregate.chat.closeTab();
Suggest Edits

Chat.DisplayMessage

Display a message in the custom chat tab
displayMessage(message, username)

 

The displayMessage function on the chat property of the Kongregate API object can be used to create a virtual chat message from a given user in the custom chat tab. It accepts the following arguments:

Name
Type
Description

message

String

The message to display

username

String

The username the message is from

Example: Display a message "Hi there!" from user "BenV"

kongregate.chat.displayMessage("Hi there!","BenV");
 
kongregate.chat.displayMessage("Hi there!","BenV");

Related:

Suggest Edits

Chat.ShowTab

Displays a custom chat tab
showTab(name, description, options)

 

Displaying a Custom Tab

This function displays a custom chat tab in the chat area, which will replace any other custom tabs that might be showing. It takes a name, description, and options:

Name
Type
Description

name

String

Name of the tab

description

String

Description of the tab

options

Object

Extra options for the tab

The options object can have the following properties:

Name
Type
Description

size

Decimal

Relative size of the canvas, 0 being the smallest, 1 being the largest (default 0.5)

Example: Display a custom tab with a large canvas

kongregate.chat.showTab("MyTab","My Custom Tab", {size:0.75});
 
kongregate.chat.showTab("MyTab","My Custom Tab", {size:0.75});

Note

The name and description parameters are currently unused - the tab will display "Match" at the top for now. These may be implemented in the future, so adding them in your code will ensure that it will work when we do.

Related:

Suggest Edits

Images.SubmitAvatar

Ask the user to change their avatar
submitAvatar(display_object, callback)

 

Exporting a custom avatar

Kongregate's Avatar Export API gives you the ability to export in-game avatars and let users use them as their Kongregate profile avatar. When you call the submitAvatar function, the user will receive a notification that the game is requesting to change their avatar. At that point, they'll be able to crop the suggested image if they wish, and can choose to accept or decline the avatar modification. This functionality can be used to provide bonuses for players, as well as more directly with avatar creator/editor apps, and probably other uses we haven't even thought of yet.

You can use the submitAvatar function on the images property of the Kongregate API object to export a DisplayObject or a Base64-encoded string containing the image data to be converted to a user avatar. It is highly recommended that avatars be at least 40x40px:

Name
Type
Description

display_object

DisplayObject or Base64-encoded string

The DisplayObject or Base64-encoded string containing the avatar image

callback

Function

The callback function to be called when the operation is complete.

The callback function is passed a single boolean parameter which will be true if the user has accepted the avatar and false if they decide not to use it.

Example: Exporting a rectangle

var rect:Shape = new Shape();
rect.graphics.lineStyle(1);
rect.graphics.beginFill(0x0000FF, 1);
rect.graphics.drawRect(0, 0, 75, 50);

kongregate.images.submitAvatar(rect, onAvatarComplete);

function onAvatarComplete(success:Boolean) {
  if(success) {
    trace("That user must love rectangles!")
  } else {
    trace("Next time I'll try a triangle :(")
  }
}
 
var base64PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=';

kongregate.images.submitAvatar(base64PNG, function(success) {
	if (success) {
  	console.log('That is a small avatar');
  }
});
Suggest Edits

Mtx.AddEventListener

addEventListener(event_type, callback)

 

Mtx events

This method can be used to listen for events related to the incentivized advertising API

The addEventListener method takes two arguments, the event type, and a callback function:

Name
Type
Description

event_type

String

Type of event to listen for

callback

Function

Function to call when the event is triggered

Incentivized ad events

The following event types are currently supported:

Name
Description

adsAvailable

Ads are now available, and showIncentivizedAd will work

adsUnavailable

Ads are not available, and showIncentivizedAd will fail

adOpened

An ad is being displayed

adCompleted

An ad has completed successfully, and the player should be rewarded

adAbandoned

Ad ad has been closed before completion, the player should not be rewarded

Related:

Suggest Edits

Mtx.InitializeIncentivizedAds

Initialize the incentivized ad system
initializeIncentivizedAds

 

The initializeIncentivizedAds method requests ads from the back-end and allows you to receive events related to ads in the method you registered with addEventListener.

kongregate.mtx.initializeIncentivizedAds();
 
kongregate.mtx.initializeIncentivizedAds();

Related:

Suggest Edits

Mtx.PurchaseItems

Start the purchase flow for predefined items
purchaseItems(items, callback)

 

Requesting Item Purchase

You may bring up the "purchase items" dialog box by using the purchaseItems method on the mtx property on the Kongregate API object. It takes either an array of item identifiers or an array of identifier/metadata objects, as well as a callback function which should be called with the result of the purchase:

Name
Type
Description

items

Array

Array of item identifier strings, or an array of objects each with an identifier and data field.

callback

Function

A callback function for when the purchase dialog is closed.

The callback function is passed an object with the following fields:

Name
Type
Description

success

Boolean

A flag indicating whether or not the purchase was successful.

Example: Purchasing a single item with identifier "sword":

kongregate.mtx.purchaseItems(["sword"], onPurchaseResult);

function onPurchaseResult(result:Object):void {
  trace("Purchase success:" + result.success);
}
 
kongregate.mtx.purchaseItems(["sword"], onPurchaseResult);

function onPurchaseResult(result) {
  console.log("Purchase success:" + result.success);
}
 
Application.ExternalEval(@"
  kongregate.mtx.purchaseItems(['sword'], function(result) {
    var unityObject = kongregateUnitySupport.getUnityObject();
    var success = String(result.success);
    unityObject.SendMessage('MyGameObject', 'OnPurchaseResult', success);
  });
");

Metadata

You can attach a metadata string to the item instance if needed which can be retrieved from the server later. It is important to note that the client can change this data using a browser plugin fairly easily, so it is a good idea to obfuscate this string, as well as verify its validity as it relates to your game.

Example: Purchasing an item with metadata attached:

var items:Array = [{identifier:"sword", data:"+1str"}];
kongregate.mtx.purchaseItems(items, onPurchaseResult);

function onPurchaseResult(result:Object):void {
  trace("Purchase success:" + result.success);
}
 
var items = [{identifier:"sword", data:"+1str"}];
kongregate.mtx.purchaseItems(items, onPurchaseResult);

function onPurchaseResult(result) {
  console.log("Purchase success:" + result.success);
}
Suggest Edits

Mtx.PurchaseItemsRemote

Start the dynamic item purchase flow
purchaseItemsRemote(order_information, callback)

 

Requesting Remote/Dynamic Item Purchase

You may start the Dynamic Purchasing API purchase flow using the purchaseItemsRemote method on the mtx services object. It accepts an order info string which will be passed to your API callback as a signed request, as well as a callback function which should be called with the result of the purchase:

Name
Type
Description

order_information

String

An order info string that will be passed to your server in an API callback.

callback

Function

A callback function for when the purchase dialog is closed.

The callback function is passed a single object with the following fields:

Name
Type
Description

success

Boolean

A flag indicating whether or not the purchase was successful.

item_order_id

Integer

The unique ID of the transaction, or undefined if the purchase failed

Example: Starting a dynamic item purchase with order info set to 'sword':

kongregate.mtx.purchaseItemsRemote("sword", onPurchaseResult);
 
function onPurchaseResult(result:Object):void {
  trace("Purchase success:" + result.success + ", id: " + result.item_order_id);
}
 
kongregate.mtx.purchaseItemsRemote("sword", onPurchaseResult);
 
function onPurchaseResult(result) {
  trace("Purchase success:" + result.success + ", id: " + result.item_order_id);
}
 
Application.ExternalEval(@"
  kongregate.mtx.purchaseItemsRemote('sword', function(result) {
    var unityObject = kongregateUnitySupport.getUnityObject();
    var success = String(result.success);
    unityObject.SendMessage('MyGameObject', 'OnRemotePurchaseResult', success);
  });
");

Once the purchase dialog is invoked, the item_order_request signed request callback will be initiated to your API callback URL so that your game server can define the items to be purchased dynamically.

Suggest Edits

Mtx.RequestItemList

Request item definitions from the server
requestItemList(tags, callback)

 

Requesting Item Definitions

The non-dynamic item definitions for a game can be retrieved using the requestItemList method. This function takes an array of tags to filter on (pass an empty array for all items), and a callback function to call when retrieval is complete:

Name
Type
Description

tags

Array

An array of strings containing tags to filter items with. Use an empty array or undefined for no filter

callback

Function

A callback function to be called with the results of the operation

The callback function is passed a single object with the following fields:

Name
Type
Description

success

Boolean

A flag indicating whether or not the operation was successful

data

Array

An array of item definitions, if successful

Each item definition in the data array contains the following fields:

Name
Type
Description

id

Integer

The unique ID of the item

identifier

String

The item identifier

name

String

The name of the item

description

String

The item description

price

Integer

The price of the item in Kreds

tags

Array

An array of strings containing the tags for the item

image_url

String

The image for the item

Example: Request all items:

kongregate.mtx.requestItemList([], onItemList);

function onItemList(result:Object):void{
  trace("Item list result, success: " + result.success);
  if(result.success) {
    for(var i:int = 0; i < result.data.length; i++) {
      var item:Object = result.data[i];
      trace((i+1) + ". " + item.identifier + ", " + item.id + "," + item.name);
    }
  }
}
 
kongregate.mtx.requestItemList([], onItemList);

function onItemList(result){
  console.log("Item list result, success: " + result.success);
  if(result.success) {
    for(var i = 0; i < result.data.length; i++) {
      var item = result.data[i];
      console.log((i+1) + ". " + item.identifier + ", " + 
                  item.id + "," + item.name);
    }
  }
}
Suggest Edits

Mtx.RequestUserItemList

Request a user's inventory from the server
requestUserItemList(username, callback)

 

Requesting User Item Instances

The inventory of any user can be requested by using the requestUserItemList method. This function takes a username string as the first argument, but you may pass in null or a blank string to request the inventory for the current user. The second argument is a callback function to call when retrieval is complete, which will generally involve a call to use_item or useItemInstance.

Name
Type
Description

username

String

Username of the user to request items for, or null for the current user

callback

Function

A callback function to be called with the results of the operation

The callback function is passed a single object with the following fields:

Name
Type
Description

success

Boolean

A flag indicating whether or not the operation was successful

data

Array

An array of item instances, if successful

Each item definition in the data array contains the following fields:

Name
Type
Description

id

Integer

The unique ID of the item instance

identifier

String

The item identifier

data

String

The metadata attached to the item instance, if any

remaining_uses

Integer

Number of remaining uses, or 0 if this is an unlimited use item

Example: Request the inventory for the current player

kongregate.mtx.requestUserItemList(null, onUserItems);

function onUserItems(result:Object):void {
  trace("User item list received, success: " + result.success);
  if(result.success) {
    for(var i:int = 0; i < result.data.length; i++) {
      var item:Object = result.data[i];
      trace((i+1) + ". " + item.identifier + ", " + item.id + "," + item.data);
    }
  }
}
 
kongregate.mtx.requestUserItemList(null, onUserItems);

function onUserItems(result) {
  console.log("User item list received, success: " + result.success);
  if(result.success) {
    for(var i=0; i < result.data.length; i++) {
      var item = result.data[i];
      console.log((i+1) + ". " + item.identifier + ", " + 
                  item.id + "," + item.data);
    }
  }
}
Suggest Edits

Mtx.ShowIncentivizedAd

Attempt to display an incentivized ad to the user
showIncentivizedAd

 

The showIncentivizedAd method attempts to show an incentivized ad to the user. It will only work after the adsAvailable event has been broadcast.

kongregate.mtx.showIncentivizedAd();
 
kongregate.mtx.showIncentivizedAd();

Related:

Suggest Edits

Mtx.ShowKredPurchaseDialog

Displays the Kred purchase interface
showKredPurchaseDialog(type)

 

Displaying the Kred Purchase Dialog

You may bring up the "purchase kreds" dialog box by using the showKredPurchaseDialog method on the microtransaction services object. The only argument is the default purchase method you would like to display, which can be either offers to show the OfferPal Kred options, or mobile to show the mobile payment options. Any other value will simply show the default purchase dialog.

Name
Type
Description

type

String

Optional type of offer to display, can be offers or mobile - any other value shows the default dialog

Example: Display the OfferPal Kred purchase dialog:

kongregate.mtx.showKredPurchaseDialog("offers");
 
kongregate.mtx.showKredPurchaseDialog("offers");

Handling Guest Users

Since guest users on Kongregate are not allowed to purchase items, you must decide how you want to handle them in your game. In general, whenever a guest user wants to purchase an item, it is a good idea to display a message letting them know they must sign in or register before they can purchase, and then display the sign-in lightbox. Further documentation on this process can be found here.

Suggest Edits

Mtx.UseItemInstance

Consume an item instance from the user's inventory
useItemInstance(item_instance_id, callback)

 

Warning

This function should ONLY be used if your game does not have a server for consuming item instances. If your game has a server component, please use the server-side version.

Consuming user item instances

You can consume a limited-use item instance by using the useItemInstance method. This function takes the item instance ID (retrieved using the requestUserItemList function) and a callback function to be called when the operation is completed.

Name
Type
Description

item_instance_id

Integer

The item instance ID to be consumed

callback

Function

A callback function to be called with the results of the operation

The callback function is passed a single object with the following fields:

Name
Type
Description

success

Boolean

A flag indicating whether or not the operation was successful

id

Integer

The ID of the item instance that was consumed

Example: Consume an item from the player's inventory

kongregate.mtx.useItemInstance(12345, onUseResult);

function onUseResult(result:Object):void {
  trace("Item use result successful: " + result.success);
}
 
kongregate.mtx.useItemInstance(12345, onUseResult);

function onUseResult(result) {
  console.log("Item use result successful: " + result.success);
}
Suggest Edits

Services.AddEventListener

addEventListener(event_type, callback)

 

Services events

This method can be used to listen for events related to the Kongregate user.

The addEventListener method takes two arguments, the event type, and a callback function:

Name
Type
Description

event_type

String

Type of event to listen for

callback

Function

Function to call when the event is triggered

User events

The following event types are currently supported:

Name
Description

login

The user has converted from a guest to a registered user. User info methods on the services object will return updated information after this event is triggered.

Example: Listen for user login event

kongregate.services.addEventListener("login", onKongregateInPageLogin);

function onKongregateInPageLogin(event:Event):void {
  var user_id:Number = kongregate.services.getUserId();
  var username:String = kongregate.services.getUsername();
  var token:String = kongregate.services.getGameAuthToken();
}
 
kongregate.services.addEventListener("login", onKongregateInPageLogin);

function onKongregateInPageLogin() {
  var user_id = kongregate.services.getUserId();
  var username = kongregate.services.getUsername();
  var token = kongregate.services.getGameAuthToken();
}

Related:

Suggest Edits

Services.Connect

Connect to to the back-end
connect()

 

Connecting

The connect function should be used as soon as you have access to the Kongregate API object in order to initialize the connection to our servers. For more information on initialization, see the Client API Introduction.

Note

This function only needs to be called when using the AS3 API, as the AS2 and JavaScript APIs will call it automatically. It is safe to call in other languages, but it will have no effect.

kongregate.services.connect();
Suggest Edits

Services.GetGameAuthToken

Get the game authentication token for the current user
getGameAuthToken()

 

Getting the player's game authentication token

You can use the getGameAuthToken function to retrieve the game authentication token for the current user for use with the server-side authentication API. All guest users have the same authentication token, and do not need to be authenticated by your server.

Name
Type
Description

Return value

String

The authentication token for the user.

Note

You should not assume that the authentication token will remain the same for each user, as it will change any time a user changes their password.

var token:String = kongregate.services.getGameAuthToken();
 
var token = kongregate.services.getGameAuthToken();
Suggest Edits

Services.GetUsername

Get the username of the current user
getUsername()

 

Getting the player's Kongregate username

You can use the getUsername function to retrieve the username of the current player. It will begin with Guest if the user is not signed in.

Name
Type
Description

Return value

String

The username of the current user.

var username:String = kongregate.services.getUsername();
 
var username = kongregate.services.getUsername();
Suggest Edits

Services.GetUserId

Get the user ID of the current user
getUserId()

 

Getting the player's Kongregate user id

You can use the getUserId function to retrieve the unique user ID of the current player. It will return 0 if the user is not signed in.

Please note that to securely authenticate a player, you should use the server-side authentication API.

Name
Type
Description

Return value

Integer

The user ID of the current user.

var userId:Number = kongregate.services.getUserId();
 
var userId = kongregate.services.getUserId();
Suggest Edits

Services.IsGuest

Determine if the current user is a guest
isGuest()

 

Checking if the user is a guest

The isGuest function can be called to determine if the player is currently signed into Kongregate or not.

Name
Type
Description

Return value

Boolean

A flag indicating whether or not the user is a guest.

var isGuest:Boolean = kongregate.services.isGuest();
 
var isGuest = kongregate.services.isGuest();
Suggest Edits

Services.PrivateMessage

Send a private message to the user
privateMessage(content)

 

Note

This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at [email protected].

Private Messages

This feature sends a private message from your game to the player. You simply invoke the method with the desired message content. The message will appear in the player's messages, with your game as the sender.

If you are looking to send them messages when they are not logged in to the game, look at our Private Messages Server API.

Name
Type
Description

content

String

The message to send

kongregate.services.privateMessage("You just did something really great!");
 
kongregate.services.privateMessage("You just did something really great!");
Suggest Edits

Services.ResizeGame

Resizes the game frame
resizeGame(width,height)

 

Maximum required game size

Because a large percentage of our players play on laptops with relatively small screens, we request that games don't require any larger than a 1050x700 size if at all possible.

Automatically resizing the enclosing iframe

If your game is embedded on Kongregate as an iframe you can take advantage of our auto-resizing feature. With this enabled the game's frame will automatically size to be appropriate for the player's browser. Your game will then need to match it's parent frame and you'll be good to go.

To use this feature, go to your game's /edit page (add /edit to the end of your URL) and scroll down until you see the dimensions section. Just set both your normal (minimum) and maximum dimensions and that's it! If you need to disable this later, set the maximum dimensions to blank again.

Manually resizing the enclosing iframe

If you need to manually resize your game's enclosing container, or you are not hosting your game through an iframe, you may do so with the resizeGame call. It accepts the following arguments:

Name
Type
Description

width

Integer

Width of the frame in pixels

height

Integer

Height of the frame in pixels

The enclosing iframe will resize around your game. Games may not be resized smaller than their initial dimensions.

kongregate.services.resizeGame(900, 650);
 
kongregate.services.resizeGame(900, 650);
Suggest Edits

Services.ShowInvitationBox

Invite other users to play a game
showInvitationBox(invitation)

 

Note

This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at [email protected].

Invite Friends

This feature displays a dialog requesting the player send a Private Message to their friends inviting them to try your game. If the player is not authenticated, it will require the player to authenticate before displaying the dialog.

The Private Message includes a game specific message you provide and some text the player may enter in the dialog. The dialog includes an interface for selecting up to 20 friends and other Kongregate members to invite and a Text Field to edit a message. An optional filter parameter may be used to narrow the list of invitees to those that have or have not played the game.

Name
Type
Description

invitation

Object

An object containing fields describing the invitation

The invitation object can contain the following fields:

Name
Type
Description

content

String

The text content of the invitation

filter

String

Optional parameter. If set to played, the dialog will only allow the player to select users that have played the game. When set to not_played, the dialog will only the player to select users that have never played the game. You can also pass a list of user IDs as the filter, and it will only show those users ex "123 8219". When left blank, all users will be available to invite.

kv_params

Object

An optional object containing parameters to be included in the game link. They must all be prepended with kv_ to be passed through to the game

Example Simple invitation:

kongregate.services.showInvitationBox({
  content: "Come try out this awesome game!"
});
 
kongregate.services.showInvitationBox({
  content: "Come try out this awesome game!"
});

Example Only invite players who have never played:

kongregate.services.showInvitationBox({
  content: "Come try out this awesome game!",
  filter: "not_played",
  kv_params: { kv_promo_code: 12345 }
});
 
kongregate.services.showInvitationBox({
  content: "Come try out this awesome game!",
  filter: "not_played",
  kv_params: { kv_promo_code: 12345 }
});
Suggest Edits

Services.ShowFeedPostBox

Create a post in the user's activity feed
showFeedPostBox(content)

 

Note

This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at [email protected]

Feed Posts

This feature displays a dialog requesting permission to make a feed post to a player's wall on behalf of the game. If the player is not authenticated, it will require the player to authenticate before displaying the dialog.

The player may optionally allow all posts from your game. If the player choses to enable that feature, then this will automatically make a post on that player's wall without invoking the dialog.

The showFeedPostBox method takes a content argument, which can either be a string containing the text to place into the feed, or an object that contains properties defining the content, image, and parameters to be passed into the game. It fires a callback once the dialog is closed.

Name
Type
Description

content

String or Object

A string containing the text for the feed post, or an object with content, image_uri, and kv_params fields.

callback

Function

A callback method which will be called with an object containing type, recipients, success, and error fields.

Note

While the game is not published (in "preview" mode), the post will not actually show on the user's feed. This is to avoid confusion around games that aren't public sending out messages. As long as you get the pop-up friend selection box and confirmation the API is integrated correctly

Making a Feed Post

Feed posts are composed of two components: the content of the feed post, and (optionally) an image URI that you specify. If you do not specify an image URI, then the game's icon will be used instead.

Basic Feed Posts

If you don't need a custom image, you may invoke showFeedPostBox with a string containing the post content:

kongregate.services.showFeedPostBox("Praise the Sun!", function(result:Object):void {
		trace("Success: " + result.success);
});
 
kongregate.services.showFeedPostBox("Praise the Sun!", function(result) {
	console.log("Success: " + result.success);
});

Using a Custom Image and Parameters

If you wish to specify a custom image and parameters to be passed into the game when clicked, then you will need to pass in an object with the properties:

Name
Type
Description

content

String

The text content for the feed post

image_uri

String

Link to an image to use as an icon for the feed post

kv_params

Object

Optional parameters to be passed into the game when the feed post link is followed

Example: Complex feed post:

kongregate.services.showFeedPostBox({
  content: "Come help defeat the boss!",
  image_uri: "http://your-domain.tld/feed-post-images/really-hard-boss-face.png",
  kv_params: { kv_promo_code: 12345 }
}, function(result:Object):void {
	trace("Success: " + result.success);
});
 
kongregate.services.showFeedPostBox({
  content: "Come help defeat the boss!",
  image_uri: "http://your-domain.tld/feed-post-images/really-hard-boss-face.png",
  kv_params: { kv_promo_code: 12345 }
}, function(result) {
	console.log('Success: ' + success);
});
Suggest Edits

Services.ShowRegistrationBox

Allows guests to sign in or create an account
showRegistrationBox

 

Showing the registration box

If the player is a guest, and you want to display the registration UI to them (for example, if you want to upsell them to buy an item or you want to use the authentication API), you can use the showRegistrationBox function.

kongregate.services.showRegistrationBox();
 
kongregate.services.showRegistrationBox();

You can read the section on handling guests for more information on how to tell when a user completes registration or signing in.

Suggest Edits

Services.ShowShoutBox

Post a shout on the user's profile page
showShoutBox(message)

 

Note

This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at [email protected].

Showing the shout box

If a player is logged-in and you want to allow them to post a shout on their profile page, you may bring up the shout box, optionally populated with some initial content. The showShoutBox function takes the following arguments:

Name
Type
Description

message

String

The message text to add to the shout

When the function is called, a pop-up will appear giving the player a preview of the shout, and allowing them to add their own text. Once they've done this, the message will read:

[User added text] [Text added by function call] on [Game name with link]

So, for example, if your game "Grind Quest MMO" called kongregate.services.showShoutBox("User43 spent 50 hours grinding to get to level 4"), and the user added "I really need to get a life!", the resulting shout would read:

I really need to get a life! User43 spent 50 hours grinding to get to level 4 on Grind Quest MMO

Example Creating a shout:

 kongregate.services.showShoutBox("I accidentally ate the whole thing!");
 
 kongregate.services.showShoutBox("I accidentally ate the whole thing!");
Suggest Edits

SharedContent.AddLoadListener

Receive notifications when shared content is loaded
addLoadListener(type, callback)

 

Adding load event listeners

You can use the addLoadListener function on the sharedContent propery of the Kongregate API object to register an event listener which will be triggered when shared content of the specified type is loaded by the user. It accepts the following arguments:

Name
Type
Description

type

String

Type of content to listen for

callback

Function

Function to call when a shared content load request has been made

The callback method will be passed a single object with the following attributes:

Name
Type
Description

id

Integer

Unique ID of the created shared content

name

String

Name of the shared content

permalink

String

Link to the shared content

content

String

The content itself

label

String

The label for the shared content

Note

It is important to register the listener as soon as possible after the API is loaded. This will allow you to capture a load event that was generated by the initial page load via URL parameters.

Example: Loading shared content with Contraption as the content type

kongregate.sharedContent.addLoadListener("Contraption", onContraptionLoad);
kongregate.services.connect();

function onContraptionLoad(params:Object):void {
  var id:Number        = params.id;
  var name:String      = params.name;
  var permalink:String = params.permalink;
  var content:String   = params.content;
  var label:String     = params.label;

  trace("Contraption " + id + " [" + label + "] loaded: " + content);
}
 
kongregate.sharedContent.addLoadListener("Contraption", onContraptionLoad);

function onContraptionLoad(params) {
  var id = params.id;
  var name = params.name;
  var permalink = params.permalink;
  var content = params.content;
  var label = params.label;

  console.log("Contraption " + id + " [" + label + "] loaded: " + content);
}

Related:

Suggest Edits

SharedContent.Browse

Allow the player to browse shared content
browse(type, sort_order, label)

 

Browsing shared content

By using the browse function on the sharedContent property of the Kongregate API object, you can cause a list of shared content to appear in the user's browser. This will allow them to view, rate, or load shared content for your game. It accepts the following arguments:

Name
Type
Description

type

String

Type of content to browse

sort_order

String

Optional parameter specifying how to sort the content

label

String

Optional label to filter the content with

The possible options for the sort_order parameter are listed below:

Name
Description

by_own

List the content created by the player first

by_newest

Newest content first

by_load_count

Most frequently loaded content first

by_friends

Content created by the player's friends first

Example: Loading shared content with Contraption as the content type

kongregate.sharedContent.addLoadListener("Contraption", onContraptionLoad);

function onContraptionLoad(params:Object):void {
  var id:Number        = params.id;
  var name:String      = params.name;
  var permalink:String = params.permalink;
  var content:String   = params.content;
  var label:String     = params.label;

  trace("Contraption " + id + " [" + label + "] loaded: " + content);
}
 
kongregate.sharedContent.addLoadListener("Contraption", onContraptionLoad);

function onContraptionLoad(params) {
  var id = params.id;
  var name = params.name;
  var permalink = params.permalink;
  var content = params.content;
  var label = params.label;

  console.log("Contraption " + id + " [" + label + "] loaded: " + content);
}

Example: Display a Shared Content browser for Contraptions, only showing those by your friends with the "Level 3 Solution" label

kongregate.sharedContent.browse("Contraption", "by_friends", "Level 3 Solution");
 
kongregate.sharedContent.browse("Contraption", "by_friends", "Level 3 Solution");

Related:

Suggest Edits

SharedContent.Save

Save a custom level or other shared content
save(type, content, callback, thumbnail, label)

 

Saving content

You can use the save function on the sharedContent property of the Kongregate API object to submit shared content on the Kongregate back-end. It accepts a type, content string, callback, and optionally a thumbnail and a label:

Name
Type
Description

type

String

Type of content the user wishes to save, 12 characters max

content

String

Value of content to be saved. We strongly recommend keeping these values under 100K since the game will hang until the content is sent, which can lead to a poor user experience if the content is too large

callback

Function

Function to be called when the operation is completed

thumbnail

DisplayObject or Base64-encoded string

Optional, but highly recommended! Send us a DisplayObject or Base64-encoded image string that we will snapshotted and used as a thumbnail for the content. If this is not provided we will take a picture of the entire stage and use that as the thumbnail (for AS3 games)

label

String

Optional label for sub-classing the shared content.

The callback method will be passed a single object with the following attributes:

Name
Type
Description

success

Boolean

Flag indicating whether or not the operation was successful

id

Integer

Unique ID of the created shared content

name

String

Name of the shared content

permalink

String

Link to the shared content

content

String

The content itself

label

String

The label for the shared content

Example: Save some shared content to as a Contraption with the contents x1y3z10, calling back onContraptionSaved using myContraptionEditor for the thumbnail and with the label Level 3 Solution

kongregate.sharedContent.save('Contraption', 'x1y3z10', onSaved,                         											 myContraptionEditor,'Level 3 Solution');

function onSaved(params:Object):void {
  if (params.success) {
    // The shared content was saved successfully.
    trace("Content saved, id:" + params.id + ", name:" + params.name);
  } else {
    // The shared content was not saved.
    // The most likely cause of this is that the User dismissed the save dialog  
  }
}
 
kongregate.sharedContent.save('Contraption', 'x1y3z10', onSaved,                         											 myContraptionEditor,'Level 3 Solution');

function onSaved(params) {
  if (params.success) {
    // The shared content was saved successfully.
    console.log("Content saved, id:" + params.id + ", name:" + params.name);
  } else {
    // The shared content was not saved.
    // The most likely cause of this is that the User dismissed the save dialog  
  }
}

Related:

Suggest Edits

Stats.Submit

Submit statistics/scores to the server
submit(statistic_name, value)

 

Statistics Client API

Submitting statistics from your game using the Client API couldn't be easier. First, make sure you have read the documentation about how to define statistics for your game on the Kongregate servers.

Submitting statistics

The API for submitting a statistic to our servers is very simple. The submit function on the stats property of the Kongregate API Object takes two arguments. The first is the name of the statistic as you defined earlier, and the second is an integer for the value:

Name
Type
Description

statistic_name

String

The name of the statistic to submit.

value

Integer

The value of the statistic to submit.

Example: Submit various statistics to the server

kongregate.stats.submit("Coins", 1); // The user collected a coin
kongregate.stats.submit("MonstersKilled", 1); //The user killed a monster
kongregate.stats.submit("HighScore", 398); //The user got a score of 398
kongregate.stats.submit("LapTime", 60); //User finished a lap in 60 seconds
 
kongregate.stats.submit("Coins", 1); // The user collected a coin
kongregate.stats.submit("MonstersKilled", 1); //The user killed a monster
kongregate.stats.submit("HighScore", 398); //The user got a score of 398
kongregate.stats.submit("LapTime", 60); //User finished a lap in 60 seconds
Suggest Edits

Authenticate

Verifies a user's identity

 
gethttps://api.kongregate.com/api/authenticate.json
curl -XGET -d '{
  "api_key": "GAMEAPIKEY",
  "user_id": 1480702,
  "game_auth_token": "GAMEAUTHTOKEN"
}' 'https://api.kongregate.com/api/authenticate.json'
curl -XGET -H "Content-type: application/json" -d '{
  "api_key": "BADKEY",
  "user_id": 1480702,
  "game_auth_token": "GAMEAUTHTOKEN"
}' 'https://api.kongregate.com/api/authenticate.json'
curl -XGET -H "Content-type: application/json" -d '{
  "user_id": 1480702
}' 'https://api.kongregate.com/api/authenticate.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "success": true,
  "username": "LordSmatchington",
  "user_id": 1480702
}
{
  "success": false,
  "error": 403,
  "error_description": "Invalid credentials"
}
{
  "success": false,
  "error": 400,
  "error_description": "user_id, game_auth_token, and api_key are required parameters"
}

Query Params

user_id
int32
required

Kongregate User ID

game_auth_token
string
required

Game Authentication Token

api_key
string
required

Your Private API Key

 

The Authentication API allows Kongregate players to play any game without registering or entering a password. By making a call to the web service from your game server you can securely determine the player's Kongregate user id and username.

Note

This method should only be called from a server, not a game client.

For more information on how Kongregate users should be authenticated in your game, see this document.

Suggest Edits

Badges

Retrieves badge definitions

 
get/badges.json
curl -XGET 'http://api.kongregate.com/badges.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "badge_id": 1993,
    "created_at": "2015-11-03T05:56:50-08:00"
  },
  {
    "badge_id": 1852,
    "created_at": "2012-11-27T18:34:48-08:00"
  },
  {
    "badge_id": 1853,
    "created_at": "2012-11-27T18:34:48-08:00"
  },
  {
    "badge_id": 1250,
    "created_at": "2010-12-08T09:48:34-08:00"
  },
  {
    "badge_id": 1251,
    "created_at": "2010-12-08T09:48:34-08:00"
  },
  {
    "badge_id": 250,
    "created_at": "2009-09-28T19:31:38-07:00"
  },
  {
    "badge_id": 249,
    "created_at": "2009-09-28T19:23:16-07:00"
  }
]
 

This endpoint is useful for people making things like the Kongregate Firefox Sidebar. There are two different badge feeds - one for badge releases on the site, and the other as a list of badges a particular user has earned.

You can query for which badges a user has been awarded using the User Badges API.

Suggest Edits

Badges - User

Retrieves information about a user's badges

 
get/accounts/username/badges.json
curl -XGET 'http://api.kongregate.com/accounts/vinsonb/badges.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "badge_id": 1993,
    "created_at": "2015-11-03T05:56:50-08:00"
  },
  {
    "badge_id": 1852,
    "created_at": "2012-11-27T18:34:48-08:00"
  },
  {
    "badge_id": 1853,
    "created_at": "2012-11-27T18:34:48-08:00"
  },
  {
    "badge_id": 1250,
    "created_at": "2010-12-08T09:48:34-08:00"
  },
  {
    "badge_id": 1251,
    "created_at": "2010-12-08T09:48:34-08:00"
  },
  {
    "badge_id": 250,
    "created_at": "2009-09-28T19:31:38-07:00"
  },
  {
    "badge_id": 249,
    "created_at": "2009-09-28T19:23:16-07:00"
  },
  {
    "badge_id": 248,
    "created_at": "2009-09-16T23:09:00-07:00"
  },
  {
    "badge_id": 128,
    "created_at": "2007-12-07T14:06:03-08:00"
  },
  {
    "badge_id": 127,
    "created_at": "2007-12-07T13:50:15-08:00"
  },
  {
    "badge_id": 126,
    "created_at": "2007-12-07T13:50:08-08:00"
  },
  {
    "mobile_badge_id": 2220,
    "created_at": "2013-12-19T18:26:14-08:00"
  },
  {
    "mobile_badge_id": 2927,
    "created_at": "2013-12-05T19:26:51-08:00"
  },
  {
    "mobile_badge_id": 2926,
    "created_at": "2013-09-16T17:29:52-07:00"
  },
  {
    "mobile_badge_id": 2916,
    "created_at": "2013-08-08T19:26:18-07:00"
  },
  {
    "mobile_badge_id": 2907,
    "created_at": "2013-08-08T09:02:57-07:00"
  },
  {
    "mobile_badge_id": 2219,
    "created_at": "2013-04-23T05:34:13-07:00"
  },
  {
    "mobile_badge_id": 2218,
    "created_at": "2013-04-23T05:34:12-07:00"
  },
  {
    "mobile_badge_id": 1717,
    "created_at": "2012-12-30T07:32:38-08:00"
  },
  {
    "mobile_badge_id": 1604,
    "created_at": "2011-03-29T10:02:02-07:00"
  },
  {
    "mobile_badge_id": 1724,
    "created_at": "2011-03-29T10:00:25-07:00"
  },
  {
    "mobile_badge_id": 1670,
    "created_at": "2011-02-16T15:03:41-08:00"
  },
  {
    "mobile_badge_id": 1611,
    "created_at": "2011-02-01T12:34:58-08:00"
  }
]

Path Params

username
string
required

Username of the user to retrieve badges for

 

This endpoint allows you to retrieve a list of badges that a given user has been awarded. You can query for a list of all available badges using the Badges API.

Suggest Edits

Characters

Creates/manages game characters for use with guilds

 
posthttps://api.kongregate.com/api/characters.json
curl -XPOST -H "Content-type: application/json" -d '{
  "api_key": "GAMEAPIKEY",
  "user_id": 426367,
  "server_identifier": "101",
  "server_name": "Gotham01",
  "character_identifier": "12582",
  "character_name": "Batman",
  "guild_identifier": "234",
  "guild_name": "JusticeLeague",
  "guild_admin_level": "admin"
}' 'https://api.kongregate.com/api/characters.json'
curl -XPOST -H "Content-type: application/json" -d '{
  "api_key": "GAMEAPIKEY",
  "user_id": 426367,
  "server_identifier": "101",
  "server_name": "Gotham01",
  "character_identifier": "12582",
  "character_name": "Batman"
}' 'https://api.kongregate.com/api/characters.json'
curl -XPOST -H "Content-type: application/json" -d '{
  "api_key": "GAMEAPIKEY",
  "user_id": 426367,
  "server_identifier": "101",
  "server_name": "Gotham01",
  "character_identifier": "12582",
  "character_name": "Batman",
  "guild_identifier": "234",
  "guild_name": "JusticeLeague"
}' 'https://api.kongregate.com/api/characters.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "success": true,
  "user_id": 426367,
  "server_identifier": "101",
  "guild_identifier": "234",
  "character_identifier": "12582"
}
{
  "success": true,
  "user_id": 426367,
  "server_identifier": "101",
  "guild_identifier": null,
  "character_identifier": "12582"
}
{
  "success": true,
  "user_id": 426367,
  "server_identifier": "101",
  "guild_identifier": "234",
  "character_identifier": "12582"
}

Body Params

api_key
string
required

Your private API key

character_identifier
string
required

Unique (per-server) identifier for the user

character_name
string
required

Display name for the user

server_identifier
string

Unique identifier for the server the guild exists on

server_name
string

Display name for the server the guild exists on

guild_identifier
string

Unique (per-server) identifier for the guild

guild_name
string

Display name for the guild

user_id
int32

The Kongregate user id (if any) of the user

guild_admin_level
string

Set to superadmin or admin to grant privileges

 

Adding a Character to a Guild

Adding a player's character to a guild is handled by a call to /characters.json. In the case that a character is added to a guild that has not been created yet, this call will have the side effect of creating that guild.

There are three types of guild members:

  • Admin: Can lock, sticky, edit, and hide forum posts in the guild forum. We suggest giving guild officers an admin status.
  • Superadmin: Currently has the same permissions as a regular admin, but we may change that later. It would be best to restrict this to the owner of a guild.
  • Member: Has access to and can post in guild chat and forums. To denote a character as a member, don't pass the guild_admin_level parameter when adding the character to the guild.

Removing a Character from a Guild

In the case that a user leaves a guild, or is booted from one, that user should no longer have access to guild specific forums or chat. The call to remove a character is almost identical to the call to add a character, except the guild_identifier and guild_name shouldn't be submitted at all (or alternatively submitted as empty strings).

Revoking a Character's Superadmin or Admin Status

You can revoke a user's Superadmin or Admin status similarly with a call that resubmits the all of the character's guild parameters the same, except without the guild_admin_status parameter.

Suggest Edits

Guilds - Create

Creates/updates a guild definition

 
posthttps://api.kongregate.com/api/guilds.json
curl -XPOST -H "Content-type: application/json" -d '{
  "api_key": "GAMEAPIKEY",
  "server_identifier": "101",
  "server_name": "Gotham01",
  "guild_identifier": "234",
  "guild_name": "JusticeLeague"
}' 'https://api.kongregate.com/api/guilds.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "success": true,
  "server_identifier": "101",
  "guild_identifier": "234"
}

Body Params

api_key
string
required

Your private API key

guild_identifier
string
required

Unique (per-server) identifier for the guild

guild_name
string
required

Display name for the guild

server_identifier
string

The unique identifier for the server

server_name
string

The display name for the server

 
Suggest Edits

Guilds - Destroy

Destroys a guild definition

 
posthttps://api.kongregate.com/api/guilds/destroy.json
curl -XPOST -H "Content-type: application/json" -d '{
  "api_key": "GAMEAPIKEY",
  "server_identifier": "101",
  "guild_identifier": "234"
}' 'https://api.kongregate.com/api/guilds/destroy.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "server_identifier": "101",
  "guild_identifier": "234"
}

Body Params

api_key
string
required

Your private API key

guild_identifier
string
required

The unique (per-server) identifier for the guild

server_identifier
string

The unique identifier of the server

 
Suggest Edits

High Scores

Retrieve high scores for a statistic

 
gethttps://api.kongregate.com/api/high_scores/scope/:statistic_id.json
curl -XGET 'https://api.kongregate.com/api/high_scores/weekly/22544.json'
curl -XGET 'https://api.kongregate.com/api/high_scores/lifetime/22544.json?lifetime_page=4'
curl -XGET 'https://api.kongregate.com/api/high_scores/lifetime/22544.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "weekly_scores": [
    {
      "username": "EnglishDiaries",
      "level": 48,
      "score": 2518,
      "avatar_url": "https://cdn1.kongcdn.com/user_avatars/0888/8221/x_dc78b392.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "Testing_1_2_3_",
      "level": 28,
      "score": 2405,
      "avatar_url": "https://cdn3.kongcdn.com/assets/avatars/defaults/fluff.png?i10c=img.resize(width:28)"
    },
    {
      "username": "Pigjr1",
      "level": 52,
      "score": 1745,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0155/1906/Pig.png?i10c=img.resize(width:28)"
    }
  ],
  "page_count": 1,
  "per_page": 25,
  "success": true
}
{
  "lifetime_scores": [
    {
      "username": "Sens3",
      "level": 41,
      "score": 4898,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0089/5543/soul_reaper.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "kuchi666",
      "level": 28,
      "score": 4836,
      "avatar_url": "https://cdn3.kongcdn.com/assets/avatars/defaults/fluff.png?i10c=img.resize(width:28)"
    },
    {
      "username": "luk4sq",
      "level": 52,
      "score": 4795,
      "avatar_url": "https://cdn4.kongcdn.com/user_avatars/0026/0050/avatar-two-face.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "Sellyme",
      "level": 56,
      "score": 4752,
      "avatar_url": "https://cdn1.kongcdn.com/user_avatars/0007/6811/B78dU.png?i10c=img.resize(width:28)"
    },
    {
      "username": "Nerava",
      "level": 48,
      "score": 4584,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0033/3252/Nerava_Icon.png?i10c=img.resize(width:28)"
    },
    {
      "username": "metallica69",
      "level": 13,
      "score": 4478,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0023/5456/Steven.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "goosefish",
      "level": 17,
      "score": 4411,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0115/2814/1272563788.8214335108.png?i10c=img.resize(width:28)"
    },
    {
      "username": "TDMazeMaster",
      "level": 22,
      "score": 4050,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0014/2206/face.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "MidgetMan",
      "level": 65,
      "score": 3992,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0003/8272/ProfGintoki.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "BestMte",
      "level": 65,
      "score": 3820,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0152/1974/Lonely.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "AGW_IS_FAKE",
      "level": 62,
      "score": 3808,
      "avatar_url": "https://cdn3.kongcdn.com/user_avatars/0055/4579/avm_avatar_alien_lurker.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "jamesbean9",
      "level": 30,
      "score": 3806,
      "avatar_url": "https://cdn4.kongcdn.com/user_avatars/0121/6259/Blue_Green_Flames_by_evilblackdragon12.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "Pandorite",
      "level": 41,
      "score": 3744,
      "avatar_url": "https://cdn4.kongcdn.com/user_avatars/0008/6524/nes_ms_pac_man_ghost-copy1225379243.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "BenV",
      "level": 40,
      "score": 3698,
      "avatar_url": "https://cdn1.kongcdn.com/user_avatars/0000/0765/starbuckbig.png?i10c=img.resize(width:28)"
    },
    {
      "username": "coreyog",
      "level": 10,
      "score": 3652,
      "avatar_url": "https://cdn1.kongcdn.com/assets/avatars/defaults/darkness.png?i10c=img.resize(width:28)"
    },
    {
      "username": "Yukidaruma",
      "level": 65,
      "score": 3650,
      "avatar_url": "https://cdn3.kongcdn.com/user_avatars/0055/6052/666-satan-1963987.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "y0ttabyte",
      "level": 65,
      "score": 3618,
      "avatar_url": "https://cdn4.kongcdn.com/user_avatars/0018/5263/aged_wb20131201063656632994.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "Ehlmo",
      "level": 62,
      "score": 3604,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0031/2266/sparta.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "ravenhawk82",
      "level": 22,
      "score": 3603,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0066/9657/avatar_atlas3.png?i10c=img.resize(width:28)"
    },
    {
      "username": "goodrich",
      "level": 32,
      "score": 3593,
      "avatar_url": "https://cdn1.kongcdn.com/user_avatars/0007/1665/champloo02_1600.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "SeargX",
      "level": 28,
      "score": 3589,
      "avatar_url": "https://cdn3.kongcdn.com/user_avatars/0059/4076/Gmod_MSN2.jpg?i10c=img.resize(width:28)"
    },
    {
      "username": "Angelow",
      "level": 38,
      "score": 3588,
      "avatar_url": "https://cdn4.kongcdn.com/user_avatars/0122/4524/1417469722.92521249311.png?i10c=img.resize(width:28)"
    },
    {
      "username": "dna0008",
      "level": 65,
      "score": 3575,
      "avatar_url": "https://cdn4.kongcdn.com/user_avatars/0110/4720/7.png?i10c=img.resize(width:28)"
    },
    {
      "username": "Mongatard",
      "level": 24,
      "score": 3574,
      "avatar_url": "https://cdn3.kongcdn.com/assets/avatars/defaults/robotboy.png?i10c=img.resize(width:28)"
    },
    {
      "username": "CaioFreitas",
      "level": 55,
      "score": 3574,
      "avatar_url": "https://cdn2.kongcdn.com/user_avatars/0008/8051/shelby.jpg?i10c=img.resize(width:28)"
    }
  ],
  "page_count": 5,
  "per_page": 25,
  "success": true
}

Path Params

scope
string
required

daily, weekly, or lifetime

statistic_id
int32
required

Statistic ID to retrieve scores for

Query Params

lifetime_page
int32

Optional page number if using the lifetime scope

weekly_page
int32

Optional page number if using the weekly scope

today_page
int32

Optional page number if using the daily scope

 

Note

You can find statistic IDs for your game on the "edit statistics" page

Suggest Edits

High Scores - Friends

Retrieve a list of high scores for a user's friends

 
gethttps://api.kongregate.com/api/high_scores/friends/statistic_id/:user_id.json
curl -XGET 'https://api.kongregate.com/api/high_scores/friends/22544/32.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "friends_scores": [
    {
      "username": "BenV",
      "level": 40,
      "score": 3698,
      "avatar_url": "https://cdn1.kongcdn.com/user_avatars/0000/0765/starbuckbig.png?i10c=img.resize(width:28)"
    },
    {
      "username": "ctide",
      "level": 13,
      "score": 1242,
      "avatar_url": "https://cdn3.kongcdn.com/assets/avatars/defaults/robotboy.png?i10c=img.resize(width:28)"
    }
  ],
  "page_count": 1,
  "per_page": 25,
  "success": true
}

Path Params

statistic_id
int32
required

Statistic ID to retrieve scores for

user_id
int32
required

Kongregate user ID of the user to retrieve friend's scores for

 
Suggest Edits

Items - Consume

Use a consumable item from a user's inventory

 
posthttps://api.kongregate.com/api/use_item.json
curl -XGET -H "Content-type: application/json" -d '{
  "api_key": "GAMEAPIKEY",
  "user_id": 32,
  "game_auth_token": "TOKEN",
  "id": 123456789
}' 'https://api.kongregate.com/api/use_item.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "success": true,
  "remaining_uses": 9,
  "usage_record_id": 7653
}

Body Params

api_key
string
required

Your private API key

user_id
int32
required

The Kongregate user ID of the owner of the item

game_auth_token
string
required

The game_auth_token for the user

id
int32
required

The item instance ID

 

This HTTP endpoint allows you to use a limited-use item belonging to a user. You must pass in the id of the item instance to use. This id can be obtained from the user's inventory. It is important to note that this is NOT the same as the item id which is returned from the items action. Calling this action on an unlimited use item will return failure, since that operation is not supported.

Note:

Note

This method is to be called from a server only. If, and only if, the game is client-side only with no server, you will need to use our client API call to consume items.

Suggest Edits

Items - List

Retrieves static item definitions from the server

 
gethttps://api.kongregate.com/api/items.json
curl -XGET -d '{
  "api_key": "GAMEAPIKEY"
}' 'https://api.kongregate.com/api/items.json'
curl -XGET -d '{
  "api_key": "GAMEAPIKEY",
  "tags": "sword,awesome"
}' 'https://api.kongregate.com/api/items.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "success": true,
  "items": [
    {
      "id": 1,
      "identifier": "sharp-sword",
      "name": "Sharp Sword",
      "description": "A sharp sword",
      "price": 10,
      "tags": [
        "sword",
        "awesome"
      ]
    },
    {
      "id": 2,
      "identifier": "dull-sword",
      "name": "Dull Sword",
      "description": "A dull sword",
      "price": 1,
      "tags": [
        "sword"
      ]
    },
    {
      "id": 3,
      "identifier": "axe",
      "name": "Axe",
      "description": "An Axe",
      "price": 10,
      "tags": [
        "axe"
      ]
    }
  ]
}
{
  "success": true,
  "items": [
    {
      "id": 1,
      "identifier": "sharp-sword",
      "name": "Sharp Sword",
      "description": "A sharp sword",
      "price": 10,
      "tags": [
        "sword",
        "awesome"
      ]
    }
  ]
}

Query Params

api_key
string
required

Your private API key

tags
string

Comma-delimited list of tags to filter by

 
Suggest Edits

Items - User

Retrieve a user's inventory

 
gethttps://api.kongregate.com/api/user_items.json
curl -XGET 'https://api.kongregate.com/api/user_items.json?api_key=GAMEAPIKEY&user_id=1'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "success": true,
  "items": [
    {
      "id": 100,
      "identifier": "sharp-sword",
      "name": "Sharp Sword",
      "description": "A sharp sword",
      "remaining_uses": null,
      "data": null
    },
    {
      "id": 101,
      "identifier": "potion",
      "name": "Potion",
      "description": "A Healing Potion",
      "remaining_uses": 10,
      "data": null
    }
  ]
}

Query Params

api_key
string
required

Your private API key

user_id
int32

Kongregate User ID of the user you wish to retrieve items for

 

This HTTP endpoint allows you to request the list of items that belong to a user. These are referred to as item instances. Item instances will only be returned by this method if they have remaining uses, or are unlimited-use items. This should be done after receiving a callback or successful transaction event, as well as each time the game loads in order to check for un-credited items in the inventory.

Note

This call should only be made from a server. To retrieve a user's items from your client, see the requestUserItemList method.

Suggest Edits

Kongpanions

Retrieve information about Kongpanions

 
gethttps://api.kongregate.com/api/kongpanions/index.json
curl -XGET 'https://api.kongregate.com/api/kongpanions/index.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "kongpanions": [
    {
      "name": "Kongbot",
      "description": "Objectives: [A] Maintain, upgrade Kongregate [B] LASERS FROM EYES [C] Learn to love <3",
      "tags": [
        "robot",
        "kongregate"
      ],
      "normal_icon_url": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0001/kongbot_2.png",
      "normal_icon_url_medium": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0001/kongbot_2.png?i10c=img.resize(height:90)",
      "normal_icon_url_small": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0001/kongbot_2.png?i10c=img.resize(height:45)",
      "shiny_icon_url": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0002/kongbot_shiny_2.png",
      "shiny_icon_url_medium": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0002/kongbot_shiny_2.png?i10c=img.resize(height:90)",
      "shiny_icon_url_small": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0002/kongbot_shiny_2.png?i10c=img.resize(height:45)",
      "id": 1
    },
    {
      "name": "Puff Catty",
      "description": "You've got to be kitten me!",
      "tags": [
        "cat",
        "animal",
        "blue"
      ],
      "normal_icon_url": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0003/cat.png",
      "normal_icon_url_medium": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0003/cat.png?i10c=img.resize(height:90)",
      "normal_icon_url_small": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0003/cat.png?i10c=img.resize(height:45)",
      "shiny_icon_url": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0004/cat_shiny.png",
      "shiny_icon_url_medium": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0004/cat_shiny.png?i10c=img.resize(height:90)",
      "shiny_icon_url_small": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0004/cat_shiny.png?i10c=img.resize(height:45)",
      "id": 2
    }
  ]
}
 
Suggest Edits

Kongpanions - User

Retrieve the list of Kongpanions a user owns

 
gethttps://api.kongregate.com/api/kongpanions.json
curl -XGET 'https://api.kongregate.com/api/kongpanions.json?username=BenV'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "kongpanions": [
    {
      "name": "Kongbot",
      "description": "Objectives: [A] Maintain, upgrade Kongregate [B] LASERS FROM EYES [C] Learn to love <3",
      "tags": [
        "robot",
        "kongregate"
      ],
      "shiny": false,
      "normal_icon_url": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0001/kongbot_2.png",
      "normal_icon_url_medium": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0001/kongbot_2.png?i10c=img.resize(height:90)",
      "normal_icon_url_small": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0001/kongbot_2.png?i10c=img.resize(height:45)",
      "shiny_icon_url": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0002/kongbot_shiny_2.png",
      "shiny_icon_url_medium": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0002/kongbot_shiny_2.png?i10c=img.resize(height:90)",
      "shiny_icon_url_small": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0002/kongbot_shiny_2.png?i10c=img.resize(height:45)",
      "id": 1
    },
    {
      "name": "Puff Catty",
      "description": "You've got to be kitten me!",
      "tags": [
        "cat",
        "animal",
        "blue"
      ],
      "shiny": false,
      "normal_icon_url": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0003/cat.png",
      "normal_icon_url_medium": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0003/cat.png?i10c=img.resize(height:90)",
      "normal_icon_url_small": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0003/cat.png?i10c=img.resize(height:45)",
      "shiny_icon_url": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0004/cat_shiny.png",
      "shiny_icon_url_medium": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0004/cat_shiny.png?i10c=img.resize(height:90)",
      "shiny_icon_url_small": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0004/cat_shiny.png?i10c=img.resize(height:45)",
      "id": 2
    },
    {
      "name": "Cooper",
      "description": "He's not sharing that ball.  Don't terrier self up over it!",
      "tags": [
        "kongdog",
        "animal",
        "white"
      ],
      "shiny": true,
      "normal_icon_url": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0009/Cooper.png",
      "normal_icon_url_medium": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0009/Cooper.png?i10c=img.resize(height:90)",
      "normal_icon_url_small": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0009/Cooper.png?i10c=img.resize(height:45)",
      "shiny_icon_url": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0010/cooper_shiny.png",
      "shiny_icon_url_medium": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0010/cooper_shiny.png?i10c=img.resize(height:90)",
      "shiny_icon_url_small": "https://assets.kongregate.com/assets/kongpanion_icons/0000/0010/cooper_shiny.png?i10c=img.resize(height:45)",
      "id": 5
    }
  ]
}

Query Params

username
string

The username of the user to retrieve Kongpanions for

user_id
string

The user id of the user to retrieve Kongpanions for

 
Suggest Edits

Private Messages

Send messages to Kongregate users

 
posthttps://api.kongregate.com/api/private_message.json
curl -XPOST -H "Content-type: application/json" -d '{
  "api_key": "GAMEAPIKEY",
  "user_id": 32,
  "content": "Hello, world"
}' 'https://api.kongregate.com/api/private_message.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "success": true
}
{
  "success": false,
  "errors": [
    "Game cannot send a PM to someone who hasn't played the game within 2 weeks."
  ]
}

Body Params

api_key
string
required

Your private api key

content
string
required

The text content to send to the user. Any HTML will be stripped, though bold and italics will be rendered.

user_id
int32

User id of the recipient of the message

username
string

Username of the recipient of the message

image_url
string

An image to be included with the message

 

Note

This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please contact us

This function allows you to send a message to a player through a server-side POST, even if that player is offline. It can be used to let players know about updates, information directly relevant to their game status, or whatever else would make sense. However, please keep the messages relevant and well-targeted. We reserve the right to discontinue access to this API if a game is using it excessively or sending information that is not applicable to the recipient.

The targeted user must have played the game recently (within two weeks), and only one message can be sent per player per day.

The user_id and username parameters are optional, but you must include one or the other.

Suggest Edits

Shared Links - Create

Create a shared link

 
posthttps://api.kongregate.com/api/shared_links/create.json
curl -XPOST -H "Content-type: application/json" -d '{
  "api_key": "GAMEAPIKEY",
  "game_auth_token": "GAMEAUTHTOKEN",
  "user_id": 32,
  "id": "MySharedLink",
  "link_params": "kv_test=foo%26kv_test2=bar&name=Joe%27s%20Dragon",
  "expiration": 1448844315,
  "kv_params": "{\"Difficulty\":\"Hard\",\"Total HP\":8675309}"
}' 'https://api.kongregate.com/api/shared_links/create.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "success": true
}

Body Params

api_key
string
required

Your private API key

game_auth_token
string
required

The game_auth_token for the game/user combination

user_id
int32
required

User id of the user

id
string
required

Unique identifier of the event in your system

name
string
required

Name of the link

type
string
required

A type or category for the link that can be used for filtering

link_params
string
required

URL-encoded parameters to pass into the game frame. Only parameters starting with kv_ will be passed through

expiration
int32
required

UNIX timestamp for when the link should no longer be shown to users

kv_params
string

Optional JSON encoded string of an object containing extra information about the link

 

The above example creates new shared link, in this case a raid called "Joe's Dragon" that has a "Dragon" type and expires Monday, November 30th 2015, 00:45:15 (GMT). Additionally, if we expand the raid link we will discover that it has a difficulty rating of "Hard" and has 867,5309 hit points.

One point of potential confusion to note: kv_params is a specific set of key-values that we (Kongregate) will process. On the other hand, the link_params, which also need to be prefaced with kv_ but need to have the &'s encoded as %26, are what will be passed in to the iframe (in this case, kv_test and kv_test2).

Suggest Edits

Shared Links - Destroy

Destroy a shared link

 
posthttps://api.kongregate.com/api/shared_links/id/destroy.json
curl -XPOST -H "Content-type: application/json" -d '{
  "api_key": "GAMEAPIKEY",
  "game_auth_token": "GAMEAUTHTOKEN",
  "user_id": 32
}' 'https://api.kongregate.com/api/shared_links/MySharedLink/destroy.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "success": true
}

Path Params

id
string
required

Unique identifier of the link in your system

Body Params

api_key
string
required

Your private API key

game_auth_token
string
required

The game_auth_token for the game/user combination

user_id
int32
required

User id of the user

 

If you wish to destroy a shared link (for example, a raid is completed prior to the end time, or the shared gold has been redeemed the maximum number of times), you can do this with a call to destroy. Simply include the ID in the URL after shared_links and it will be removed from the listing. Please note that validation of links is still your responsibility - destroying a shared link simply removes it from our listing.

Suggest Edits

Statistics

Submit statistics and high scores

 
posthttps://api.kongregate.com/api/submit_statistics.json
curl -XPOST -H "Content-type: application/json" -d '{
  "api_key": "GAMEAPIKEY",
  "user_id": 32,
  "GamesWon": 1,
  "Coins": 45,
  "Score": 1000
}' 'https://api.kongregate.com/api/submit_statistics.json'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "success": true
}

Body Params

api_key
string
required

Your private API key

user_id
string
required

The Kongregate user ID for the user to submit for

example_statistic_name
int32

Any other parameters will be submitted as statistics

another_example_statistic_name
int32

Any other parameters will be submitted as statistics

 

This method submits statistics for uses with badges and high scores. Any parameters other than api_key and user_id are assumed to be statistic names for your game, and will be submitted as such.

Suggest Edits

User Information

Retrieve information about Kongregate users

 
gethttps://api.kongregate.com/api/user_info.json
curl -XGET 'https://api.kongregate.com/api/user_info.json?username=ap_u2&friends=true'
curl -XGET 'https://api.kongregate.com/api/user_info.json?user_ids=1,2'

A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "friends": [
    "ap_u",
    "KIXEYE",
    "llbundle",
    "anthony",
    "ap_u1"
  ],
  "muted_users": [],
  "friend_ids": [
    1047195,
    5235025,
    3903986,
    2090,
    20350241
  ],
  "muted_user_ids": [],
  "user_id": 2295077,
  "username": "ap_u2",
  "private": false,
  "page_num": 1,
  "num_pages": 1,
  "success": true,
  "user_vars": {
    "username": "ap_u2",
    "level": 2,
    "points": 101,
    "avatar_url": "https://cdn1.kongcdn.com/assets/avatars/defaults/bug.png?i10c=img.resize(width:50)",
    "chat_avatar_url": "https://assets.kongregate.com/assets/avatars/defaults/bug.png?i10c=img.resize(width:16)",
    "developer": false,
    "moderator": false,
    "admin": false,
    "game_title": "Tom Clancy’s Endwar® Online",
    "game_url": "http://www.kongregate.com/games/Ubisoft_Shanghai/tom-clancy-s-endwar-online"
  }
}
{
  "success": true,
  "users": [
    {
      "friends": [],
      "muted_users": [],
      "friend_ids": [],
      "muted_user_ids": [],
      "user_id": 1,
      "username": "jimgreer",
      "private": false,
      "page_num": 1,
      "num_pages": 1,
      "success": true,
      "user_vars": {
        "username": "jimgreer",
        "level": 48,
        "points": 15827,
        "avatar_url": "https://cdn1.kongcdn.com/user_avatars/0000/0001/1402337637.680815584717.png?i10c=img.resize(width:50)",
        "chat_avatar_url": "https://assets.kongregate.com/user_avatars/0000/0001/avatar_atlas3_chat.png?i10c=img.resize(width:16)",
        "developer": true,
        "moderator": true,
        "admin": false,
        "gender": "Male",
        "game_title": "Musaic Box",
        "game_url": "http://www.kongregate.com/games/Badim/musaic-box"
      }
    },
    {
      "friends": [],
      "muted_users": [],
      "friend_ids": [],
      "muted_user_ids": [],
      "user_id": 2,
      "username": "emily_greer",
      "private": false,
      "page_num": 1,
      "num_pages": 1,
      "success": true,
      "user_vars": {
        "username": "emily_greer",
        "level": 24,
        "points": 3853,
        "avatar_url": "https://cdn4.kongcdn.com/user_avatars/0000/0002/LegendsofKongEmily.png?i10c=img.resize(width:50)",
        "chat_avatar_url": "https://assets.kongregate.com/user_avatars/0000/0002/Anex_chat.png?i10c=img.resize(width:16)",
        "developer": false,
        "moderator": true,
        "admin": true,
        "gender": "Female",
        "age": 41,
        "game_title": "Endless Boss Fight",
        "game_url": "http://www.kongregate.com/games/WhiteMilkGames/endless-boss-fight"
      }
    }
  ]
}

Query Params

username
string

Username to retrieve information about

user_id
int32

User ID of user to retrieve information about

usernames
string

Comma-delimited list of users to retrieve information about (max 50)

user_ids
string

Comma-delimited list of users IDs to retrieve information about (max 50)

page_num
int32

Page number to retrieve

friends
boolean

Indicates whether or not to include the friends list. Only supported when requesting information about a single user.

 

Note

If you are intending to load lots of user information (for example, loading the avatar URLs for all of a user's friends), you should use the multiple id/username version of the request to avoid long load times or timeouts due to making lots of requests. These group requests can be done with up to 50 user IDs or usernames at a time. The friends flag is not supported when requesting multiple records.