Raumsystem–Steuerung

Übersicht

Mit der Raumsystem-Steuerung bedient ein Panel im physischen Meetingraum ein laufendes Meeting. Das Panel kann ein Wandpanel, ein Q-SYS- oder Crestron-Prozessor sein oder jedes andere Gerät, das HTTPS-Anfragen senden kann. Über HTTPS-Anfragen steuert das Panel, was auf den Bildschirmen im Raum zu sehen ist und wie und wann das Meeting beendet wird. Es sind dieselben Aktionen, die ein Moderator in der Browserapplikation auch manuell ausführen kann. Mit den folgenden Kommandos bedienen Sie einen Raum über ein Panel statt über den Browser.

Basis-URL: https://<DOMAIN-NAME>/api/v6

<DOMAIN-NAME> ist Ihre eigene Web-Meeting-Domain. Verwenden Sie die Domain, unter der Ihre Instanz läuft.

Content-Type: application/json bei jedem POST.

Die Raumsystem-API besteht aus einem Endpunkt für Kommandos und einem für den Zustand. Sie senden ein Kommando und jede Antwort enthält den Zustand des Meetings nach dem Kommando. Mit den Zustands-APIs können Sie jederzeit den aktuellen Stand abrufen und so zum Beispiel die Tasten auf dem Panel beleuchten.

Mit den Raumsystem-Kommandos können Sie kein Meeting starten. Nutzen Sie dafür die normalen REST-APIs.

Verwendung mit einem KI-Assistenten

Wenn Sie mit einem KI-Coding-Assistenten arbeiten, können Sie den folgenden Text in Ihren Assistenten kopieren und mit einem Satz ergänzen, der beschreibt, was Sie programmieren möchten.

Der Prompt verweist auf unsere Entwicklerdokumentation, die wir für Coding-Assistenten in einer separaten, token-optimierten KI-Version ausliefern.

Lies zuerst diese Seite, bevor Du Code schreibst:
https://www.veeting.com/de/developer-documentation/room-system-control

Sie dokumentiert die Raumsystem-Steuerung von Veeting Rooms. Halte
Dich an diese sechs Regeln:

1. Frag mich nach meiner Veeting-Domain und meinen Zugangsdaten,
   bevor Du Code schreibst, sofern ich sie Dir nicht schon gegeben
   habe. Rate weder das eine noch das andere.
2. Ein Aufruf war nur dann erfolgreich, wenn der HTTP-Status 200
   ist UND der Body responseCode 0 enthält. Prüfe beides. Ein 402
   ist eine Ablehnung und kein Serverfehler; ein erneuter Versuch
   hilft nicht.
3. Nimm in der URL die 24 Zeichen lange «id» des Meetings, nie den
   Meeting-Token mit den Bindestrichen aus dem Meeting-Link.
4. Kommandos wirken nur, solange das Meeting läuft. Es gibt kein
   Kommando, das eines startet.
5. presentation.nextSlide und presentation.previousSlide brauchen
   eine Präsentation, die jemand im Meeting bereits geöffnet hat.
6. Kommandonamen und Tool-IDs sind Identifier. Übersetze sie nie
   und erfinde keine. Nimm nur die Werte von dieser Seite.

Was ich bauen möchte:

Funktion aktivieren

Die Raumsystem-Steuerung ist standardmässig ausgeschaltet. Ein White-Label-Administrator schaltet sie in den Systemeinstellungen unter «Raumsystemfunktionen aktivieren» ein. Solange die Einstellung aus ist, antworten die nachfolgenden Endpunkte mit 402.

Authentifizierung

Sie haben drei Möglichkeiten, sich zu authentifizieren. Die Methoden unterscheiden sich darin, welche Meetings sie erreichen.

Für ein Raumsystem ist ein API-Key der Normalfall. Einen Key auf Kontoebene erstellen Sie in den «Kontoeinstellungen». Er ist auf die Meeting-Endpunkte beschränkt und lässt sich darum bedenkenlos in einem Raum hinterlegen. Ein Key auf Instanzebene erreicht jedes Konto und gehört nie in Kundenhand. Wie Keys ausgestellt werden und wie sie im Namen eines Users handeln, steht unter API-Nutzung.

Ein Moderatoren-Token wird für jedes einzelne Meeting neu erstellt und ist nur für dieses spezifische Meeting gültig. Mit einem Moderatoren-Token muss das Raumsystem über die /moderator/-Varianten der beiden Routen angesprochen werden. Schicken Sie ihn als Header statt in der URL, damit er nicht in Proxy- und Browser-Logs landet.

Endpunkte

<MEETING-ID> ist die 24 Zeichen lange id des Meetings, also der Wert, den die Meeting-API beim Anlegen zurückgibt, zum Beispiel 6a9e7e89813a920f5679188f. Es ist nicht die meetingId mit den Bindestrichen aus dem Meeting-Link.

Der Request-Body eines Kommandos ist in beiden Varianten (API-Key und Moderatoren-Token) derselbe:

{
  "command": "tool.activate",
  "parameters": {
    "toolId": "vr-whiteboard"
  }
}

Lassen Sie parameters weg, wenn ein Kommando keine braucht. Alle vier Routen liefern das Zustandsobjekt, das weiter unten beschrieben ist.

Kommandos

Parameter

Hinweise, die Ihnen Zeit sparen

