HTTP API

Overview¶

We provide a chat service via HTTP. It is mainly composed of Channel API, User API, and Message API.

Channel API
- Get all channel list API
- Channel retrieval API
- Channel participant retrieval API
- Channel creation API
- Channel deletion API
- Channel entry API
- Channel exit API
User API
- User token issuance API
- User participating channel retrieval API
- User block list retrieval API
- User block API
- User unblock API
Message API
- Channel announcement message sending API
- User announcement message sending API
- Channel custom message sending API
- User custom message sending API
- Channel message retrieval API

Basic information¶

When using the HTTP API, we provide basic information that you need to know in common.

Preparation of the dictionary¶

To use the HTTP API, you need to prepare the following items.

Hive Certification Key: Authentication token for API calls
- Can be checked in Hive Console > App Center > Project Management > Game Details > Basic Information
Game Index: The index of the game created in Hive Console > App Center > Project Management

Channel type¶

The channel types used when sending HTTP API are as follows.

Type	Description
`PUBLIC`	A channel that anyone can enter
`PRIVATE`	A channel that can be entered by entering a password
`GROUP`	A channel that only specific users can participate in (e.g., guild channel)

Request URL¶

Server	URL
LIVE	`api-chat.withhive.com`
SANDBOX	`sandbox-api-chat.withhive.com`

Common header¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y
Content-Type	Type of request data (`application/json`)	string	Y

Response code¶

API response code

HTTP Status Code	Code	Message	Description
200	0	Success.	Success
400	100	Bad request.	Bad request
401	101	Invalid token.	Invalid token
403	102	Forbidden.	Forbidden
404	103	Not found.	Not found
405	104	Method not allowed.	Method not allowed
500	105	Internal server error.	Internal server error

Detailed error codes (400, 403)

HTTP Status Code	Code	Message	Description
400	200	Duplicate channel ID.	Duplicate channel ID
	201	Channel not found or deleted.	Channel not found or deleted
	202	Channel is full.	Channel is full
	203	Invalid channel password.	Invalid channel password
	204	Message size exceeded. The maximum size is 200.	Message size exceeded (maximum 200 characters)
	300	User not in session.	User not in session (not connected to the Socket server)
	301	User not in the channel.	User not in the channel
	302	User is already in the channel.	User is already in the channel
	303	User already blocked.	User already blocked
	304	Block list is full. The maximum size is 100.	Block list is full (maximum 100 users)
	305	User not in block list.	User not in block list
	306	User is blocked.	User is blocked
	307	The maximum number of channels a user can enter is 10.	User has exceeded the maximum number of channels allowed (10 limit)
	400	Custom message size exceeded. The maximum size is 8,000 bytes.	Custom message size exceeded (maximum 8,000 bytes)
403	308	User is not the owner of the channel.	User is not the owner of the channel

Channel API features¶

This explains the API requests and responses for each function of the channel API used in the chat service, along with example code.

Retrieve full channel list¶

Retrieving the list of currently created channels.

Request URL¶

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

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive Game Index	integer	Y

Header parameters¶

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

Query parameters¶

Field Name	Description	Type	Required
type	Channel type (`PRIVATE`, `PUBLIC`, `GROUP`)	string	N
channelId	Channel ID for querying channels	string	N
channelName	Querying channels that include the channel name	string	N
sort	Sort criteria (`channelId`, `channelName`, `regTime`) (default `regTime`)	string	N
order	Sort order (`ASC`, `DESC`) (default `DESC`)	string	N
size	Number of channels to query per page (minimum 1 ~ maximum 10, default 10)	integer	N
page	Page number to query (starting from 1, default 1)	integer	N

Response body¶

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

Response body > data¶

Field Name	Description	Type
content	Channel List	object array
page	Page Info	object

Response body > data > content¶

