Chat

Altzone Chat WebSockets API – Client Integration Guide

Overview

The Altzone chat system uses WebSockets protocol for real-time messaging. The /ws/chat endpoint provides the chat functionality.

The API supports both global and clan chats, including message sending and reactions. All data description that each message contains can be found from swagger for /chat endpoints.

Notice that the chats has also history, that can be obtained via HTTP endpoints, which are described in the swagger.

---

1. Connecting to chat via Web Sockets

URL:

wss://altzone.fi/api/ws/chat //production version
wss://devapi.altzone.fi/ws/chat //dev version
wss://devapi.altzone.fi/latest-release/ws/chat //latest release version

Authentication

JWT token is required, which is the same token as for "normal" (HTTP) API calls. You can provide it with two methods:

• Pass the token as a query parameter:
  wss://altzone.fi/api/ws/chat?token=<JWT_TOKEN>
• Or as an Authorization header:
  Authorization: Bearer <JWT_TOKEN>

If authentication fails, the connection will be rejected.

When connection was successful, the following will happen:

• Attach user info to the connection.
• Automatically join the user to their clan and the global chat rooms.

---

2. Message Types

The information sent to the chat consists of two pieces:

• event, or what has happen. It determines the content of the data, so that different events expects different data.
• data, the information itself

At the moment there can be sent two types of information:

• message
• reaction to a message

Below are detailed examples of all possible events.

a. Clan Chat

Event names starts from "clanMessage".

• Send a message:
  Payload:

  {
    "event": "clanMessage",
    "data": {
      "content": "Hello clan!",
      "feeling": "happy" //optional
    }
  }

• React to a message:
  Payload:

  {
    "event": "clanMessageReaction",
    "data": {
      "message_id": "<MESSAGE_ID>",
      "emoji": "🔥"
    }
  }

b. Global Chat

Event names starts from "globalMessage".

• Send a message:
  Payload:

  {
    "event": "globalMessage",
    "data": {
      "content": "Hello world!",
      "feeling": "excited" //optional
    }
  }

• React to a message:
  Payload:

  {
    "event": "globalMessageReaction",
    "data": {
      "message_id": "<MESSAGE_ID>",
      "emoji": "👍"
    }
  }

---

3. Receiving Messages

All chat new messages and reactions to them are broadcasted to all connected clients in the relevant room (clan or global). That means that all the clients connected to a chat will get all of the updates.

The information sent will contain the following pieces:

• chat, chat type can be "clan" or "global"
• event, or what happen, can be "newMessage" or "newReacion"
• message, the updated message

The API will send messages in a json format:

{
  "chat": "clan", // or "global"
  "event": "newReaction",
  "message": {
    "_id": "<MESSAGE_ID>",
    "clan_id": "<CLAN_ID>",
    "sender": {
      "_id": "<PLAYER_ID>",
      "name": "<PLAYER_NAME>",
      "avatar": {<PLAYER_AVATAR>},
    "content": "Wadup globalz",
    "type": "global",
    "reactions": [
      {
        "playerName": "<PLAYER_NAME>",
        "emoji": "🫡"
      }
    ],
    "createdAt": "2025-06-23T13:03:15.778Z"
  }
}

---

4. Disconnection & Room Management

• On disconnect, the user is removed from all chat rooms.
• If a user leaves a clan, the server should be notified to remove them from the clan chat room.

---

5. Error Handling

• If an error occurs (e.g., invalid token, missing fields), the server may send an error message:

  {
    "error": [
      {
        "reason": "NOT_FOUND",
        "field": "_id",
        "value": "68595093c721e4551c90e207",
        "message": "Could not find any objects with specified id",
        "additional": null
      }
    ]
  }

  Or, for simpler errors:

  {
    "error": "Error description"
  }

---

6. Example Usage (JavaScript)

const ws = new WebSocket('wss://<SERVER_HOST>/ws/chat?token=<JWT_TOKEN>');

ws.onopen = () => {
  ws.send(JSON.stringify({
    event: 'clanMessage',
    data: { content: 'Hello clan!' }
  }));
};

ws.onmessage = (msg) => {
  const data = JSON.parse(msg.data);
  // handle incoming messages
};

---

7. Notes

• Replace <SERVER_HOST>, <PORT>, and <JWT_TOKEN> with actual values.
• All payloads must be sent as JSON.
• The server expects specific event names as described above.

---