Ihr Panel muss nicht mitzählen. presentation.nextSlide und presentation.previousSlide bezieht die Plattform auf die Seite, auf der das Meeting gerade steht. Ein Panel muss also nicht mitzählen. Wenn Sie die Seitenzahl anzeigen möchten, lesen Sie presentation.currentPage aus dem Zustand.

Zuerst muss eine Präsentation offen sein. Um die Präsentation zu steuern, muss jemand im Meeting sie zuvor geöffnet haben. Ohne ein solches Dokument antworten die APIs mit 402.

Tool-Identifier

toolId akzeptiert diese Werte und keine anderen. Es sind Identifier, keine Beschriftungen, und sie lauten in jeder Oberflächensprache gleich.

• vr-agenda
• vr-assistant
• vr-chat
• vr-dialin-numbers
• vr-documents
• vr-lobby-management
• vr-minutes
• vr-notes
• vr-participants
• vr-polls
• vr-screensharing
• vr-settings
• vr-tv-channel-manager
• vr-video
• vr-webinar-configuration
• vr-webinar-questions
• vr-whiteboard

Custom Tools heissen vr-custom-tool-0 bis vr-custom-tool-5. Wie Sie Custom Tools einrichten, steht unter Widgets im Meetingraum.

Welche Tools ein Teilnehmer überhaupt sieht, ist eine andere Frage. Das entscheiden die Meeting-Berechtigungen des Kontos. Aktivieren Sie ein Tool, das ein Teilnehmer nicht nutzen darf, bekommt er es auch nicht zu sehen.

Das Zustandsobjekt

Beide Zustandsendpunkte und jedes Kommando liefern dieses Objekt.

Jeder Teilnehmer enthält participantId, name, isModerator und handRaised, dazu tvChannel, sofern er einem TV-Kanal zugewiesen ist.

Statuscodes und Fehler

Jede Antwort verwendet denselben Wrapper wie die REST API: { "responseCode": 0, "responseMessage": "", "data": { ... } }.

Beispiele

Das Whiteboard auf alle Bildschirme legen:

curl -X POST "https://<DOMAIN-NAME>/api/v6/meeting-room/<MEETING-ID>/room-system/commands" \
  -H "X-API-KEY: <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{"command":"tool.activate","parameters":{"toolId":"vr-whiteboard"}}'

Eine Seite weiterblättern:

curl -X POST "https://<DOMAIN-NAME>/api/v6/meeting-room/<MEETING-ID>/room-system/commands" \
  -H "X-API-KEY: <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{"command":"presentation.nextSlide"}'

Den Zustand lesen, mit einem Moderatoren-Token statt eines Keys:

curl "https://<DOMAIN-NAME>/api/v6/meeting-room/<MEETING-ID>/room-system/moderator/state" \
  -H "X-MODERATOR-TOKEN: <MODERATOR-TOKEN>"

Eine erfolgreiche Antwort:

{
  "responseCode": 0,
  "responseMessage": "",
  "data": {
    "activeToolId": "vr-documents",
    "presentation": { "documentId": "6710a2b4c81e4a6c8b0d2f4a", "currentPage": 7 },
    "presentationModeActive": true,
    "waitingRoomActive": false,
    "followMeActive": false,
    "recordingState": "stopped",
    "participants": [
      { "participantId": "a1b2c3", "name": "Anna Meier", "isModerator": true, "handRaised": false, "tvChannel": 1 }
    ]
  }
}

Anbindung an ein Panel

Ein Panel braucht in der Regel zweierlei: eine Taste, die ein Kommando schickt, und eine Lampe, die zeigt, was im Raum läuft.

Für die Taste schicken Sie das Kommando und prüfen, ob der HTTP-Status 200 und responseCode 0 ist. Für die Lampe fragen Sie den Zustandsendpunkt regelmässig ab. Da jedes Kommando ebenfalls mit dem Zustand antwortet, können Sie den Zustand auch aus der API-Antwort übernehmen.

Legen Sie den API-Key in die Konfiguration des Panels und nicht in das Skript der einzelnen Taste. Dann müssen Sie beim Wechsel eines Keys nicht jede Taste anfassen.

Weitere nützliche Steuerungsmöglichkeiten

Mit den Query-Parametern können Sie zum Beispiel festlegen, ob der angesprochene Browser Audio überhaupt empfangen soll. Das ist vor allem im TV-Modus interessant.

Gerade wenn Sie verschiedene Bildschirme über denselben Rechner steuern und die Browserinstanzen deshalb im Kioskmodus öffnen, möchten Sie sicherstellen, dass es im Raum kein Echo gibt. Deshalb ist es sinnvoll, z.B. nur in einer Browserinstanz Audio zu empfangen.

Häufige Fehler

• Den Meeting-Token mit Bindestrichen aus dem Meeting-Link nehmen und nicht die 24 Zeichen lange id.
• Nur den HTTP-Status prüfen oder nur responseCode. Prüfen Sie beides.
• Ein Kommando an ein Meeting schicken, das noch nicht begonnen hat. Es wird nichts in eine Queue gelegt.
• presentation.nextSlide aufrufen, bevor jemand ein Dokument geöffnet hat.
• Den Moderatoren-Token an die Routen ohne /moderator/ im Pfad schicken, wo er ignoriert wird.
• Eine Tool-ID erfinden oder übersetzen. Die Identifier sind in jeder Sprache englisch.
• Die Funktion auf der Instanz ausgeschaltet lassen und den 402 als kaputten Key deuten.