Field Name	Description	Type
channelId	Channel ID	string
type	Channel type (`PRIVATE`, `PUBLIC`, `GROUP`)	string
gameIndex	Hive game index	integer
owner	Hive player ID of the channel owner	string
channelName	Channel name	string
memberCount	Current number of participants in the channel	integer
maxMemberCount	Maximum number of participants in the channel	integer
chatHistoryAllowed	Whether message history retrieval is allowed	boolean
regTime	Channel creation date and time (based on `UTC+0`, format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`)	string
regTimeMillis	Channel creation date and time (UnixTimestamp Millisecond)	long

Response body > data > page¶

Field Name	Description	Type
size	Number of items per page	integer
currentPage	Current page number	integer
totalElements	Total number of items	integer
totalPages	Total number of pages	integer

Request sample¶

curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels?type=PUBLIC&sort=regTime&order=DESC&size=10&page=1' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "content": [
      {
        "channelId": "open:12345",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "1000",
        "channelName": "오픈 채팅방",
        "memberCount": 2,
        "maxMemberCount": 50,
        "chatHistoryAllowed": true,
        "regTime": "2024-12-30T15:01:01.004Z",
        "regTimeMillis": 1731306364351
      },
      /// ... channel info
    ],
    "page": {
      "size": 10,
      "currentPage": 1,
      "totalElements": 100,
      "totalPages": 10
    }
  }
}

Channel lookup¶

Retrieving channel details.

Request URL¶

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

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive Game Index	integer	Y
channelId	Channel ID to query	string	Y

Header parameters¶

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

Response body¶

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

Response body > data¶

Field Name	Description	Type
info	Channel Info	object
members	Participant List	object array

Response body > data > info¶

Field Name	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 participants in the channel	integer
maxMemberCount	Maximum number of participants in the channel	integer
chatHistoryAllowed	Whether message history retrieval is allowed	boolean
regTime	Channel creation date and time (based on `UTC+0`, format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`)	string
regTimeMillis	Channel creation date and time (UnixTimestamp Millisecond)	long

Response body > data > members¶

Field Name	Description	Type
playerId	Hive Player ID	long
connectedTime	Connection time (based on `UTC+0`, format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`)	string
connectedTimeMillis	Connection time (Unix Timestamp Millisecond)	long

Request sample¶

curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "info": {
      "channelId": "open:12345",
      "type": "PUBLIC",
      "gameIndex": 1,
      "owner": "SYSTEM",
      "channelName": "오픈채팅방",
      "memberCount": 2,
      "maxMemberCount": 50,
      "chatHistoryAllowed": true,
      "regTime": "2024-12-30T15:01:01.004Z",
      "regTimeMillis": 1731306364351
    },
    "members": [
      {
        "playerId": 1,
        "connectedTime": "2024-11-25T06:22:06.604Z",
        "connectedTimeMillis": 1739328218507
      },
      {
        "playerId": 2,
        "connectedTime": "2024-11-25T06:22:16.233Z",
        "connectedTimeMillis": 1731306364351
      }
    ]
  }
}

Channel participants query¶

Retrieving channel participant information.

Request URL¶

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

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive game index	integer	Y
channelId	Channel ID to query	string	Y

Header parameters¶

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

Response body¶

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

Response body > data¶

Field Name	Description	Type
members	List of channel participants	object array

Response body > data > members¶

Field Name	Description	Type
playerId	Hive Player ID	long
connectedTime	Connection time (based on `UTC+0`, format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`)	string
connectedTimeMillis	Connection time (Unix Timestamp Millisecond)	long

Request sample¶

curl --request GET 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345/members' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "members": [
      {
        "playerId": 1,
        "connectedTime": "2024-11-25T06:22:06.604Z",
        "connectedTimeMillis": 1739328218507
      },
      {
        "playerId": 2,
        "connectedTime": "2024-11-25T06:22:16.233Z",
        "connectedTimeMillis": 1731306364351
      }
    ]
  }
}

Create channel¶

Creating a new channel.

When you enter playerId in the request body, the user corresponding to playerId becomes the owner of the channel being created. This user will enter the channel they created. Conversely, if playerId is not entered in the request body, the SYSTEM that is created becomes the owner of the channel.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channel`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channel`
HTTP METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive Game Index	integer	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y
Content-Type	The type of request data (`application/json`)	string	Y

Request body¶

This is the transmission data required when requesting to create a channel.

Field Name	Description	Type	Required
channelId	Channel ID (English letters, numbers, and some special characters (`-`, `.`, `_`, `~`, `:`) allowed, maximum 100 characters)	string	Y
playerId	Player ID of the channel creator's Hive	long	N
password	Password (required if the channel is `PRIVATE`) (maximum 50 characters)	string	N
channelName	Channel name (maximum 50 characters)	string	Y
maxMemberCount	Maximum number of participants in the channel (minimum 2 to maximum 5,000)	integer	Y
type	Channel type (`PRIVATE`, `PUBLIC`, `GROUP`)	string	Y
chatHistoryAllowed	Whether message history can be viewed (default is false)	boolean	N

Response body¶

