christian/busylight_modular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
busylight_modular/docs/starface-modul-anleitung.md

9.8 KiB
Raw Blame History

Starface Modul – Busylight Webhook (Neuaufbau)

Übersicht

Dieses Modul sendet bei jedem Anruf-Event einen HTTP-Request an den Busylight-Server. Damit zeigen die Türschilder automatisch den Telefonstatus an.

Ablauf: Anruf startet → Starface → HTTP GET → Busylight-Server → WLED wird rot Ablauf: Anruf endet → Starface → HTTP GET → Busylight-Server → WLED zurück auf Normal

Voraussetzungen

  • Starface mit Modulcreator-Lizenz
  • Busylight-Server erreichbar unter http://100.95.224.14:8081
  • Durchwahlen im Busylight-Portal bei den Benutzern eingetragen

Neues Modul erstellen

Schritt 1: Modul anlegen

  1. Starface Admin → Module → Modulcreator
  2. Neues Modul erstellen
  3. Tab Module Settings:
    • Name: Busylight Webhook
    • Version: 1
    • Vendor: cynfo GmbH

Schritt 2: GUI-Tab – Einstellungen definieren

  1. Tab GUI öffnen
  2. Ein neues Textfeld anlegen:
    • Variable-Name: GUI_WEBHOOK_URL
    • Typ: String
    • Standardwert: http://100.95.224.14:8081
    • Label/Beschreibung: Busylight Webhook URL

Das ist die einzige Einstellung die der Admin später pro Instanz konfiguriert.

Schritt 3: Funktion "CallWebhook" erstellen

Diese Funktion baut die URL zusammen und sendet den HTTP-Request.

  1. Tab Development
  2. Links unter Functions auf + klicken → Name: CallWebhook
  3. Function Settings klicken → Input-Variablen anlegen:
Name Typ Beschreibung
loginId String Durchwahl des Benutzers
action String callstart oder callend

  1. Zurück zu Edit wechseln

  2. Folgende 4 Bausteine nacheinander aus der Components-Sidebar (rechts) in den Edit-Bereich ziehen:

Baustein 1: Append (URL zusammenbauen)

Wo: Components → String → Append

In den Edit-Bereich ziehen. Dann konfigurieren:

  • Input "Strings" (Klick auf das Feld, dann mehrere Werte hinzufügen):
Nr Wert By Reference
1 GUI_WEBHOOK_URL ✅ Ja (Referenz auf die Modul-Variable)
2 / ❌ Nein (fester Text)
3 loginId ✅ Ja (Referenz auf Input-Variable)
4 / ❌ Nein (fester Text)
5 action ✅ Ja (Referenz auf Input-Variable)
  • Output "result" → wird automatisch erzeugt, z.B. http://100.95.224.14:8081/222/callstart

Baustein 2: CreateHttpUrlWithParams (URL-Objekt erstellen)

Wo: Components → Net.HTTP → CreateHttpUrlWithParams

In den Edit-Bereich ziehen (unter den Append). Konfigurieren:

  • Input "url": result → ✅ By Reference (Output vom Append-Baustein)
  • Alle anderen Inputs leer lassen (keine Query-Parameter nötig)
  • Output "httpUrl" → wird automatisch erzeugt

Baustein 3: HttpRequest (HTTP-Request absenden)

Wo: Components → Net.HTTP → HttpRequest

In den Edit-Bereich ziehen (unter CreateHttpUrlWithParams). Konfigurieren:

  • Input "httpUrl": httpUrl → ✅ By Reference (Output von CreateHttpUrlWithParams)
  • Input "method": GET → ❌ Fester Text
  • Alle anderen Inputs (body, headers, timeout) leer lassen
  • Output brauchen wir nicht

Baustein 4: Log (zum Debuggen)

Wo: Components → System → Log

In den Edit-Bereich ziehen (unter HttpRequest). Konfigurieren:

  • Input "Log level": INFO (fester Text)
  • Input "Message" (mehrere Werte):
Nr Wert By Reference
1 Busylight: ❌ Nein (fester Text)
2 result ✅ Ja (die URL die aufgerufen wurde)

Die fertige CallWebhook-Funktion sieht im Editor so aus:

Append([GUI_WEBHOOK_URL, "/", loginId, "/", action]) → result
CreateHttpUrlWithParams(result) → httpUrl
HttpRequest(httpUrl, "GET")
Log("INFO", ["Busylight: ", result])

Schritt 4: Funktion "Call" erstellen

Diese Funktion wird bei jedem Anruf-Event aufgerufen. Sie ermittelt die Durchwahl und ruft je nach Status CallWebhook mit callstart oder callend auf.

  1. Links unter Functions auf + klicken → Name: Call
  2. Function Settings → Input-Variablen anlegen:
Name Typ Beschreibung
UCI_CALL UCI_CALL By Reference ✅ – Das Anruf-Objekt
USER_ACCOUNT STARFACE_USER By Reference ✅ – Der betroffene User
  1. Zurück zu Edit und folgende Bausteine einfügen:

Baustein 1: Call.getCallInformations

Wo: Components → Call → Call.getCallInformations

  • Input "call": UCI_CALL → ✅ By Reference
  • Outputs die wir brauchen:
    • uciCallState (String) – Der Anruf-Status
    • uciCalledNumber (String) – Die angerufene Nummer

Baustein 2: ResolveUserData (Benutzerdaten holen)

Wo: Components → STARFACE → ResolveUserData

  • Input "accountId": USER_ACCOUNT → ✅ By Reference
  • Output den wir brauchen:
    • loginId (String) – Die Login-ID / Durchwahl des Users

