Contacts Config Format

Overview

Contacts are a flexible alternative to the traditional friends system. Unlike a simple friends list, contacts can be split into named groups, allowing you to manage social connections differently across game modes or features.

To learn how to work with contacts and groups in your game, see the .

Adding Contacts Config

To use contacts, you need to:

Add the contacts description to the contacts config.
Deploy configs to services.

Contacts Description Format

{
  "allowedGroups": ["Arkanoid"]
}

Fields

allowedGroups list of string required 

A list of contact group names allowed in the game. Maximum 20 groups.

All contacts in the game are split into groups. Depending on your needs, you can use a single group or multiple groups.

Single group — suitable for most games:

{
  "allowedGroups": ["DungeonGame"]
}

Multiple groups — useful when different game modes need separate contact lists:

{
  "allowedGroups": ["DungeonGame_solo", "DungeonGame_duo", "DungeonGame_squad"]
}

matching object optional 

Configures contact update notifications. If not set, notifications are disabled.

Each notification has the following fields:

notificationEnabled bool required : If true, enables notifications when a contact’s status changes.
notificationKey string optional: Notification key sent with the update event. Defaults to "notify_contacts_update".

"matching": {
  "notificationEnabled": true,
  "notificationKey": "notify_contacts_update"
}

limitedAccess array of objects optional 

Defines access rules controlling which players can use contacts. Maximum 20 rules. Rules with disabled: true are ignored. If no enabled rules are present, access is allowed for all players.

Each rule has the following fields:

allow bool required : If true, players matching this rule are allowed access. If false, they are denied.
disabled bool optional : If true, this rule is ignored. Defaults to false.
purchased list of string (GUID) optional : Allow if the player has purchased any of the listed items. Maximum 100 entries.
notPurchased list of string (GUID) optional : Allow if the player has not purchased any of the listed items. Maximum 100 entries.
authTag list of string optional : Allow if the player’s auth tag matches any of the listed values. Maximum 100 entries.
notAuthTag list of string optional : Allow if the player’s auth tag does not match any of the listed values. Maximum 100 entries.
authType list of string optional : Allow if the player’s auth type matches any of the listed values. Maximum 100 entries.
notAuthType list of string optional : Allow if the player’s auth type does not match any of the listed values. Maximum 100 entries.
platform list of string optional : Allow if the player’s platform matches any of the listed values. Maximum 100 entries.
notPlatform list of string optional : Allow if the player’s platform does not match any of the listed values. Maximum 100 entries.
loginWildcard list of string optional : Allow if the player’s login matches any of the listed wildcard patterns. Maximum 100 entries.
notLoginWildcard list of string optional : Allow if the player’s login does not match any of the listed wildcard patterns. Maximum 100 entries.
comment string optional : Internal comment for this rule. Maximum 512 characters.
errorMessage string optional : Error message returned to the client when access is denied. Maximum 512 characters.

"limitedAccess": [
  {
    "allow": true,
    "platform": ["pc", "console"],
    "errorMessage": "Contacts are not available on this platform."
  }
]

loginChecks array of objects optional 

Defines additional checks performed during login. Maximum 20 checks.

Each check has the following fields:

needToken bool required : If true, an auth token is required to perform this check.
type string optional : Type of the check. Possible values: GENERIC (default), CURRENCY.
requestUrls list of string (URL) optional : URLs to call during the check. Maximum 100 entries.
action string optional : Action name to perform. Maximum 512 characters.
comment string optional : Internal comment. Maximum 4096 characters.
errorOverride string optional : Custom error message to return on failure. Maximum 512 characters.
knownErrors list of string optional : List of known error messages that are handled gracefully. Maximum 100 entries.
timeoutSec int optional : Timeout in seconds for the check request. Range: 0–86400. Defaults to 0.
denyLoginOnReqFailure bool optional : If true, login is denied when the check request fails. Defaults to false.

"loginChecks": [
  {
    "type": "GENERIC",
    "needToken": true,
    "requestUrls": ["https://auth.example.com/check"],
    "timeoutSec": 30,
    "denyLoginOnReqFailure": true
  }
]