Field Name	Description	Type
code	Response result code	integer
message	Result message	string

Request sample¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/channel' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data'{
    "channelId": "open:12345",
    "playerId": 1000,
    "channelName": "오픈 채팅방",
    "maxMemberCount": 100,
    "type": "PUBLIC",
    "chatHistoryAllowed": true
}'

Response sample¶

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

Delete channel¶

Deleting the channel.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}`
HTTP Method	`DELETE`

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive game index	integer	Y
channelId	Channel ID to delete	string	Y

Header parameters¶

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

Response body¶

Field Name	Description	Type
code	Response result code	integer
message	Result message	string

Request sample¶

curl --request DELETE 'https://api-chat.withhive.com/api/v1/games/1/channels/open:12345' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

Response sample¶

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

Enter channel¶

Entering users into the channel.

The maximum number of channels that can be entered is 10 per user.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/enter`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/enter`
HTTP METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive Game Index	integer	Y
channelId	Channel ID	string	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y
Content-Type	The type of the request data (`application/json`)	string	Y

Request body¶

This is the data required when requesting to enter the channel.

Field Name	Description	Type	Required
playerId	Player ID of the user to be admitted Hive	long	Y
password	Password (required for `PRIVATE` channel)	string	N

Response body¶

Field Name	Description	Type
code	Response result code	integer
message	Result message	string

Request sample¶

curl --request POST 'https://api-chat.withhive.com/api/v1/games/1/channels/guild:12345/enter' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data '{
    "playerId": 1001,
    "password": "guildPass123"
}'

Response sample¶

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

Channel exit¶

Removing users who joined the channel. The channel will remain even if the channel owner leaves. Channels without participants where the channel owner is not SYSTEM will be periodically deleted.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/exit`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/channels/{channelId}/exit`
HTTP METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive Game Index	integer	Y
channelId	Channel ID	string	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y
Content-Type	Type of request data (`application/json`)	string	Y

Request body¶

This is the transmission data required when requesting to exit the channel.

Field Name	Description	Type	Required
playerId	Player ID of the user to be removed Hive	long	Y

Response body¶

Field Name	Description	Type
code	Response result code	integer
message	Result message	string

Request sample¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/channels/guild:12345/exit' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data '{
    "playerId": 1001
}'

Response sample¶

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

User API features¶

This explains the API requests and responses for user APIs used in the chat service, along with example code.

User token issuance¶

Issuing an authentication token for connecting to the socket server.

Connect to the Socket server address returned through the issued token.

Request URL¶

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

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive Game Index	integer	Y
playerId	Hive Player ID	long	Y

Header parameters¶

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

Response body¶

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

Response body > data¶

Field Name	Description	Type
gameIndex	Hive game index	integer
socketAddress	Socket server address	string
token	Issued token	string

Request sample¶

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

Response sample¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "gameIndex": 1,
    "socketAddress": "wss://test-socket-chat.withhive.com/ws",
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg"
  }
}

User participation channel inquiry¶

Retrieves the list of channels the user is participating in.

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 Name	Description	Type	Required
gameIndex	Hive Game Index	integer	Y
playerId	Hive Player ID	long	Y

Header parameters¶

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

Response body¶

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

Response body > data¶

Field Name	Description	Type
gameIndex	Hive Game Index	integer
playerId	Hive Player ID	long
channels	List of Channels	object array

Response body > data > channels¶

Field Name	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 participants	integer
maxMemberCount	Maximum number of channel participants	integer
chatHistoryAllowed	Whether message history retrieval is allowed	boolean
regTime	Channel creation date and time (based on `UTC+0`, format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`)	string
regTimeMillis	Channel creation date and 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": "길드 채팅방",
        "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": "오픈 채팅방",
        "memberCount": 2,
        "maxMemberCount": 100,
        "chatHistoryAllowed": true,
        "regTime": "2023-12-20T10:15:30.123Z",
        "regTimeMillis": 1731302348750
      }
      // ... 채널
    ]
  }
}

User block list retrieval¶

Retrieving the list of users blocked by the 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 Name	Description	Type	Required
gameIndex	Hive Game Index	string	Y
playerId	Hive Player ID	long	Y

Header parameters¶

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

Response body¶

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

Response body > data¶

Field Name	Description	Type
gameIndex	Hive Game Index	integer
playerId	Hive Player ID	long
blockedUsers	Blocked List	object array

Response body > data > blockedusers¶

