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 each 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 the basic information that you need to know when using the HTTP API.

Preparation¶

You need to prepare the following items to use the HTTP API.

• Hive Certification Key (Hive 인증키): 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.

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": "Open chat room",
        "maxMemberCount": 50,
        "regTime": "2024-12-30T15:01:01.004Z"
      },
      /// ... Channel information
    ],
    "page": {
      "size": 10,
      "currentPage": 1,
      "totalElements": 100,
      "totalPages": 10
    }
  }
}

Channel retrieval¶

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": "Open Chat Room",
        "maxMemberCount": 50,
        "regTime": "2024-12-30T15:01:01.004Z"
    },
    "members": [
      {
        "playerId": 1,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:06.604Z"
      },
      {
        "playerId": 2,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:16.233Z"
      }
    ]
  }
}

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"
      },
      {
        "playerId": 2,
        "extraData": null,
        "connectedTime": "2024-11-25T06:22:16.233Z"
      }
    ]
  }
}

Create channel¶

Creating a new conversation channel.

If the playerId exists, the user will be allowed to enter the channel. If the playerId does not exist, 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": "Open chat room",
    "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 a user from the channel. If the channel owner leaves, the channel will be deleted.

Request URL¶

Path parameters¶

Header parameters¶

Request body¶

This is the transmission data required when requesting to leave 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 sent 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": "Server maintenance is in progress. Please try connecting again later."
}'

Response sample¶

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

User API features¶

This explains the API requests and responses for each feature of the user API 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¶

Retrieving 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": "Guild chat room",
        "maxMemberCount": 50,
        "regTime": "2023-12-19T15:01:01.004Z"
      },
      {
        "channelId": "open:67890",
        "type": "PUBLIC",
        "gameIndex": 1,
        "owner": "SYSTEM",
        "channelName": "Open chat room",
        "maxMemberCount": 100,
        "regTime": "2023-12-20T10:15:30.123Z"
      }
      // ... channel
    ]
  }
}

User block list inquiry¶

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"
      },
      {
        "blockedPlayerId": 1003,
        "blockedTime": "2023-12-21T08:45:12.456Z"
      },
      // ... Block list
    ]
  }
}

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