Channel

This guide describes how to use APIs for creating and deleting channels, modifying channel information, and retrieving channel lists and participants.

Overview¶

A channel is a conceptual space where chat takes place, and all in-game chats are conducted within channels.

This section describes the channel types and channel behavior supported by the API.

Channel types¶

The channel types that can be created via API are as follows:

Channel type	Capacity	Max joined channels	Leave channel on disconnect	Primary use
`PUBLIC`	1 – 5,000	Up to 10	O	Open chat, events, etc.
`GROUP`	1 – 500	Up to 10	X	Guild, team, party chat
`PRIVATE`	1 – 500	Up to 10	X	Friends, private group chat
`ONE_ON_ONE`	2	Up to 200	X	1:1 chat

PUBLIC channels are created for open chat where unspecified users can participate, and only online users can join.
GROUP and PRIVATE channels are created for chatting within specific groups such as guilds, friends, and parties.
PRIVATE channels are created for chatting among friends or within a private group, and users must enter a password to join.

How channels work¶

The basic behavior of channels is as follows:

There are explicit moments of joining and leaving a channel, and the chat server provides consistent handling at each point.
When a message is sent to a channel, it is delivered to all users in the channel. (However, messages are not delivered to blocked users.)
Only channel participants can send messages to a channel. (However, notice messages are an exception.)

The behavior based on channel API usage is as follows:

Creating and deleting channels¶

You can create a channel using the Create channel or Create 1:1 channel API.
- For 1:1 channels (ONE_ON_ONE), you must use the Create 1:1 channel API.
Cases where a channel is deleted:
- When the Delete channel API is used
- When the channel owner is not SYSTEM and the channel has no participants, it is periodically deleted.
If a channel is deleted while there are still participants, a channel deletion event is sent to the participants.

Modifying channel information¶

You can modify channel information using the Update channel API.
- Modifiable fields: channel name, maximum member count, password, and chat history availability
- Even if the maximum member count is changed to 50 while the channel already has 100 participants, the status of existing participants is not affected.
- 1:1 channel (ONE_ON_ONE) information cannot be modified.

Create channel API¶

Creates a new channel.

If playerId is included in the request body parameters, the user with that playerId becomes the channel owner and automatically joins the channel. If playerId is not included, the channel owner is set to SYSTEM.

The following channels are periodically deleted:

Channels where the owner is not SYSTEM and there are no participants

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	Description	Type	Required
gameIndex	Hive game index	integer	Y

Header parameters¶

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

Request body¶

Field	Description	Type	Required
channelId	Channel ID (Uppercase/lowercase letters, numbers, and some special characters (`-`, `.`, `_`, `~`, `:`) allowed, max 100 characters)	string	Y
playerId	Player ID of the channel creator	long	N
password	Password (required for `PRIVATE` channels) (Max 50 characters)	string	N
channelName	Channel name (Max 50 characters)	string	Y
maxMemberCount	Maximum number of channel participants (Min 2 – Max 5,000)	integer	Y
type	Channel type (`PRIVATE`, `PUBLIC`, `GROUP`)	string	Y
chatHistoryAllowed	Whether message history is available (Default: `false`)	boolean	N

Response body¶

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

Response body > data¶

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

Request sample¶

curl --request POST 'https://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",
    "channelName": "Open Chat Room",
    "maxMemberCount": 100,
    "type": "PUBLIC",
    "chatHistoryAllowed": true
}'

Response sample¶

{
    "code": 0,
    "message": "Success.",
    "data": {
        "channelId": "open:12345",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "SYSTEM",
        "channelName": "Open Chat Room",
        "chatHistoryAllowed": true,
        "maxMemberCount": 100,
        "regTime": "2025-07-21T08:39:07.542913300Z",
        "regTimeMillis": 1753087147542
  }
}

Create 1:1 channel API¶

Creates a 1:1 channel (ONE_ON_ONE) and joins the users corresponding to playerId and otherPlayerId in the request data.

If a previously created 1:1 channel already exists with the same users, the existing channel is joined instead.

Request URL¶

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

Path parameters¶

Field	Description	Type	Required
gameIndex	Hive game index	integer	Y

Header parameters¶

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

Request body¶

Field	Description	Type	Required
channelId	Channel ID (Uppercase/lowercase letters, numbers, and some special characters (`-`, `.`, `_`, `~`, `:`) allowed, max 100 characters)	string	Y
channelName	Channel name (max 50 characters)	string	Y
playerId	Player ID	long	Y
otherPlayerId	Other player's Player ID	long	Y
chatHistoryAllowed	Whether message history is available (Default: `false`)	boolean	N

Response body¶

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

Response body > data¶

Field	Description	Type
channelId	Channel ID	string
type	Channel type (`ONE_ON_ONE`)	string
gameIndex	Hive game index	integer
owner	Channel owner	string
channelName	Channel name	string
maxMemberCount	Maximum number of channel participants	integer
participants	List of participant playerIds	array
chatHistoryAllowed	Whether message history is available	boolean
regTime	Channel creation datetime (based on `UTC+0`, format: `yyyy-MM-dd'T'HH:mm:ss.SSSZ`)	string
regTimeMillis	Channel creation datetime (UnixTimestamp Millisecond)	long

Request sample¶

curl --request POST 'https://api-chat.withhive.com/api/v1/games/1/channel/1on1' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data'{
    "channelId": "1on1:test",
    "channelName": "Test 1:1 Channel",
    "playerId": 1000,
    "otherPlayerId": 2000,
    "chatHistoryAllowed": false
}'

