Skip to content

WebSocket API

Overview

The WebSocket API provides a chat service by communicating with the Socket server via WebSocket. It supports game client connections, channel message transmissions, and more.

The main features of the WebSocket API are as follows.

  • Client connection / disconnection
  • PING / PONG
  • Sending / receiving chat messages
    • Channel chat
    • 1:1 chat
  • Filtering blocked users
    • Do not send messages to blocked users
    • Do not receive messages from blocked users
  • Channel join and leave notifications

Basic information

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

Key terms

  • Channel: Chat Room
  • Channel Message: A chat message sent to all users in the joined channel
  • 1:1 Message: A chat message sent only to a specific user

Packet type

The types of packets for sending and receiving with the socket server are as follows.

Packet Name Description
CONNECT Connect to the socket server
RESPONSE_CONNECT Response to the CONNECT request
RECONNECT Reconnect to the socket server
RESPONSE_RECONNECT Response to the RECONNECT request
PING Keep connection alive
If PING is requested while CONNECT has not succeeded, the server will disconnect the connection
PONG Response to the PING request
CHANNEL_CHAT Channel chat
RESPONSE_CHANNEL_CHAT Response to the CHANNEL_CHAT request
DIRECT_CHAT 1:1 chat
RESPONSE_DIRECT_CHAT Response to the DIRECT_CHAT request
NOTIFY_ENTER_CHANNEL Channel entry message
NOTIFY_EXIT_CHANNEL Channel exit message
NOTIFY_DELETE_CHANNEL Channel deletion message
NOTIFY_CHANNEL_NOTICE Channel notice message
NOTIFY_CHANNEL_CHAT Channel chat message
NOTIFY_DIRECT_CHAT 1:1 chat message
NOTIFY_DISCONNECT Disconnection message
When the WebSocket connection is idle, and the Json format is invalid, it responds with this packet type

Socket connection process

  1. Request a token issuance through the chat Http API on the game server. ※ The issued token is used for connecting to the chat Socket server

  2. Connection request to the Socket server from the game client

    • WebSocket communication
    • Use the token issued in step 1
    • If the connection is successful, the Socket server will return the information below
    {
    "packetType":"RESPONSE_CONNECT",
    "status": 200,
    "message": "OK",
    "body":{
        "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
    }
}

Socket disconnection

When the WebSocket connection is terminated, the server performs the following actions.

  • Exit from the participating channel and send exit notification messages
  • Delete connection information

Socket communication structure

WebSocket communication is performed in JSON format. The request packet format is as follows.

{
        "packetType":"Packet type",
        "correlationId":"Identifier for matching the response to the request",
        "body": {
                // JSON data according to packetType
        }
}


The following is the response packet format.

{
        "packetType":"Packet type (starts with RESPONSE)",
        "correlationId":"Identifier for matching the response to the request",
        "status":"Status code",
        "message":"Status message",
        "body": // JSON Object
}


The following is the server message packet format.

{
        "packetType":"Packet type (starts with NOTIFY)",
        "body":{
                // JSON data according to packetType
        }
}


The following cases apply when the server-side disconnects the WebSocket connection.

  • If there are no requests from the client side for 1 minute
  • When it is not in JSON format
  • When the status value is 401 or 403
    • 401 unauthorized
    • 403 forbidden
  • If accessing from another session, the existing session will be terminated

Response code

This is the response status code.

Status Code Status Message Description
200 Success. Success
400 Bad Request Bad Request
401 Unauthorized Unauthorized
403 Forbidden Forbidden by the server
408 Request timeout Connection closed by the server due to no requests from the client for 60 seconds
409 Conflict User's request conflicts with server state (e.g. when the chat partner in a 1:1 chat is offline)
500 Internal Server Error Internal Server Error

Websocket API features

This explains the API requests and responses for each function of the WebSocket API used in the chat service, along with example code.

Client access

Request parameters

Field Name Description Type Required
packetType Client connection command (CONNECT) string Y
body Request data object Y
Request parameters > body
Field Name Description Type Required Example
gameIndex Hive game index integer Y e.g. 1
playerId Account identifier
Hive player ID		 long Y e.g. 1234
loginKey Token used for access
Issued from Chat Http API		 string Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"
extraData User additional information (UTF-8 based)
(up to 256 Bytes)		 string N e.g. "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}"

Response body

Field Name Description Type Required
packetType Response to the connection request (RESPONSE_CONNECT) string Y
status Status code integer Y
message Status message string Y
body Returned data object Y
Response body > body
Field Name Description Type Required Example
sessionId The value returned upon successful connection string Y e.g. "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"

Request sample

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY", // JWT generated by the API server
        "extraData": "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}" // Additional information
    }
}

Response sample

{
    "packetType":"RESPONSE_CONNECT",
    "status": 200,
    "message":"OK",
    "body":{
        "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
    }
}

Client reconnection

The reconnection feature is provided because the WebSocket connection may be disconnected depending on the network situation. If a RECONNECT request is made within 10 minutes after the WebSocket connection is disconnected, you will enter the channel you previously participated in.

Request parameters

