Channel

This guide explains how to use the APIs for creating and deleting channels, updating channel information, and retrieving channel lists and participants.

Overview¶

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

This section describes the channel types and channel operation methods supported by the API.

Channel types¶

The following channel types can be created via API requests.

• PUBLIC channels are suitable for open chat with unspecified participants.
• Only users connected to the socket server can join the channel.
• GROUP and PRIVATE channels are suitable for group chats such as guilds, friends, or parties.
• PRIVATE channels require a password to join.

Channel operation¶

The basic operation of channels is as follows:

• There are clear entry and exit points for channels, 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 (except blocked users).
• Only channel participants can send messages to the channel (notice messages are an exception).

The following describes the behavior when using the channel API.

Channel creation and deletion¶

• You can create a channel using the create channel or create 1:1 channel API.
  • For 1:1 channels (ONE_ON_ONE), use the create 1:1 channel API.
• A channel is deleted in the following cases:
  • When the delete channel API is used
  • When the channel owner is not SYSTEM and there are no participants, the channel is periodically deleted.
• If a channel is deleted while there are participants, a channel deletion event is sent to the participants.

Channel information update¶

• You can update channel information using the update channel API.
  • Updatable items: channel name, maximum number of members, password, chat history availability
  • If you reduce the maximum number of members below the current number of participants, existing participants are not forcibly removed.
  • 1:1 channel (ONE_ON_ONE) information cannot be updated.

Create channel API¶

Creates a new channel.

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

The following types of channels are periodically deleted:

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

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Response body¶

Response body > data¶

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 and joins the users corresponding to playerId and otherPlayerId in the request data to the 1:1 channel (ONE_ON_ONE). If a 1:1 channel (ONE_ON_ONE) already exists, it joins the existing channel.

Each user can have up to 200 1:1 channels (ONE_ON_ONE).

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Response body¶

Response body > data¶

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'{
    "playerId": 1000,
    "otherPlayerId": 2000,
    "chatHistoryAllowed": false
}'

Response sample¶

{
    "code": 0,
    "message": "Success.",
    "data": {
        "channelId": "V0FQBKSa9bWC33v",
        "type": "ONE_ON_ONE",
        "gameIndex": 1,
        "owner": "100",
        "channelName": "100&200",
        "chatHistoryAllowed": true,
        "maxMemberCount": 2,
        "regTime": "2025-07-18T09:37:36.697035738Z",
        "regTimeMillis": 1752831456697
    }
}

Update channel API¶

Updates an existing channel.

Only channels of the following types can be updated:

• PUBLIC
• PRIVATE
• GROUP

When updating the maximum number of participants in a chat channel, even if more users are currently in the channel than the new limit, the existing users are not forcibly removed. Therefore, if you reduce the maximum number of participants to below the current number, there will be a temporary state where the number of participants exceeds the maximum limit.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Response body¶

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 channel and sends a channel deletion event to the users participating in the channel.

Request URL¶

Path parameters¶

Header parameters¶

Response body¶

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 channels API¶

Retrieves the list of channels created. The channel types that can be retrieved are as follows:

• PUBLIC
• PRIVATE
• GROUP

Request URL¶

Path parameters¶

Header parameters¶

Query parameters¶

Response body¶

Response body > data¶

Response body > data > content¶

Response body > data > page¶

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 information
    ],
    "page": {
      "size": 10,
      "currentPage": 1,
      "totalElements": 100,
      "totalPages": 10
    }
  }
}

Get channel API¶

Retrieves detailed information about a specific channel.

Request URL¶

Path parameters¶

Header parameters¶

Response body¶

Response body > data¶

Response body > data > info¶

Response body > data > members¶

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 the users participating in a channel.

Request URL¶

Path parameters¶

Header parameters¶

Response body¶

Response body > data¶

Response Body > data > members¶

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¶

Path parameters¶

Header parameters¶

Request body¶

Response body¶

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¶

Allows a user to exit a channel.

The channel is not deleted if the owner exits, unless the owner is not SYSTEM and there are no participants.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

Response body¶

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