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:

• 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¶

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 (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¶

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'{
    "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¶

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 created channel and sends a channel deletion event to the users in that 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 channel list API¶

Retrieves the list of created channels. The channel types available for retrieval 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 info
    ],
    "page": {
      "size": 10,
      "currentPage": 1,
      "totalElements": 100,
      "totalPages": 10
    }
  }
}

Get channel API¶

Retrieves detailed information of a created 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 users who have joined 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¶

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¶

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