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 is commonly needed 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 packet types for sending and receiving with the socket server are as follows.

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.

   • Request the User Token Issuance API using the Hive Certification Key

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

   • 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 communication structure¶

• JSON format of packet types starting with 'RESPONSE_'
  

  {
          "packetType":"Packet Type",
          "status":"Status Code",
          "message":"Status Message",
          "body": JSON Object
  }
  

• Other packet formats

  {
          "packetType":"Packet Type",
          "body":{
                  //JSON data according to packetType
          }
  }
  

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

• If there are no requests for 1 minute on the client side
• When it is not in JSON format
• When the status value is 401 or 403
  • 401 unauthorized
  • 403 forbidden

Response code¶

This is the response status code.

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¶

Request parameters > body¶

Response body¶

Response body > body¶

Request sample¶

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "loginKey": JWT generated by API server,
        "extraData": Additional information
    }
}

Response sample¶

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

Client Disconnection¶

Request parameters¶

Request parameters > body¶

• If the sessionId is not specified, the disconnection process for the sessionId assigned to the websocket will be handled.
• If the sessionId is specified, the disconnection process for that value will be handled.

Response body¶

Request sample¶

• If the sessionId is not specified

  {
          "packetType":"DISCONNET"
  }
  

• When specifying the sessionId

  {
          "packetType":"DISCONNECT",
          "body":{
                  "sessionId":"6c2408fffe8c91a8-00002f24-00000032-093b757cdc668383-54b4fbc1"
          }
  }
  

Response sample¶

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

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¶

Response body¶

Request sample¶

{
    "packetType":"PING"   
}

Response Sample¶

{
    "packetType": "PONG"   
}

Channel message sending¶

Request parameters¶

Request parameters > body¶

Response body¶

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¶

Request parameters > body¶

Response body¶

Response body > body¶

Request sample¶

{
  "packetType": "DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 2222,
    "to": 1234,
    "message": "Hello",
    "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 NOTIFY.

Channel entry message¶

Body¶

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¶

Body¶

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¶

Body¶

Sample¶

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

Channel Announcement Message¶

Body¶

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¶

Body¶

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¶

Body¶

Sample¶

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