Response sample¶

{
    "code": 0,
    "message": "Success.",
    "data": {
        "channelId": "1on1:test",
        "type": "ONE_ON_ONE",
        "gameIndex": 1,
        "owner": "1000",
        "channelName": "Test 1:1 Channel",
        "chatHistoryAllowed": false,
        "maxMemberCount": 2,
        "participants": [1000, 2000],
        "regTime": "2025-07-18T09:37:36.697035738Z",
        "regTimeMillis": 1752831456697
    }
}

Update channel API¶

Updates a created channel.

Only the following channel types can be updated:

PUBLIC
PRIVATE
GROUP

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	`PATCH`
CONTENT-TYPE	`application/json`

Path parameters¶

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

Header parameters¶

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

Request body¶

Field	Description	Type	Required
channelName	Channel name (Max 50 characters)	string	N
password	Password (required for `PRIVATE` channels) (Max 50 characters)	string	N
maxMemberCount	Maximum number of channel participants	integer	N
type	Channel type (`PRIVATE`, `PUBLIC`, `GROUP`)	string	N
chatHistoryAllowed	Whether message history is available (Default: `false`)	boolean	N

Response body¶

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

Request sample¶

curl --request PATCH 'https://api-chat.withhive.com/api/v1/games/1/channels/testchannel' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs' \
--header 'Content-Type: application/json' \
--data'{
    "channelName": "Open Chat Room",
    "maxMemberCount": 100,
    "type": "PUBLIC",
    "chatHistoryAllowed": true
}'

Response sample¶

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

Delete channel API¶

Deletes a created channel and sends a channel deletion event to the users in that 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	Description	Type	Required
gameIndex	Hive game index	integer	Y
channelId	Channel ID to delete	string	Y

Header parameters¶

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

Response body¶

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

Get channel list API¶

Retrieves the list of created channels. The channel types available for retrieval are as follows:

PUBLIC
PRIVATE
GROUP

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	Description	Type	Required
gameIndex	Hive game index	integer	Y

Header parameters¶

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

Query parameters¶

Field	Description	Type	Required
type	Channel type (`PRIVATE`, `PUBLIC`, `GROUP`)	string	N
channelId	Retrieve channels starting with the specified channel ID	string	N
channelName	Retrieve channels containing the specified 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 per page (Min 1 – Max 10, Default: `10`)	integer	N
page	Page number to retrieve (Starts from 1, Default: `1`)	integer	N

Response body¶

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

Response body > data¶

Field	Description	Type
content	Channel list	object array
page	Page info	object

Response body > data > content¶

Field	Description	Type
channelId	Channel ID	string
type	Channel type (`PRIVATE`, `PUBLIC`, `GROUP`)	string
gameIndex	Hive game index	integer
owner	Player ID of the 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 is available	boolean
regTime	Channel creation datetime (based on `UTC+0`, format: `yyyy-MM-dd'T'HH:mm:ss.SSSZ`)	string
regTimeMillis	Channel creation datetime (UnixTimestamp Millisecond)	long

Response body > data > page¶

Field	Description	Type
size	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": "Open Chat Room",
        "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
    }
  }
}

Get channel API¶

Retrieves detailed information of a created 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	`GET`

Path parameters¶

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

Header parameters¶

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

Response body¶

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

Response body > data¶

Field	Description	Type
info	Channel info	object
members	Member list	object array

Response body > data > info¶

Field	Description	Type
channelId	Channel ID	string
type	Channel type (`PRIVATE`, `PUBLIC`, `GROUP`, `ONE_ON_ONE`)	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 is available	boolean
regTime	Channel creation datetime (based on `UTC+0`, format: `yyyy-MM-dd'T'HH:mm:ss.SSSZ`)	string
regTimeMillis	Channel creation datetime (UnixTimestamp Millisecond)	long

Response body > data > members¶

Field	Description	Type
playerId	Player ID	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": "Open Chat Room",
      "memberCount": 2,
      "maxMemberCount": 50,
      "chatHistoryAllowed": true,
      "regTime": "2024-12-30T15:01:01.004Z",
      "regTimeMillis": 1731306364351
    },
    "members": [
      {
        "playerId": 1
      },
      {
        "playerId": 2
      }
    ]
  }
}

Get channel members API¶

Retrieves information about users who have joined a channel.

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	Description	Type	Required
gameIndex	Hive game index	integer	Y
channelId	Channel ID to retrieve	string	Y

Header parameters¶

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

Response body¶

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

Response body > data¶

Field	Description	Type
members	Channel member list	object array

Response body > data > members¶

Field	Description	Type
playerId	Player ID	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
      },
      {
        "playerId": 2
      }
    ]
  }
}

Enter channel API¶

Allows a specific user to join a channel.

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	Description	Type	Required
gameIndex	Hive game index	integer	Y
channelId	Channel ID	string	Y

Header parameters¶

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

Request body¶

Field	Description	Type	Required
playerId	Player ID of the user to enter	long	Y
password	Password (required for `PRIVATE` channels)	string	N

Response body¶

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

Exit channel API¶

Removes a user from a channel.

Even if the channel owner leaves, the channel is maintained. However, channels where the owner is not SYSTEM and there are no participants are 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	Description	Type	Required
gameIndex	Hive game index	integer	Y
channelId	Channel ID	string	Y

Header parameters¶

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

Request body¶

Field	Description	Type	Required
playerId	Player ID of the user to exit	long	Y

Response body¶

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