From 1e66646f521154382224d80dfa998eca40f940e8 Mon Sep 17 00:00:00 2001 From: Christian Mueller Date: Fri, 24 Apr 2026 17:03:29 +0200 Subject: [PATCH] docs: add Starface Modulcreator guide and webhook test script Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/starface-modul-anleitung.md | 130 +++++++++++++++++++++++++++++++ docs/test-starface.sh | 36 +++++++++ 2 files changed, 166 insertions(+) create mode 100644 docs/starface-modul-anleitung.md create mode 100644 docs/test-starface.sh diff --git a/docs/starface-modul-anleitung.md b/docs/starface-modul-anleitung.md new file mode 100644 index 0000000..045bee4 --- /dev/null +++ b/docs/starface-modul-anleitung.md @@ -0,0 +1,130 @@ +# Starface Modulcreator – Busylight Integration + +## Übersicht + +Dieses Modul sendet bei jedem Anruf-Event einen HTTP-Request an den Busylight-Server, +damit die Türschilder automatisch den Telefonstatus anzeigen. + +## Voraussetzungen + +- Starface Telefonanlage mit Modulcreator-Lizenz +- Busylight-Server erreichbar unter `http://BUSYLIGHT-IP:8081` +- Durchwahlen der Mitarbeiter im Busylight-Portal eingetragen + +## Modul im Modulcreator erstellen + +### Schritt 1: Neues Modul anlegen + +1. Starface Admin-Oberfläche öffnen +2. **Admin** → **Modulcreator** (oder **Module** → **Modulcreator**) +3. **Neues Modul erstellen** +4. Modulinformationen: + - **Name**: `Busylight` + - **Beschreibung**: `Sendet Telefonstatus an Busylight Türschilder` + - **Vendor**: `cynfo GmbH` + - **Version**: `1.0.0` + +### Schritt 2: Modulkonfiguration (Instanz-Variablen) + +Unter **Modulkonfiguration** folgende Variablen anlegen: + +| Variable | Typ | Standardwert | Beschreibung | +|----------|-----|-------------|-------------| +| `busylight_url` | String | `http://100.95.224.14:8081` | URL des Busylight Webhook-Servers | + +### Schritt 3: Trigger konfigurieren + +1. **Trigger hinzufügen**: `Anruf-Trigger` (Call Trigger) +2. **Trigger-Typ**: `Bei jedem Anruf` oder `Call State Changed` +3. **Richtung**: Eingehend + Ausgehend (beide) + +### Schritt 4: Funktionsablauf erstellen + +Der Ablauf hat zwei Zweige: + +#### Zweig A: Anruf beginnt (callstart) + +1. **Bedingung**: Anrufstatus = `CONNECTED` (Anruf angenommen) +2. **Aktion**: HTTP Request + - **Methode**: GET + - **URL**: `{busylight_url}/{called_number}/callstart` + - `{called_number}` = Die Durchwahl des angerufenen Benutzers + +#### Zweig B: Anruf endet (callend) + +1. **Bedingung**: Anrufstatus = `HANGUP` (Anruf beendet) +2. **Aktion**: HTTP Request + - **Methode**: GET + - **URL**: `{busylight_url}/{called_number}/callend` + +### Schritt 5: Variablen-Mapping + +Die Starface-Variablen müssen auf die URL gemappt werden: + +| Starface-Variable | Beschreibung | Verwendung | +|-------------------|-------------|-----------| +| `${call.calledNumber}` | Durchwahl des Angerufenen | In URL als Durchwahl | +| `${call.callingNumber}` | Nummer des Anrufers | Optional für Logging | +| `${call.state}` | Aktueller Anrufstatus | Für Bedingung | + +**Hinweis:** Die genauen Variablennamen können je nach Starface-Version variieren. +Im Modulcreator werden die verfügbaren Variablen als Dropdown angeboten. + +### Schritt 6: Modul speichern und aktivieren + +1. **Speichern** klicken +2. **Modul exportieren** als `.sfm` Datei (für Backup) +3. Unter **Module** → **Modulinstanzen** eine neue Instanz anlegen +4. `busylight_url` auf die IP des Busylight-Servers setzen: `http://100.95.224.14:8081` +5. **Aktivieren** + +## Testen + +### Von der Kommandozeile testen + +```bash +# Anruf simulieren (Durchwahl 222 = Nicklas Janzen) +curl http://100.95.224.14:8081/222/callstart +# → Türschild sollte rot werden + +# Anruf beenden +curl http://100.95.224.14:8081/222/callend +# → Türschild sollte auf Zeiterfassungs-Status zurückspringen +``` + +### Im Busylight-Portal prüfen + +- **Dashboard**: Telefon-Badge sollte "Telefoniert" anzeigen +- **Protokoll**: Einträge mit `phone_active` und `phone_end` sollten erscheinen + +## Alternative: Starface Rufnummernaktionen + +Falls kein Modulcreator verfügbar ist, können auch **Rufnummernaktionen** verwendet werden: + +1. **Admin** → **Rufnummern** → Durchwahl auswählen +2. **Aktionen** → **Neue Aktion** +3. **Bei Anrufbeginn**: HTTP Request an `http://BUSYLIGHT:8081/{durchwahl}/callstart` +4. **Bei Anrufende**: HTTP Request an `http://BUSYLIGHT:8081/{durchwahl}/callend` + +**Nachteil:** Muss pro Durchwahl einzeln eingerichtet werden. + +## Fehlerbehebung + +### Türschild reagiert nicht + +1. Busylight-Server erreichbar? `curl http://100.95.224.14:8081/` +2. Durchwahl im Busylight-Portal beim Benutzer eingetragen? +3. Benutzer laut Zeiterfassung "anwesend" oder "homeoffice"? +4. Starface-Modul aktiviert? +5. Firewall: Port 8081 von der Starface zum Busylight-Server offen? + +### Falscher Benutzer wird rot + +- Prüfen ob die Durchwahl im Busylight-Portal dem richtigen Benutzer zugeordnet ist +- Variable im Modulcreator: `${call.calledNumber}` (nicht `${call.callingNumber}`) + +### Türschild bleibt nach Anrufende rot + +- Prüfen ob das HANGUP-Event im Modul konfiguriert ist +- Im Busylight-Protokoll prüfen ob `callend` ankommt +- Manuell zurücksetzen: `curl http://100.95.224.14:8081/{durchwahl}/callend` diff --git a/docs/test-starface.sh b/docs/test-starface.sh new file mode 100644 index 0000000..da5c607 --- /dev/null +++ b/docs/test-starface.sh @@ -0,0 +1,36 @@ +#!/bin/bash +# Test-Script für Starface Busylight Webhook-Integration +# Simuliert Anruf-Events für alle konfigurierten Durchwahlen + +BUSYLIGHT="http://100.95.224.14:8081" + +echo "=== Busylight Starface Webhook Test ===" +echo "" + +# API Info prüfen +echo "1. Busylight API erreichbar?" +curl -s "$BUSYLIGHT/" | head -3 +echo "" + +# Durchwahl zum Testen (anpassen!) +DW="${1:-222}" +echo "2. Test mit Durchwahl: $DW" +echo "" + +echo " → Sende callstart..." +RESULT=$(curl -s "$BUSYLIGHT/$DW/callstart") +echo " ← $RESULT" +echo "" + +echo " Warte 5 Sekunden (Türschild sollte jetzt ROT sein)..." +sleep 5 + +echo " → Sende callend..." +RESULT=$(curl -s "$BUSYLIGHT/$DW/callend") +echo " ← $RESULT" +echo "" + +echo "3. Fertig! Türschild sollte jetzt zurück auf Zeiterfassungs-Status sein." +echo "" +echo "Verwendung: $0 [durchwahl]" +echo "Beispiel: $0 210 (Test mit Durchwahl 210)"