201 lines
3.9 KiB
Markdown
201 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```json
|
|
{
|
|
"type": "init",
|
|
"name": "alice_1",
|
|
"room": "lobby",
|
|
"password": ""
|
|
}
|
|
```
|
|
|
|
## Wichtige Antworttypen
|
|
|
|
- Token:
|
|
|
|
```json
|
|
{"type":1,"message":"<token>"}
|
|
```
|
|
|
|
- Raumliste:
|
|
|
|
```json
|
|
{"type":3,"message":[{"name":"lobby","users":2}]}
|
|
```
|
|
|
|
- Raum betreten / Status:
|
|
|
|
```json
|
|
{"type":5,"message":"room_entered","to":"lobby"}
|
|
```
|
|
|
|
- Chatnachricht:
|
|
|
|
```json
|
|
{"type":"message","userName":"alice","message":"Hallo","color":"#33aaee"}
|
|
```
|
|
|
|
- Fehler:
|
|
|
|
```json
|
|
{"type":"error","message":"invalid_token"}
|
|
```
|
|
|
|
## Commands (WebSocket JSON)
|
|
|
|
Nach erfolgreichem `init` (mit `token`):
|
|
|
|
- Nachricht senden
|
|
|
|
```json
|
|
{"type":"message","message":"Hallo zusammen","token":"..."}
|
|
```
|
|
|
|
- Raum wechseln
|
|
|
|
```json
|
|
{"type":"join","room":"sports","password":"","token":"..."}
|
|
```
|
|
|
|
- Räume abfragen
|
|
|
|
```json
|
|
{"type":"rooms","token":"..."}
|
|
```
|
|
|
|
- Userliste des aktuellen Raums
|
|
|
|
```json
|
|
{"type":"userlist","token":"..."}
|
|
```
|
|
|
|
- Farbe setzen
|
|
|
|
```json
|
|
{"type":"color","value":"#33aaee","token":"..."}
|
|
```
|
|
|
|
- Aktionen
|
|
|
|
```json
|
|
{"type":"scream","message":"Hallo alle","token":"..."}
|
|
{"type":"do","message":"winkt","token":"..."}
|
|
{"type":"dice","message":"1d6","token":"..."}
|
|
{"type":"roll","value":4,"token":"..."}
|
|
```
|
|
|
|
- Dice-Game
|
|
|
|
```json
|
|
{"type":"start_dice_game","rounds":3,"token":"..."}
|
|
{"type":"end_dice_game","token":"..."}
|
|
```
|
|
|
|
- Räume neu laden
|
|
|
|
```json
|
|
{"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:
|
|
|
|
```json
|
|
{"type":"message","message":"/join lounge geheim","token":"..."}
|
|
```
|
|
|
|
## Minimales Browser-Beispiel (Vanilla JS)
|
|
|
|
```javascript
|
|
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
|
|
- `loggedin`: Username ist bereits aktiv
|
|
- `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)
|
|
- 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
|