Skip to content

Contacts API

Jump to bottom
Alexander Lobanov edited this page Dec 19, 2022 · 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 parametr in GaijinCentral in Application tab see External IDs value.
  • apprUid (int) - the unique identifier of the user for sending a friendship request
  • requestorUid (int) - the unique identifier of the user who sent the friendship request
  • groupName (string) - the name of the game
  • comment (string) - just a comment for some action

Client methods

Login

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

{
  "method": "cln_cs_login",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "appid": 1222,
    "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. Contact list is the map with key like #TycoonCity#requestsToMe

  • #TycoonCity - the first part of the key is the game name
  • #requestsToMe - the second part of the key is the contact status 
{
  "method": "cln_get_contact_lists_ext",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "token": "user token"
  }
}
Response 
{
  "jsonrpc": "2.0",
  "id": "912eb0e0-853e-47d6-a519-49dcb4b7e604",
  "result": {
    "#TycoonCity#requestsToMe": [
      {
        "uid": 118904222,
        "nick": "test260",
        "time": {
       "$date": 1671443640722
      }
    ],
    "#TycoonCity#approved": [
      {
        "uid": 16929170,
        "nick": "test217",
        "time": {
       "$date": 1671443640315
      },
      {
        "uid": 16929150,
        "nick": "test199",
        "time": {
       "$date": 1671443640112
      }
    ]
  }
}

Client methods to change the status of contact

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"
}

Friend request

User id for the friend request specified in the apprUser parameter

{
  "method": "cln_request_for_contact",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "token": "user token",
    "apprUid": 16929100,
    "comment": "frendship test request",
    "groupName": "TycoonCity" 
  }
}

Cancel friend request

Cancel a friend request to the user specified in the apprUser parameter

{
  "method": "cln_cancel_request_for_contact",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "token": "user token",
    "apprUid": 16929100,
    "groupName": "TycoonCity"
  }
}

Approve friend request

Approve a friend request from the user specified in the requestorUid parameter

{
  "method": "cln_approve_request_for_contact",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "token": "user token",
    "requestorUid": 16929110,
    "groupName": "TycoonCity"
  }
}

Reject friend request

Reject a friend request from the user specified in the requestorUid parameter

{
  "method": "cln_reject_request_for_contact",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "token": "user token",
    "requestorUid": 16929110,
    "groupName": "TycoonCity",
    "comment": "reject friendship test request"
  }
}

Delete user from friend list

Delete the user, specified in the requestorUid parameter, from friends list

{
  "method": "cln_break_approval_contact",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "token": "user token",
    "requestorUid": 16929110,
    "groupName": "TycoonCity",
    "comment": "break_test"
  }
}

Add to blacklist

Added the user, specified in the requestorUid parameter, to the blacklist

{
  "method": "cln_blacklist_request_for_contact",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "token": "user token", 
    "requestorUid": 16929110,
    "groupName": "TycoonCity",
    "comment": "black_test"
  }
}

Remove from blacklist

Remove the user, specified in the requestorUid parameter, from blacklist

{
  "method": "cln_remove_from_blacklist_for_contact",
  "id": "request id",
  "jsonrpc": "2.0",
  "params": {
    "token": "user token",
    "requestorUid": 16929110,
    "groupName": "TycoonCity",
    "comment": "test"
  }
}

Contact status

Possible contact status 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