Field Name Description Type Required
packetType Client reconnect command (RECONNECT) string Y
body Request data object Y
Request parameters > body
Field Name Description Type Required Example
gameIndex Hive game index integer Y e.g. 1
playerId Account identifier
Hive player ID		 long Y e.g. 1234
loginKey Token used for access
Chat Http API issued		 string Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"
extraData User additional information (UTF-8 based)
(maximum 256 Byte)		 string N e.g. "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}"

Response body

Field Name Description Type Required
packetType Response to reconnect request (RESPONSE_RECONNECT) string Y
status Status code integer Y
message Status message string Y
body Returned data object Y
Response body > body
Field Name Description Type Required Example
sessionId The value returned upon successful connection string Y e.g. "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
channelIds List of channels that were successfully entered among previously participated channels array Y e.g. ["ch:1", "ch:2"]
failChannelIds List of channels that failed to enter among previously participated channels array Y e.g. []

Request sample

{
    "packetType": "RECONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY", // JWT generated by the API server
        "extraData": "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}" // Additional information
    }
}

Response sample

{
    "packetType":"RESPONSE_RECONNECT",
    "status": 200,
    "message":"OK",
    "body":{
        "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76",
        "channelIds":["ch:1", "ch:2"], // List of channels successfully joined from previously participated channels
        "failChannelIds":[]                // List of channels that failed to join from previously participated channels
    }
}

PING / PONG

  • Requests are valid only when the socket server and CONNECT are completed.
  • Re-login is required if there is no PONG response

Request parameters

Field Name Description Type Required
packetType PING request command (PING) string Y

Response body

Field Name Description Type Required
packetType PONG response command (PONG) string Y

Request sample

{
    "packetType":"PING"   
}

Response sample

{
    "packetType": "PONG"   
}

Channel message sending

Request parameters

Field Name Description Type Required
packetType Channel message transmission command (CHANNEL_CHAT) string Y
body Request data object Y
Request parameters > body
Field Name Description Type Required Example
gameIndex Hive game index integer Y e.g. 1
from Identifier of the account to send messages to the channel
Hive player ID		 long Y e.g. 1234
to Channel ID to send the channel message
Chat Http API created		 string Y e.g. "open:1"
message Message to send to the channel
(maximum 200 characters)		 string Y e.g. "Hello World!"
langCode Hive language code
(based on ISO 639 alpha-2, languages not distinguished by ISO 639 alpha-2 should be distinguished with a Script tag)		 string Y e.g. "en"

Response body

Field Name Description Type Required
packetType Response to channel message transmission (RESPONSE_CHANNEL_CHAT) string Y
status Status code integer Y
message Status message string Y

Request sample

{
    "packetType":"CHANNEL_CHAT",
    "body": {
        "gameIndex": 1,
        "from": 1234,
        "to": "open:1",
        "message": "Hello World!",
        "langCode": "en"
    }
}

Response sample

{
    "packetType": "RESPONSE_CHANNEL_CHAT",
    "status": 200,
    "message":"OK"
}

1:1 message sending

Request parameters

Field Name Description Type Required
packetType 1:1 message transmission command (DIRECT_CHAT) string Y
body Request data object Y
Request parameters > body
Field Name Description Type Required Example
gameIndex Hive Game Index integer Y e.g. 1
from 1:1 Message Sender Account Identifier
Hive Player ID		 long Y e.g. 1234
to 1:1 Message Receiver Account Identifier
Hive Player ID		 long Y e.g. 2222
message Message to be sent 1:1
(up to 200 characters)		 string Y e.g. "Hello World!"
langCode Hive Language Code
(based on ISO 639 alpha-2, languages not distinguished by ISO 639 alpha-2 should be separated with a Script tag)		 string Y e.g. "en"

Response body

Field Name Description Type Required
packetType Response to 1:1 message transmission (RESPONSE_DIRECT_CHAT) string Y
status Status code integer Y
message Status message string Y
Response body > body
Field Name Description Type Required Example
status Response status code integer Y e.g. 200

Request sample

{
  "packetType": "DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 2222,
    "to": 1234,
    "message": "안녕하세요",
    "langCode": "ko"
  }
}

Response sample

{
    "packetType": "RESPONSE_DIRECT_CHAT",
    "status": 200,
    "message":"OK"
}

Socket server event message

This explains the messages sent from the Server to the Client when an event occurs.

This message starts with packetType as NOTIFY.

Channel entry message

Field Name Description Type Required
packetType Channel entry message (NOTIFY_ENTER_CHANNEL) string Y
body Request data object Y

Body

Field Name Description Type Required Example
gameIndex Hive game index integer Y e.g. 1
channelId Entered channel ID string Y e.g. "open:10"
playerId Identifier for the account that entered the channel
Hive player ID		 long Y e.g. 1234
extraData User additional information (UTF-8 standard)
(maximum 256 Byte)		 string Y e.g. "abcd"
timestamp Date and time of entry into the channel (UTC+0 standard, format yyyy-MM-dd'T'HH:mm:ss.SSSZ) string Y e.g. "2024-11-12T08:59:59.497Z"

Sample

