Skip to content

WebSocket API

Overview

The WebSocket API provides chat services 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 entry and exit 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 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.
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_NOTICE User notice message
NOTIFY_CHANNEL_CHAT Channel chat message
NOTIFY_DIRECT_CHAT 1:1 chat message

Socket connection process

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

  2. App client requests connection to the Socket server

    • WebSocket communication
    • Use the token issued in step 1
    • If the connection is successful, the Socket server returns 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 disconnects the WebSocket connection.

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

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 the server state (e.g. when the 1:1 chat partner 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 connection

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
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. "en"
loginKey Token used for access
Issued from Chat Http API		 string Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"

Response body

Field Name Description Type Required
packetType Response to 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 Value returned upon successful connection string Y e.g. "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"

Request sample

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "langCode": "en",
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" // API 서버에서 생성한 JWT
    }
}

Response sample

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

Client reconnection

A reconnection feature is provided as the WebSocket connection may be disconnected depending on the network situation. If a RECONNECT request is made within 10 minutes after the WebSocket disconnection, you will rejoin 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
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. "en"
loginKey Token used for access
Issued from Chat Http API		 string Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"

Response body

Field Name Description Type Required
packetType Response to the reconnection 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 joined from previously participated channels string array Y e.g. ["ch:1", "ch:2"]
failChannelIds List of channels that failed to join from previously participated channels string array Y e.g. []

Request sample

{
    "packetType": "RECONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "langCode": "en",
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" // JWT generated from the API server  
    }
}

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 the message to the channel
Hive player ID		 long Y e.g. 1234
to Channel ID to send the message to the channel
Chat Http API created		 string Y e.g. "open:1"
message Message to send to the channel
(up to 200 characters)		 string Y e.g. "Hello World!"
extraData Additional information for the message (UTF-8 based)
(up to 256 Bytes)		 string Y e.g. "bbbb"
langCode Language code of the sent message
Hive language code
(Based on ISO 639 alpha-2, languages that are not distinguished by ISO 639 alpha-2 should be separated by 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!",
        "extraData": "bbbb",
        "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 recipient 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!"
extraData Additional message information (UTF-8 based)
(up to 256 Bytes)		 string Y e.g. "bbbb"
langCode Language code of the sent message
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": "안녕하세요",
    "extraData": "bbbb",
    "langCode": "ko"
  }
}

Response sample

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

Socket server event message

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

This message starts with packetType 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
timestamp Date and time of entry into the channel (based on UTC+0, format yyyy-MM-dd'T'HH:mm:ss.SSSZ) string Y e.g. "2024-11-12T08:59:59.497Z"
timestampMillis Date and time of entry into the channel (Unix Timestamp Millisecond) long Y e.g. 1731401989

Sample

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

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 ID of the channel exited string Y e.g. "open:10"
playerId Identifier of the account exited from the channel
Hive player ID		 long Y e.g. 2222
timestamp Date and time of exit from the channel (UTC+0 standard, format yyyy-MM-dd'T'HH:mm:ss.SSSZ) string Y e.g. "2024-11-12T08:59:59.497Z"
timestampMillis Date and time of exit from the channel (UnixTimestamp Millisecond) long Y e.g. 1731401989

Sample

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

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"
timestampMillis Date and time the channel was deleted (UnixTimestamp Millisecond) long Y e.g. 1731401989

Sample

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

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 Y 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"
timestampMillis Date and time when the notification message was sent (UnixTimestamp Millisecond) long Y e.g. 1731401989

Sample

// 특정 채널에 공지
{
  "packetType": "NOTIFY_CHANNEL_NOTICE",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "from": "SYSTEM",
    "message": "공지 메시지 입니다.",
    "timestamp": "2024-11-13T05:06:29.198Z",
    "timestampMillis": 1731401989
  }
}

User notice message

Field Name Description Type Required
packetType User notification message (NOTIFY_NOTICE) string Y
body Request data object Y

Body

Field Name Description Type Required Example
gameIndex Hive game index integer Y e.g. 1
playerId Player ID who received the notice message long Y e.g. 123123
from Identifier of the account that sent the notice message string Y e.g. SYSTEM
message Content of the notice message string Y e.g. "This is a notice message."
timestamp Date and time when the notice 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"
timestampMillis Date and time when the notice message was sent (UnixTimestamp Millisecond) long Y e.g. 1731401989

Sample

// Notice message for a specific user
{
  "packetType": "NOTIFY_NOTICE",
  "body": {
    "gameIndex": 1,
    "playerId": 123123,
    "from": "SYSTEM",
    "message": "공지 메시지 입니다.",
    "timestamp": "2024-11-13T05:06:29.198Z",
    "timestampMillis": 1731401989
  }
}

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
to Channel ID that sent the channel message string Y e.g. "open:10"
message Content of the channel message string Y e.g. "Hello. This is a channel chat."
extraData Additional information of the message (UTF-8 based)
(maximum 256 Byte)		 string Y e.g. "bbbb"
timestamp Date and time of the channel message sent (UTC+0 based, format yyyy-MM-dd'T'HH:mm:ss.SSSZ) string Y e.g. "2024-11-13T05:12:18.385Z"
timestampMillis Date and time of the channel message sent (UnixTimestamp Millisecond) long Y e.g. 1731401989

Sample

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

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
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."
extraData Additional message information (UTF-8 based)
(maximum 256 Byte)		 string Y e.g. "abcd"
timestamp 1:1 message sent date and time (UTC+0 based, yyyy-MM-dd'T'HH:mm:ss.SSSZ format) string Y e.g. "2024-11-13T05:12:50.060Z"
timestampMillis 1:1 message sent date and time (UnixTimestamp Millisecond) long Y e.g. 1731401989

Sample

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