Skip to content

Websocket api

Overview

The WebSocket API provides chat services by communicating with the socket server via WebSocket. It supports game client connection, sending channel messages, and more.

The main features of the WebSocket API are as follows:

  • Client connect / disconnect
  • PING / PONG
  • Send / receive chat messages
    • Channel chat
    • 1:1 chat
  • Blocked user filtering
    • Do not send messages to blocked users
    • Do not receive messages from blocked users
  • Channel entry and exit notifications

Basic information

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

Key terms

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

Packet types

The following packet types are sent and received with the socket server.

Packet name Description
CONNECT Connect to the socket server
RESPONSE_CONNECT Response to CONNECT request
RECONNECT Reconnect to the socket server
RESPONSE_RECONNECT Response to RECONNECT request
PING Keep connection
If PING is sent before CONNECT succeeds, the server disconnects
PONG Response to PING request
CHANNEL_CHAT Channel chat
RESPONSE_CHANNEL_CHAT Response to CHANNEL_CHAT request
DIRECT_CHAT 1:1 chat
RESPONSE_DIRECT_CHAT Response to DIRECT_CHAT request
NOTIFY_ENTER_CHANNEL Channel entry message
NOTIFY_EXIT_CHANNEL Channel exit message
NOTIFY_DELETE_CHANNEL Channel delete 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. The game server requests a token issuance from the chat Http API. ※ The issued token is used to connect to the chat Socket server

  2. The app client requests a connection to the Socket server

    • WebSocket communication
    • Use the token issued in step 1
    • Upon successful connection, 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 the channel you are participating in and send a departure notification message
  • 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 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 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 server may terminate the WebSocket connection in the following cases:

  • If there is no request from the client for 1 minute
  • If it is not in JSON format
  • When the status value is 401 or 403
    • 401 unauthorized
    • 403 forbidden
  • If you connect with another session, the existing session will be terminated

Response codes

Response status codes are as follows.

Status code Status message Description
200 Success. Success
400 Bad Request Bad request
401 Unauthorized No permission
403 Forbbiden Denied by the server
408 Request timeout The server disconnects the connection due to no request from the client for 60 seconds
409 Conflict The user's request conflicts with the server status (e.g. if the 1:1 chat partner is offline)
500 Internal Server Error Internal server error

WebSocket API functions

This section describes the API requests, responses, and example code for each function of the WebSocket API used in the chat service.

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
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 The token used for connection
Issued by 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 Return 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" // JWT created by the API server
    }
}

Response sample

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

Client reconnection

The WebSocket provides a reconnection feature as the connection may be terminated depending on the network situation. If a RECONNECT request is made within 10 minutes after the WebSocket disconnection, it will rejoin the previously joined channel.

Request parameters

Field name Description Type Required
packetType Client reconnection 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
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 The token used for connection
Issued by Chat Http API		 string Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"

Response body

Field name Description Type Required
packetType Response to reconnection request (RESPONSE_RECONNECT) string Y
status Status code integer Y
message Status message string Y
body Return 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"
channelIds List of channels that were successfully rejoined from the previously joined channels string array Y e.g. ["ch:1", "ch:2"]
failChannelIds List of channels that failed to rejoin from the previously joined channels string array Y e.g. []

Request sample

{
    "packetType": "RECONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "langCode": "en",
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" // JWT created by 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 that were successfully rejoined
        "failChannelIds":[]                // List of channels that failed to rejoin
    }
}

PING / PONG

  • Requests are only valid when the Socket server and CONNECT are successfully completed
  • If there is no PONG response, re-login is required

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

Send channel message

Request parameters

Field name Description Type Required
packetType Channel message sending 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 Account identifier sending the message to the channel
Player ID		 long Y e.g. 1234
to Channel ID to send the channel message
Chat Http API에서 생성		 string Y e.g. "open:1"
message Message to be sent to the channel
(Up to 200 characters)		 string Y e.g. "Hello World!"
extraData Additional message information (based on UTF-8)
(Up to 256 Byte)		 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 are separated by Script tag)		 string Y e.g. "en"

Response body

Field name Description Type Required
packetType Response to channel message sending (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"
}

Send 1:1 message