{
  "packetType": "NOTIFY_ENTER_CHANNEL",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "playerId": 1234,
    "extraData": "abcd",
    "timestamp": "2024-11-12T08:59:59.497Z"
  }
}

Channel exit message

Field Name Description Type Required
packetType Channel exit message (NOTIFY_EXIT_CHANNEL) string Y
body Request data object Y

Body

Field Name Description Type Required Example
gameIndex Hive game index integer Y e.g. 1
channelId Exited channel ID string Y e.g. "open:10"
playerId Identifier of the account that exited the channel
Hive player ID		 long Y e.g. 2222
extraData User additional information (UTF-8 based)
(maximum 256 Byte)		 string Y e.g. "abcd"
timestamp Date and time when the channel was exited (UTC+0 based, format yyyy-MM-dd'T'HH:mm:ss.SSSZ) string Y e.g. "2024-11-12T08:59:59.497Z"

Sample

{
  "packetType": "NOTIFY_EXIT_CHANNEL",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "playerId": 2222,
    "extraData": "abcd",
    "timestamp": "2024-11-12T09:29:35.872Z"
  }
}

Channel deletion message

Field Name Description Type Required
packetType Channel deletion message (NOTIFY_DELETE_CHANNEL) string Y
body Request data object Y

Body

Field Name Description Type Required Example
gameIndex Hive Game Index integer Y e.g. 1
channelId Deleted Channel ID string Y e.g. "open:10"
timestamp Date and time the channel was deleted (based on UTC+0, format yyyy-MM-dd'T'HH:mm:ss.SSSZ) string Y e.g. "2024-11-12T08:59:59.497Z"

Sample

{
  "packetType": "NOTIFY_DELETE_CHANNEL",
  "body": {
    "gameIndex": 1,
    "channelId": "owner:1",
    "timestamp": "2024-11-13T05:06:29.198Z"
  }
}

Channel announcement message

Field Name Description Type Required
packetType Notification message (NOTIFY_CHANNEL_NOTICE) string Y
body Request data object Y

Body

Field Name Description Type Required Example
gameIndex Hive game index integer Y e.g. 1
channelId Channel ID that received the notification message string N e.g. "open:10"
from Identifier of the account that sent the notification message string Y e.g. SYSTEM
message Content of the notification message string Y e.g. "This is a notification message."
timestamp Date and time when the notification message was sent (based on UTC+0, format yyyy-MM-dd'T'HH:mm:ss.SSSZ) string Y e.g. "2024-11-13T05:06:29.198Z"

Sample

// Announce to specific channel
{
  "packetType": "NOTIFY_CHANNEL_NOTICE",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "from": "SYSTEM",
    "message": "This is an announcement message.",
    "timestamp": "2024-11-13T05:06:29.198Z"
  }
}

Channel message

Field Name Description Type Required
packetType Channel message (NOTIFY_CHANNEL_CHAT) string Y
body Request data object Y

Body

Field Name Description Type Required Example
gameIndex Hive game index integer Y e.g. 1
from Identifier of the account that sent the channel message
Hive player ID		 long Y e.g. 2222
fromExtra User additional information (UTF-8 based)
(maximum 256 Byte)		 string Y e.g. "bbbb"
to Channel ID that sent the channel message string Y e.g. "open:10"
langCode Hive language code
(based on ISO 639 alpha-2, languages not distinguished by ISO 639 alpha-2 should be distinguished by attaching a Script tag)		 string Y e.g. "ko"
timestamp Date and time when the channel message was sent (UTC+0 based, format yyyy-MM-dd'T'HH:mm:ss.SSSZ) string Y e.g. "2024-11-13T05:12:18.385Z"

Sample

{
  "packetType": "NOTIFY_CHANNEL_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 2222,
    "fromExtra": "bbbb",
    "to": "open:10",
    "message": "Hello World!",
    "langCode": "ko",
    "timestamp": "2024-11-13T05:12:18.385Z"
  }
}

1:1 message

Field Name Description Type Required
packetType 1:1 message (NOTIFY_DIRECT_CHAT) string Y
body Request data object Y

Body

Field Name Description Type Required Example
gameIndex Hive game index integer Y e.g. 1
from 1:1 message sender account identifier
Hive player ID		 long Y e.g. 1234
fromExtra User additional information (UTF-8 based)
(maximum 256 Byte)		 string Y e.g. "abcd"
to 1:1 message recipient account identifier
Hive player ID		 long Y e.g. 2222
message 1:1 message content string Y e.g. "Hello. This is a 1:1 chat."
langCode Hive language code
(based on ISO 639 alpha-2, languages not distinguished by ISO 639 alpha-2 are separated by Script tag)		 string Y e.g. "ko"
timestamp 1:1 message sent date and time (UTC+0 based, format yyyy-MM-dd'T'HH:mm:ss.SSSZ) string Y e.g. "2024-11-13T05:12:50.060Z"

Sample

{
  "packetType": "NOTIFY_DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 1234,
    "fromExtra": "abcd",
    "to": 2222,
    "message": "안녕하세요. 1:1 채팅입니다.",
    "langCode": "ko",
    "timestamp": "2024-11-13T05:12:50.060Z"
  }
}