Kongregate Developers

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 apps@kongregate.com.

Shared Links (Raids) API

A number of games on Kongregate have guilds, raids, or other group events within them that players can join by clicking on a link, usually posted in chat or the forums. This is an excellent social feature, but can also clog up chat rooms and be difficult to track, especially for new players. To help clean up chat and provide a better organization method for games and players, we put together a Shared Links API.

More broadly, the API provides a way for a game to provide a link, the relevant URL parameters, and some basic details about the item. These links will appear on a separate tab from chat and be filterable by type and sorted by expiration. Clicking on the link will load within the game's frame, removing the weird and unnecessary page reload or new tab that previously occurred.

There are only two methods needed to control this functionality - creating a raid, and destroying a raid. Kongregate will take care of sorting and filtering the list of raids automatically. This is all done through server-to-server calls in order to prevent spamming of links from client-side users.

Creating a Shared Link

POST https://api.kongregate.com/api/shared_links/create.json
Required params:
  • user_id: User id of the user
  • game_auth_token: The game_auth_token for the game/user combination
  • api_key: The api key assigned to your game
  • id: a unique identifier for the event or object in your system
  • link_params: URL parameters for the link (using kv_ to prepend the parameter names)
  • name: name for the link that will be displayed to the user
  • type: A type or category for the link that can be used for filtering
  • expiration: UNIX timestamp for when the link should no longer be shown to users
Optional params:
  • kv_params: A set of key-value pairs that are used to give extra information about the shared link
Response fields:
  • success: true/false depending on if the request was successful
  • error: error code integer, if any
  • error_description: error code description string, if any
POST https://api.kongregate.com/api/shared_links/create.json?api_key=API_KEY&game_auth_token=GAME_AUTH_TOKEN&user_id=USER_ID&id=SHARED_LINK_ID&link_params=kv_test=foo%26kv_test2=bar&name=Joe%27s%20Dragon&type=Dragon&expiration=1448844315&kv_params=%7B%22Difficulty%22:%22Hard%22,%22Total HP%22:8675309%7D
{
  "success": true
}

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's, are what will be passed in to the iframe (in this case, kv_test and kv_test2).

Destroying a Shared Link

POST https://api.kongregate.com/api/shared_links/:id/destroy.json
Required params:
  • user_id: User id of the user
  • game_auth_token: The game_auth_token for the game/user combination
  • api_key: The api key assigned to your game
    • Response fields:
      • success: true/false depending on if the request was successful
      • error: error code integer, if any
      • error_description: error code description string, if any
POST https://api.kongregate.com/api/shared_links/5893125/destroy.json
{
  "success": true
}

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 through the destroy.json call. 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.

Comments