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 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
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 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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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
},
]
}
}