Request parameters

Field name Description Type Required
packetType 1:1 message sending 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 Account identifier sending the 1:1 message
Player ID		 long Y e.g. 1234
to Account identifier receiving the 1:1 message
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 (based on UTF-8)
(Up to 256 Byte)		 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 are separated by Script tag)		 string Y e.g. "en"

Response body

Field name Description Type Required
packetType Response to 1:1 message sending (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 messages

This section describes the messages sent from the server to the client when an event occurs.

These messages start with NOTIFY in the packetType.

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 Channel ID of the entry string Y e.g. "open:10"
playerId Account identifier that entered the channel
Player ID		 long Y e.g. 1234
timestamp Time of entry to the channel (UTC+0 standard, yyyy-MM-dd'T'HH:mm:ss.SSSZ format) string Y e.g. "2024-11-12T08:59:59.497Z"
timestampMillis Time of entry to the channel (UnixTimestamp 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 Channel ID of the exit string Y e.g. "open:10"
playerId Account identifier that exited the channel
Player ID		 long Y e.g. 2222
timestamp Time of exit from the channel (UTC+0 standard, yyyy-MM-dd'T'HH:mm:ss.SSSZ format) string Y e.g. "2024-11-12T08:59:59.497Z"
timestampMillis 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 delete message

Field name Description Type Required
packetType Channel delete 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 Channel ID of the deleted channel string Y e.g. "open:10"
timestamp Time of deletion of the channel (UTC+0 standard, yyyy-MM-dd'T'HH:mm:ss.SSSZ format) string Y e.g. "2024-11-12T08:59:59.497Z"
timestampMillis Time of deletion of the channel (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 notice message

Field name Description Type Required
packetType Notice 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 notice message string Y e.g. "open:10"
from Account identifier 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 Time of sending the notice message (UTC+0 standard, yyyy-MM-dd'T'HH:mm:ss.SSSZ format) string Y e.g. "2024-11-13T05:06:29.198Z"
timestampMillis Time of sending the notice message (UnixTimestamp Millisecond) long Y e.g. 1731401989

Sample

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

User notice message

Field name Description Type Required
packetType User notice 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 that received the notice message long Y e.g. 123123
from Account identifier 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 Time of sending the notice message (UTC+0 standard, yyyy-MM-dd'T'HH:mm:ss.SSSZ format) string Y e.g. "2024-11-13T05:06:29.198Z"
timestampMillis Time of sending the notice message (UnixTimestamp Millisecond) long Y e.g. 1731401989

Sample

// Notice to a specific user
{
  "packetType": "NOTIFY_NOTICE",
  "body": {
    "gameIndex": 1,
    "playerId": 123123,
    "from": "SYSTEM",
    "message": "This is a notice 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 Account identifier that sent the channel message
Player ID		 long Y e.g. 2222
to Channel ID that received 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 message information (based on UTF-8)
(Up to 256 Byte)		 string Y e.g. "bbbb"
timestamp Time of sending the channel message (UTC+0 standard, yyyy-MM-dd'T'HH:mm:ss.SSSZ format) string Y e.g. "2024-11-13T05:12:18.385Z"
timestampMillis Time of sending the channel message (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 Account identifier that received the 1:1 message
Player ID		 long Y e.g. 1234
to Account identifier that sent the 1:1 message
Player ID		 long Y e.g. 2222
message Content of the 1:1 message string Y e.g. "Hello. This is a 1:1 chat."
extraData Additional message information (based on UTF-8)
(Up to 256 Byte)		 string Y e.g. "abcd"
timestamp Time of sending the 1:1 message (UTC+0 standard, yyyy-MM-dd'T'HH:mm:ss.SSSZ format) string Y e.g. "2024-11-13T05:12:50.060Z"
timestampMillis Time of sending the 1:1 message (UnixTimestamp Millisecond) long Y e.g. 1731401989

Sample

{
  "packetType": "NOTIFY_DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 1234,
    "to": 2222,
    "message": "Hello. This is a 1:1 chat.",
    "extraData": "abcd",
    "timestamp": "2024-11-13T05:12:50.060Z",
    "timestampMillis": 1731401989
  }
}