Skip to content

Contacts API

Jump to bottom
Alexander Lobanov edited this page Feb 14, 2023 · 11 revisions

Contact API uses json-rpc protocol.

Description of common action parameters

Required for all methods

  • token (string) - user token

Required for specific methods

  • appid (int) - the application id, you can see this parameter in GaijinCentral in Application tab see External IDs value.

Client methods

Login

For work with contact, the user must log in to the contact server. Without this, the contacts API may not work properly.

{
  "method": "cln_cs_login",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "appid": 1197,
    "token": "user token"
  }
}
Response NOTE: The following fields are present in response, but not supported: - chardToken 
{
  "chardToken": 212969517706894,
  "user_id": 16929100,
  "nick": "test156",
  "login": {
    "first": 1670923278,
    "last": 1670926150
  },
  "externalid": []
}

Get contact list

Action return the contact list for the user. Specific action parameters:

  • groups (int) - works like filter, response contains only groups that are contained in the groups parameter. If the groups parameter is not defined, the response contains all groups allowed for the game.
  • statuses (int) - works like filter, response contains only statuses that are contained in the statuses parameter. If the statuses parameter is not defined, the response contains all types. See contact status description 
{
  "method": "GetContacts",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "appid": 1197,
    "groups": ["Dungeon"],
    "statuses": ["requestsToMe"],
    "token": "user token"
  }
}
Response 
{
  "jsonrpc": "2.0",
  "id": "912eb0e0-853e-47d6-a519-49dcb4b7e604",
  "result": {
    "Dungeon": {  //group
      "requestsToMe": [  //status
        {
          "uid": 11111111,
          "nick": "user1",
          "time": {
            "$date": 1671443640722
          }
        }
      ],
      "approved": [  //status
        {
          "uid": 33333333,
          "nick": "user3",
          "time": {
            "$date": 1671443640315
          }
        },
        {
          "uid": 44444444,
          "nick": "user4",
          "time": {
            "$date": 1671443640112
          }      
        }
      ]
    }
  }
}

Client methods to change the status of contact

Action parameters required for all methods in this section:

  • uid (int) - the unique identifier of another user
  • group (string) - the name of the group, now allowed only one group equal to the name of the game

All actions in this part return "OK" or error

"OK" Response 
{
  "id": "request id",
  "jsonrpc": "2.0",
  "result": "OK"
}
Example of response with error 
{
  "error": {
    "code": -32603,
    "message": "BLACKLISTED"
  },
  "id": "request id",
  "jsonrpc": "2.0"
}

In the examples below all actions are sent by two users:

  • user1 with uid: 11111111 sent friendship request.
  • user2 with uid: 22222222 who approves or rejects friendship request.

Friend request

User id for the friend request specified in the uid parameter.
user1 send friendship request:

{
  "method": "FriendshipRequest",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "appid": 1197,
    "token": "user1 token",
    "uid": 22222222,
    "group": "Dungeon" 
  }
}

Cancel friendsip request

Cancel a friendsip request to the user specified in the uid parameter. user1 cancel friendship request:

{
  "method": "CancelFriendshipRequest",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "appid": 1197,
    "token": "user1 token",
    "uid": 22222222,
    "group": "Dungeon"
  }
}

Approve friend request

Approve a friend request from the user specified in the uid parameter user2 approve friendship request from user1:

{
  "method": "ApproveFriendship",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "appid": 1197,
    "token": "user2 token",
    "uid": 11111111,
    "group": "Dungeon"
  }
}

Reject friendship request

Reject a friendship request from the user specified in the uid parameter.
user2 reject friendship request from user1:

{
  "method": "RejectFriendship",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "appid": 1197,
    "token": "user2 token",
    "uid": 11111111,
    "group": "Dungeon"
  }
}

Delete user from friend list

Delete the user, specified in the uid parameter, from friends list user1 delete user2 from friend list:

{
  "method": "DeleteFriend",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "appid": 1197,
    "token": "user1 token",
    "uid": 22222222,
    "group": "Dungeon",
  }
}

Add to blacklist

Added the user, specified in the uid parameter, to the blacklist user1 add user2 to the blacklist:

{
  "method": "AddToBlackList",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "appid": 1197,
    "token": "user1 token", 
    "uid": 22222222,
    "group": "Dungeon"
  }
}

Remove from blacklist

Remove the user, specified in the uid parameter, from blacklist user1 remove user2 from blacklist:

{
  "method": "RemoveFromBlackList",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "appid": 1197,
    "token": "user1 token",
    "requestorUid": 22222222,
    "groupName": "Dungeon"
  }
}

Contact status

Possible contact type values:

  • #requestsToMe - the status of the user who received the friend request
  • #myRequests - the status of the user who send the friend request
  • #approved - status means users are friends
  • #rejectedByMe - the status of the user who rejected the friend request
  • #myRejectedRequests - the status of the user whose friend request was rejected
  • #meInBlacklist - the status of the user whose friend request was added to the blacklist
  • #myBlacklist - the status of the user who added to the blacklist

Status change scheme

User 1 sends a friend request. User 2 approves friendship

                                                                     user 1                                       user2                   
status - -
user 1 -> Friend request response: OK
status #myRequests #requestsToMe
user 2 -> Approve request response: OK
status #approved #approved

User 1 sends a friend request. User 2 rejects it

                                                                     user 1                                       user2                   
status - -
user 1 -> Friend request response: OK
status #myRequests #requestsToMe
user 2 -> Reject request response: OK
status #myRejectedRequests #rejectedByMe

User 1 resubmits friend request after being rejected

                                                                     user 1                                       user2                   
status #myRejectedRequests #rejectedByMe
user 1 -> Friend request response: OK
status #myRequests #requestsToMe

User 2 approves friendship after rejection

                                                                     user 1                                       user2                   
status #myRejectedRequests #rejectedByMe
user 2 -> Approve request response: OK
status #myRequests #requestsToMe

User 1 sends a friend request and than cancels it

                                                                     user 1                                       user2                   
status - -
user 1 -> Friend request response: OK
status #myRequests #requestsToMe
user 1 -> Cancel request response: OK
status - -

User 1 sends a friend request. User 2 adds it to the blacklist

                                                                     user 1                                       user2                   
status - -
user 1 -> Friend request response: OK
status #myRequests #requestsToMe
user 2 -> Add to blacklist response: OK
status #meInBlacklist #myBlacklist

User 1 resubmits friend request after being added to the blacklist

                                                                     user 1                                       user2                   
status #meInBlacklist #myBlacklist
user 1 -> Friend request error: BLACKLISTED
status #meInBlacklist #myBlacklist

User 2 removes user 1 from blacklist

                                                                     user 1                                       user2                   
status #meInBlacklist #myBlacklist
user 2 -> Remove from blacklist response: OK
status - -

Home

Gaijin Application Platform
Dev Portal

Clone this wiki locally