Field Name	Description	Type
blockedPlayerId	Player ID of the blocked user Hive	long
blockedTime	Time of blocking (based on `UTC+0`, format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`)	string
blockedTimeMillis	Time of blocking (Unix Timestamp 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
      },
      // ... 차단 목록
    ]
  }
}

User block¶

Blocking other users. This is a feature that restricts the sending and receiving of real-time messages.

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 Name	Description	Type	Required
gameIndex	Hive Game Index	string	Y
playerId	Hive Player ID	long	Y
blockPlayerId	Blocked Hive Player ID	long	Y

Header parameters¶

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

Response body¶

Field Name	Description	Type
code	Response result 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."
}

Unblock user¶

Unblocking 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 Name	Description	Type	Required
gameIndex	Hive game index	string	Y
playerId	Hive player ID	long	Y
blockedPlayerId	Hive player ID to unblock	long	Y

Header parameters¶

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

Response body¶

Field Name	Description	Type
code	Response result 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."
}

Message API features¶

This is an API for sending notification messages or custom messages, or for retrieving message history from a specific channel.

Channel notice message sending¶

Sends announcement messages to a specific channel or all channels.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/notice`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/notice`
HTTP METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive Game Index	integer	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y
Content-Type	Type of request data (`application/json`)	string	Y

Request body¶

This is the transmission data required when requesting to send a notification message.

Field Name	Description	Type	Required
channelId	The channel ID to send the message (if not provided, send to all channels)	string	N
langCode	The Hive language code of the user to send the message (if not provided, send regardless of language) (Based on ISO 639 alpha-2, languages not distinguished by ISO 639 alpha-2 should be separated with a Script tag)	string	N
message	The content of the announcement message to be sent (up to 200 characters)	string	Y

Channelid¶

If there is no channelId, the Path parameter gameIndex will send messages to all channels that exist in the app.

Langcode¶

If langCode is not present, the message will be delivered to all users regardless of language.

If there is a langCode, the user who receives the message will vary depending on the field value. For example, if the langCode is en, the notification message will be sent only to users whose Request body langCode is en when connecting the client.

Response body¶

Field Name	Description	Type
code	Response result code	integer
message	Description result message	string

Request sample¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/notice' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "channelId": "open:12345",
    "langCode": "en",
    "message": "서버 점검이 있습니다. 잠시 후 다시 접속해 주세요."
}'

Response sample¶

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

User notice message sending¶

Sending a notification message to the user.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/notice/users/{playerId}`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/notice/users/{playerId}`
HTTP METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

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

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y
Content-Type	Type of the request data (`application/json`)	string	Y

Request body¶

This is the transmission data required when requesting to send a notification message.

Field Name	Description	Type	Required
langCode	The Hive language code of the user to whom the message will be sent (sent regardless of language if not provided) (Based on ISO 639 alpha-2, languages not distinguished by ISO 639 alpha-2 should be separated with a Script tag)	string	N
message	The content of the notification message to be sent (up to 200 characters)	string	Y

Langcode¶

If there is no langCode, it delivers messages to the playerId user regardless of the language.

If there is a langCode, a user notification message will only be sent when the langCode in the API Request body matches the langCode in the Request body when the client connects. For example, if a user with playerId=1111 connects to the chat client with langCode=en, and the user notification message sending API is called with playerId=1111, langCode=ja, a notification message will not be sent to this user.

Response body¶

Field Name	Description	Type
code	Response result code	integer
message	Description result message	string

Request sample¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/notice/users/123123' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "langCode": "en",
    "message": "123123 님에게 보내는 공지 메시지입니다."
}'

Response sample¶

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

Send channel custom message¶

Sends custom messages to all users who joined the channel.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/channels/{channelId}`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/channels/{channelId}`
HTTP METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive game index	integer	Y
channelId	Channel ID to receive messages	string	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y
Content-Type	Type of the request data (`application/json`)	string	Y

Request body¶

This is the transmission data required when requesting to send a custom message.

Field Name	Description	Type	Required
message	The content of the custom message to be sent (`UTF-8` based) (up to 8,000 Bytes)	string	Y

Response body¶

Field Name	Description	Type
code	Response result code	integer
message	Description result message	string

Request sample¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/custom-message/channels/public:123' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "message": "커스텀 메시지입니다."
}'

Response sample¶

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

Send user custom message¶

Sending a custom message to the user.

Request URL¶

Server	URL
LIVE	`https://api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/users`
SANDBOX	`https://sandbox-api-chat.withhive.com/api/v1/games/{gameIndex}/custom-message/users`
HTTP METHOD	`POST`
CONTENT-TYPE	`application/json`

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive Game Index	integer	Y

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (`Bearer`)	string	Y
Content-Type	The type of request data (`application/json`)	string	Y

Request body¶

This is the transmission data required when requesting to send a custom message.

Field Name	Description	Type	Required
playerIds	A collection of account identifiers to receive messages Hive player ID list (up to 10)	long array	Y
message	The content of the custom message to be sent (`UTF-8` based) (up to 8,000 Bytes)	string	Y

Response body¶

Field Name	Description	Type
code	Response result code	integer
message	Description result message	string

Request sample¶

curl --request POST 'https://sandbox-api-chat.withhive.com/api/v1/games/1/custom-message/users' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxLCJpYXQiOjE3MzI1MTcyMzUsImV4cCI6MTczMjUyMDgzNX0.lm5eFqEuSPjsKZUItpTQvFy_2oWrMMJ_J0MPH9VFtNg' \
--header 'Content-Type: application/json' \
--data '{
    "playerIds": [
        123123
    ],
    "message": "커스텀 메시지입니다."
}'

Response sample¶

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

Channel message history retrieval¶

Retrieving channel message history. Channel message history is provided with cursor-based pagination, and only channel message history from the last 30 days can be retrieved. This API can only be used if the option to view previous conversation history is enabled in channel settings. The channel message history received in the API response may include past messages from blocked users.

Pagination: size and index¶

Provides pagination using the query parameter index. There is no default value for index, and if the request is made without index, it will return the chat messages starting from the most recent up to the specified size.

For example, if you call the API with size=5 without index, it will return the 5 most recent chat histories and a nextIndex (for example, a value like 68009c30780e4f2d9830d8a0) that allows you to receive the next history.

After re-calling the API with index=68009c30780e4f2d9830d8a0 and size=5, it will return the 5 chat records that occurred after the last chat history returned earlier.

Pagination: hasnext¶

If the response value hasNext is true, it means there are more past chat histories. In other words, you can use the response value nextIndex as index to retrieve more previous channel message histories.

Request URL¶

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

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Hive Game Index	integer	Y
channelId	Channel ID to query	integer	Y

Header parameters¶

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

Query parameters¶

This is the query string data required when requesting channel message retrieval.

Field Name	Description	Type	Required
size	Channel history size (Minimum 1 ~ Maximum 50)	integer	Y
index	Index to use for retrieval (if not provided, retrieves the most recent message)	string	N

Response body¶

Field Name	Description	Type
code	Response result code	integer
message	Description result message	string
data	Response data	object

Response body > data¶

Field Name	Description	Type
hasNext	Whether additional retrieval is possible	boolean
nextIndex	The index to use for the next retrieval	string
content	Channel message history	object array

Response body > data > content¶

Field Name	Description	Type
gameIndex	Hive game index	integer
from	Identifier of the account that received the message Hive player ID	long
extraData	User additional information (`UTF-8` based) (maximum 256 Byte)	string
to	Channel ID that sent the message	string
message	Message content	string
langCode	Hive language code (based on ISO 639 alpha-2, languages not distinguished by ISO 639 alpha-2 should be separated with a Script tag)	string
timestamp	Date and time when the message was sent (`UTC+0` based, `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format)	string
timestampMillis	Date and time when the message was sent (UnixTimestamp Millisecond)	long

Request sample¶

curl --request GET 'https://test-api-chat.withhive.com/api/v1/games/1/channels/open:1/messages?size=50' \
--header 'Authorization: hivechat 005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76'

Response sample¶

{
  "code": 0,
  "message": "Success.",
  "data": {
    "hasNext": true,
    "nextIndex": "67c7d83336af25202c1c0ad4",
    "content": [
    // as size=50, returns 50 objects each of which is like the followings.
      {
        "gameIndex": 1,
        "from": 1111112,
        "extraData": "김하이브",
        "to": "open:10",
        "message": "zzz",
        "langCode": "ko",
        "timestamp": "2025-03-05T04:50:59.757Z",
        "timestampMillis": 1741150259757
      },
      {
        "gameIndex": 1,
        "from": 1111111,
        "extraData": null,
        "to": "open:10",
        "message": "하이브2",
        "langCode": "ko",
        "timestamp": "2025-03-05T04:51:01.689Z",
        "timestampMillis": 1741150261689
      },
    ]
  }
}