Baustein 3: IsUser (Prüfen ob es ein echter User ist)

Wo: Components → STARFACE → IsUser

  • Input "accountId": USER_ACCOUNT → ✅ By Reference
  • Output: isUser (Boolean)

Baustein 4: if(!isUser) → exit

Wenn es kein User ist (z.B. eine Gruppe oder Queue), abbrechen.

Wo: Components → Basic Components → if

  • Bedingung: isUser → is not true (isNotTrueExpression)
  • Innerhalb des if: exit einfügen (Components → Basic Components → exit)

Baustein 5: switch(uciCallState) – Status-Weiche

Wo: Components → Basic Components → switch

  • Variable: uciCallState → ✅ By Reference

Dann 3 case-Blöcke hinzufügen (Components → Basic Components → case):

case 'INCOMING'
  • Condition: INCOMING (fester Text)
  • Innerhalb: CallWebhook aufrufen
    • Wo: Links unter Functions → CallWebhook in den case ziehen
    • loginId = loginId → ✅ By Reference (Output von ResolveUserData)
    • action = callstart → ❌ Fester Text
case 'OUTGOING'
  • Condition: OUTGOING (fester Text)
  • Innerhalb: CallWebhook aufrufen
    • loginId = loginId → ✅ By Reference
    • action = callstart → ❌ Fester Text
case 'HANGUP'
  • Condition: HANGUP (fester Text)
  • Innerhalb: CallWebhook aufrufen
    • loginId = loginId → ✅ By Reference
    • action = callend → ❌ Fester Text

Die fertige Call-Funktion sieht im Editor so aus:

Call.getCallInformations(UCI_CALL) → uciCallState, uciCalledNumber, ...
ResolveUserData(USER_ACCOUNT) → loginId, firstName, familyName, ...
IsUser(USER_ACCOUNT) → isUser

if(!isUser)
  exit

switch(uciCallState)
  case 'INCOMING':
    CallWebhook(loginId, "callstart")
  case 'OUTGOING':
    CallWebhook(loginId, "callstart")
  case 'HANGUP':
    CallWebhook(loginId, "callend")

Schritt 5: Funktion "Register" erstellen

Diese Funktion registriert den Call-Event-Listener wenn das Modul aktiviert wird.

  1. Links unter Functions auf + klicken → Name: Register
  2. Einen Baustein einfügen:

Wo: Components → Call → RegisterCallEventByUser (oder ähnlich)

  • Dieser registriert die Call-Funktion als Handler für alle Anruf-Events
  • Target-Funktion: Call

Hinweis: Der genaue Baustein heißt je nach Starface-Version anders. Im alten Modul steht er unter "Register" und verweist auf die "Call"-Funktion.

Schritt 6: Funktion "Unregister" erstellen

  1. Links unter Functions auf + klicken → Name: Unregister
  2. Einen Baustein einfügen der den Event-Listener wieder abmeldet

Schritt 7: Entry Points setzen

  1. Tab Module Settings (oder unten im Development-Tab)
  2. Entry Points / Lifecycle Events konfigurieren:
    • InstanceActivated → Funktion Register aufrufen
    • InstanceDeactivated → Funktion Unregister aufrufen

Schritt 8: Speichern und Installieren

  1. Save klicken
  2. Apply klicken
  3. Modul als .sfm exportieren (für Backup)
  4. Unter Module → Modulinstanzen → Neue Instanz anlegen
  5. GUI_WEBHOOK_URL = http://100.95.224.14:8081
  6. Aktivieren

Testen

Schnelltest von der Kommandozeile

# Anruf simulieren (Durchwahl 222)
curl http://100.95.224.14:8081/222/callstart
# → Dashboard zeigt "Telefoniert" bei Nicklas Janzen

# Anruf beenden
curl http://100.95.224.14:8081/222/callend
# → Dashboard zeigt normalen Status

Im Starface Modulcreator

  • Tab Log File öffnen
  • Bei einem Testanruf sollte erscheinen: 
    INFO: Busylight: http://100.95.224.14:8081/222/callstart

Im Busylight-Portal

  • Dashboard: Telefon-Badge wechselt auf "Telefoniert" (rot)
  • Protokoll: Einträge mit phone_active und phone_end

Zusammenfassung – Alle Funktionen

Funktion Zweck Bausteine
CallWebhook URL bauen + HTTP GET senden Append → CreateHttpUrlWithParams → HttpRequest → Log
Call Anruf-Event verarbeiten getCallInformations → ResolveUserData → IsUser → if/exit → switch/case → CallWebhook
Register Event-Listener anmelden RegisterCallEventByUser
Unregister Event-Listener abmelden UnregisterCallEventByUser

Fehlerbehebung

Webhook kommt nicht an

  1. Starface Log File prüfen – steht die URL drin?
  2. Firewall: Port 8081 vom Starface-Server (192.168.200.251) zum Busylight-Server (100.95.224.14) offen?
  3. Test: curl http://100.95.224.14:8081/ vom Starface-Server

Falscher User wird rot

  • loginId = Starface Login-ID = Durchwahl (z.B. 222)
  • Diese muss im Busylight-Portal unter Benutzer → Durchwahl eingetragen sein

Türschild bleibt rot

  • HANGUP-case prüfen – wird callend gesendet?
  • Manuell zurücksetzen: curl http://100.95.224.14:8081/222/callend
  • Im Busylight-Protokoll prüfen ob phone_end ankommt