User

This guide explains how to use the APIs for viewing user joined channels, viewing user block lists, blocking users, and unblocking users.

Get user joined channels API¶

Retrieves the list of channels the user is participating in, excluding 1:1 channels (ONE_ON_ONE).

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/channels`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/channels`
HTTP METHOD	`GET`

Path parameters¶

Field	Description	Type	Required
gameIndex	Hive game index	integer	Y
playerId	Player ID	long	Y

Header parameters¶

Field	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y

Response body¶

Field	Description	Type
code	Response code	integer
message	Result message	string
data	Response data	object

Response body > data¶

Field	Description	Type
gameIndex	Hive game index	integer
playerId	Player ID	long
channels	Channel list	object array

Response body > data > channels¶

Field	Description	Type
channelId	Channel ID	string
type	Channel type (`PRIVATE`, `PUBLIC`, `GROUP`)	string
gameIndex	Hive game index	integer
owner	Channel owner	string
channelName	Channel name	string
memberCount	Current number of channel members	integer
maxMemberCount	Maximum number of channel members	integer
chatHistoryAllowed	Whether message history can be viewed	boolean
regTime	Channel creation time (`UTC+0`, `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format)	string
regTimeMillis	Channel creation time (UnixTimestamp Millisecond)	long

Request sample¶

curl --request GET 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/channels' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

Response sample¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "gameIndex": 1,
    "playerId": 1001,
    "channels": [
      {
        "channelId": "guild:12345",
        "type": "GROUP",
        "gameIndex": 1,
        "owner": "1000",
        "channelName": "Guild chat room",
        "memberCount": 1,
        "maxMemberCount": 50,
        "chatHistoryAllowed": true,
        "regTime": "2023-12-19T15:01:01.004Z",
        "regTimeMillis": 1731306364351
      },
      {
        "channelId": "open:67890",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "SYSTEM",
        "channelName": "Open chat room",
        "memberCount": 2,
        "maxMemberCount": 100,
        "chatHistoryAllowed": true,
        "regTime": "2023-12-20T10:15:30.123Z",
        "regTimeMillis": 1731302348750
      }
      // ... channels
    ]
  }
}

Block user API¶

Blocks a user to restrict real-time message sending and receiving.

After blocking a user, the behavior of channels and messages changes as follows:

You can still receive 1:1 channel (ONE_ON_ONE) invitations from blocked users.
- This is to avoid notifying the blocked user that they have been blocked.
You will not receive chat messages or event messages about channel entry and exit from blocked users.
You cannot send messages to blocked users.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockPlayerId}`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockPlayerId}`
HTTP METHOD	`POST`

Path parameters¶

Field	Description	Type	Required
gameIndex	Hive game index	string	Y
playerId	Player ID of the user blocking	long	Y
blockPlayerId	Player ID of the user being blocked	long	Y

Header parameters¶

Field	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y

Response body¶

Field	Description	Type
code	Response code	integer
message	Result message	string

Request sample¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/block/1002' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

Response sample¶

{
  "code": 0,
  "message": "Success."
}

Get user block list¶

Retrieves the list of users blocked by a specific user.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/blocks`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/blocks`
HTTP METHOD	`GET`

Path parameters¶

Field	Description	Type	Required
gameIndex	Hive game index	string	Y
playerId	Player ID of the user blocking	long	Y

Header parameters¶

Field	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y

Response body¶

Field	Description	Type
code	Response code	integer
message	Result message	string
data	Response data	object

Response body > data¶

Field	Description	Type
gameIndex	Hive game index	integer
playerId	Player ID of the user blocking	long
blockedUsers	List of blocked user information	object array

Response body > data > blockedUsers¶

Field	Description	Type
blockedPlayerId	Player ID of the blocked user	long
blockedTime	Blocked time (`UTC+0`, `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format)	string
blockedTimeMillis	Blocked time (UnixTimestamp Millisecond)	long

Request sample¶

curl  --request GET 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/blocks' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

Response sample¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "gameIndex": 1,
    "playerId": 1001,
    "blockedUsers": [
      {
        "blockedPlayerId": 1002,
        "blockedTime": "2023-12-20T10:15:30.123Z",
        "blockedTimeMillis": 1739329550811
      },
      {
        "blockedPlayerId": 1003,
        "blockedTime": "2023-12-21T08:45:12.456Z",
        "blockedTimeMillis": 1739329553137
      }
      // ... block list
    ]
  }
}

Unblock user¶

Unblocks a blocked user.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockedPlayerId}`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/users/{playerId}/block/{blockedPlayerId}`
HTTP METHOD	`DELETE`

Path parameters¶

Field	Description	Type	Required
gameIndex	Hive game index	string	Y
playerId	Player ID	long	Y
blockedPlayerId	Player ID of the user to be unblocked	long	Y

Header parameters¶

Field	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y

Response body¶

Field	Description	Type
code	Response code	integer
message	Result message	string

Request sample¶

curl --request DELETE 'https://sandbox-api-chat.withhive.com/api/v1/games/1/users/1001/block/1002' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg'

Response sample¶

{
  "code": 0,
  "message": "Success."
}