HTTP API

Overview¶

The HTTP API provides chat services by communicating with the API server via HTTP. It is mainly composed of Channel API and User API.

The main features of the channel API and user API are as follows.

• 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
  • Announcement message sending API
• User API
  • User token issuance API
  • User participating channel retrieval API
  • User block list retrieval API
  • User block API
  • User unblock API

Basic information¶

This provides basic information that you need to know when using the HTTP API.

Preparation¶

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

• Hive Certification Key: Authentication token for API calls
  • Can be found 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.

Request URL¶

Common header¶

Response code¶

• API response code

• Detailed error codes (400, 403)

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 all channel list¶

Retrieving the list of currently created channels.

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": "오픈 채팅방",
        "memberCount": 2,
        "maxMemberCount": 50,
        "regTime": "2024-12-30T15:01:01.004Z",
        "regTimeMillis": 1731306364351
      },
      /// ... 채널 정보
    ],
    "page": {
      "size": 10,
      "currentPage": 1,
      "totalElements": 100,
      "totalPages": 10
    }
  }
}

Channel lookup¶

Retrieving detailed information for 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": "오픈채팅방",
      "memberCount": 2,
      "maxMemberCount": 50,
      "regTime": "2024-12-30T15:01:01.004Z",
      "regTimeMillis": 1731306364351
    },
    "members": [
      {
        "playerId": 1,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:06.604Z",
        "connectedTimeMillis": 1739328218507
      },
      {
        "playerId": 2,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:16.233Z",
        "connectedTimeMillis": 1731306364351
      }
    ]
  }
}

Channel participants query¶

Retrieving participant information for a specific 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,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:06.604Z",
        "connectedTimeMillis": 1739328218507
      },
      {
        "playerId": 2,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:16.233Z",
        "connectedTimeMillis": 1731306364351
      }
    ]
  }
}

Create channel¶

Creating a new conversation channel.

If the playerId exists, the user will be allowed to enter the channel. If there is no playerId, the owner will be SYSTEM.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

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

Response body¶

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

Response sample¶

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

Delete channel¶

Deleting a specific 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."
}

Enter channel¶

Entering users into the existing channel.

The maximum number of channels that a user can enter is 10.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

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

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-raw '{
    "playerId": 1001,
    "password": "guildPass123"
}'

Response sample¶

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

Channel exit¶

Removing users from the channel. The channel will remain even if the channel owner leaves.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

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

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

Notice message sending¶

Sends announcement messages to a specific channel or all channels in the game. If the channelId parameter is not provided, the announcement message will be delivered to all channels created for the corresponding gameIndex.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

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

Response body¶

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",
    "message": "서버 점검이 있습니다. 잠시 후 다시 접속해 주세요."
}'

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¶

Path parameters¶

Header parameters¶

Response body¶

Response body > data¶

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¶

Path parameters¶

Header parameters¶

Response body¶

Response body > data¶

Response body > data > channels¶

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,
        "regTime": "2023-12-19T15:01:01.004Z",
        "regTimeMillis": 1731306364351
      },
      {
        "channelId": "open:67890",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "SYSTEM",
        "channelName": "오픈 채팅방",
        "memberCount": 2,
        "maxMemberCount": 100,
        "regTime": "2023-12-20T10:15:30.123Z",
        "regTimeMillis": 1731302348750
      }
      // ... 채널
    ]
  }
}

User block list retrieval¶

Retrieving the list of users blocked by the user.

Request URL¶

Path parameters¶

Header parameters¶

Response body¶

Response body > data¶

Response body > data > blockedusers¶

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¶

The user blocks a specific user.

Request URL¶

Path parameters¶

Header parameters¶

Response body¶

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¶

The user unblocks a specific user.

Request URL¶

Path parameters¶

Header parameters¶

Response body¶

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