yourchat2/WEB_DIALOG_INTEGRATION.md

Web-Dialog Integration mit yourchat2

Diese Doku beschreibt, wie eine Web-Applikation den Chat-Dialog mit dem Daemon yourchat2 verbindet. Sie ist absichtlich auf das Protokoll und die Client-Integration fokussiert (ohne Betriebs-/Startanleitung).

Verbindung

• Transport: WebSocket
• Standard-Endpunkt: ws://<host>:1235
• Nachrichtenformat: JSON (ein JSON-Objekt pro WebSocket-Frame)

Verbindungs- und Login-Flow

1. WebSocket verbinden
2. init senden
3. Token (type: 1) aus der Antwort speichern
4. Alle weiteren auth-pflichtigen Commands mit token senden

init Beispiel

{
  "type": "init",
  "name": "alice_1",
  "room": "lobby",
  "password": ""
}

Wichtige Antworttypen

• Token:

{"type":1,"message":"<token>"}

• Raumliste:

{"type":3,"message":[{"name":"lobby","users":2}]}

• Raum betreten / Status:

{"type":5,"message":"room_entered","to":"lobby"}

• Erzwungenes Logout bei Session-Ersatz (Reconnect mit gleichem Namen):

{"type":5,"message":"logout","reason":"replaced_by_new_login"}

• Chatnachricht:

{"type":"message","userName":"alice","message":"Hallo","color":"#33aaee"}

• Fehler:

{"type":"error","message":"invalid_token"}

Commands (WebSocket JSON)

Nach erfolgreichem init (mit token):

• Nachricht senden

{"type":"message","message":"Hallo zusammen","token":"..."}

• Raum wechseln

{"type":"join","room":"sports","password":"","token":"..."}

• Räume abfragen

{"type":"rooms","token":"..."}

• Userliste des aktuellen Raums

{"type":"userlist","token":"..."}

• Farbe setzen

{"type":"color","value":"#33aaee","token":"..."}

• Aktionen

{"type":"scream","message":"Hallo alle","token":"..."}
{"type":"do","message":"winkt","token":"..."}
{"type":"dice","message":"1d6","token":"..."}
{"type":"roll","value":4,"token":"..."}

• Dice-Game

{"type":"start_dice_game","rounds":3,"token":"..."}
{"type":"end_dice_game","token":"..."}

• Räume neu laden

{"type":"reload_rooms","token":"..."}

Slash-Commands im Dialogtext

Wenn das Frontend nur type:"message" sendet, werden folgende Slash-Kommandos serverseitig erkannt:

• /join <room> [password]
• /color <hex>
• /dice [expr]
• /roll [wert]
• /start_dice_game <runden>
• /end_dice_game
• /reload_rooms
• /do <aktion>
• /scream <text>
• /rooms
• /userlist

Beispiel:

{"type":"message","message":"/join lounge geheim","token":"..."}

Minimales Browser-Beispiel (Vanilla JS)

const ws = new WebSocket("ws://127.0.0.1:1235");
let token = null;

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "init",
    name: "alice_1",
    room: "lobby",
    password: ""
  }));
};

ws.onmessage = (ev) => {
  const msg = JSON.parse(ev.data);

  if (msg.type === 1) {
    token = msg.message;
    return;
  }

  if (msg.type === "error") {
    console.error("chat error:", msg.message);
    return;
  }

  if (msg.type === "message") {
    console.log(`${msg.userName}: ${msg.message}`);
    return;
  }

  console.log("chat event:", msg);
};

function sendMessage(text) {
  if (!token) return;
  ws.send(JSON.stringify({ type: "message", message: text, token }));
}

Häufige Fehlercodes

• missing_name: init ohne name
• invalid_username: Username entspricht nicht den Regeln
• user_not_allowed: User nicht erlaubt (DB/Allowlist)
• not_initialized: Command vor init
• missing_token: Token fehlt
• invalid_token: Token stimmt nicht
• room_not_found_or_join_failed: Raumzugriff verweigert (Passwort/Alter/Regeln)
• permission_denied: fehlende Rechte (z. B. Dice-Admin-Operationen)

Hinweise für Frontend-Implementierung

• Token zentral im Chat-State halten
• Reconnect-Strategie einbauen (neues init, neues Token); alte Session wird dabei serverseitig ersetzt
• Vor Senden auth-pflichtiger Commands Token prüfen
• UI sollte Fehler vom Typ error immer sichtbar machen
• Für Slash-Kommandos reicht normales message-Senden