Custom Tools – eigene Widgets im Meetingraum

Übersicht

Mit Custom Tools bringen Sie Ihre eigene Oberfläche in den Meetingraum, gleichberechtigt neben Video, Dokumenten und Whiteboard. Ein Tool besteht aus einem Icon, einem Label und einer Ihrer Seiten, die der Raum in einem iFrame darstellt.

Sie konfigurieren die Tools in den Systemeinstellungen einer White-Label-Instanz. Pro Instanz gibt es genau eine Konfiguration, standardmässig ist keine hinterlegt.

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/custom-tools

Sie dokumentiert Custom Tools im Meetingraum von Veeting Rooms.
Halte Dich an diese fünf Regeln:

1. Ein API-Endpunkt muss ein REINES JSON-Array von Tools
   zurückgeben, kein Objekt mit einer data-Eigenschaft.
2. meetingId ist die 24 Zeichen lange ID, meetingToken die Nummer mit
   den Bindestrichen. Vertausche die beiden nicht.
3. Die Anfrage an einen API-Endpunkt enthält moderatorToken, aber
   nie culture. Jede iFrame-URL, fest oder vom Endpunkt geliefert,
   erhält culture angehängt, aber nie moderatorToken.
4. moderatorToken hängen wir immer an den API-Aufruf an, sein
   Vorhandensein beweist also nichts. Prüfe den Wert selbst.
5. Der Raum zeigt höchstens fünf Tools an, und ein Tool ohne
   iFrameUrl überspringt er.

Was ich bauen möchte:

Die Quelle wählen

Sie stellen ein Tool auf zwei Wegen bereit. Eine Instanz nutzt jeweils einen davon.

Wie Sie sich auch entscheiden: Custom Tools müssen für die Instanz aktiviert sein, sonst erscheint nichts.

Eine feste iFrame-URL

Liefern Sie die URL über HTTPS aus. Ihr Webserver muss zudem Header senden, die dem Browser erlauben, Ihre Seite innerhalb unserer Seite darzustellen.

Das Label

Sie geben entweder einen festen String an oder eine Liste von Übersetzungen, mit Pipes (|) getrennt.

Was wir an Ihre URL anhängen

Wir ergänzen Query-Parameter, damit Ihre Seite weiss, wer sie betrachtet. Das gilt für eine feste URL und für die iFrameUrl jedes Tools, das ein API-Endpunkt zurückgibt:

Drei Dinge sollten Sie wissen:

• Wechselt der Teilnehmer die Sprache des Raums, laden wir den iFrame des Tools mit dem neuen culture neu.
• moderatorToken senden wir hier nicht. Den erhält nur ein API-Endpunkt, siehe unten. Mit einer festen iFrame-URL erkennen Sie deshalb nicht, ob der Betrachter Moderator ist.
• Enthält Ihre URL bereits ein ?, hängen wir die Parameter mit & an. Eine URL mit eigenem Query-String funktioniert also weiterhin.

Die Werte sind URL-codiert. Decodieren Sie sie also, bevor Sie damit arbeiten. Ein Name mit einem Leerzeichen oder einem & kommt so unversehrt bei Ihnen an.

Ein API-Endpunkt

Mit einem API-Endpunkt entscheiden Sie pro Teilnehmer, welche Tools erscheinen. Bis zu fünf dürfen es sein.

Tritt jemand bei, rufen wir Ihren Endpunkt auf und zeigen dieser Person an, was Ihr Endpunkt zurückgibt.

Der Aufruf

Wir schicken ein HTTP GET mit diesen Query-Parametern und legen Ihr konfiguriertes Geheimnis in den Header X-API-KEY:

Hinweis: Die Anfrage an Ihren Endpunkt enthält culture nicht, moderatorToken hängen wir dagegen immer an. Die iFrameUrl jedes Tools, das Sie zurückgeben, erhält culture trotzdem, zusammen mit den übrigen Parametern aus «Was wir an Ihre URL anhängen». Bei einem Teilnehmer ohne Moderationsrechte ist der Parameter zwar vorhanden, enthält aber keinen gültigen Wert. Prüfen Sie deshalb den Wert selbst und nicht, ob der Parameter vorhanden ist. Alle Werte sind URL-codiert.

curl 'https://<CUSTOM-TOOL-API-URL>?participantName=Joe%20Doe\
&participantId=XXXXX\
&meetingId=5349b4ddd2781d08c09890f3\
&meetingToken=0000-0000-0000-0000\
&moderatorToken=YYYYY' \
  -H 'X-API-KEY: <CUSTOM-TOOL-API-KEY>' \
  -H 'accept: application/json, text/plain, */*'

Die Antwort

Antworten Sie mit HTTP 200 und einem reinen JSON-Array von Tool-Objekten. Verpacken Sie es nicht. Anders als bei der REST API entpackt hier niemand eine data-Eigenschaft für Sie.

Ein Label-Objekt:

[
  {
    "iFrameUrl": "https://www.example.com/custom-tool-1",
    "toolIcon": "<svg>...</svg>",
    "labels": [
      {
        "culture": "en-US",
        "label": "Custom tool 1"
      },
      {
        "culture": "de",
        "label": "Spezialtool 1"
      }
    ]
  }
]

Grenzen und Fallbacks

• Höchstens fünf Tools. Wir hören nach dem fünften brauchbaren Tool auf; alles danach ignorieren wir.
• Ein Tool ohne iFrameUrl überspringen wir vollständig.
• Fehlt labels oder ist das Array leer, erhält das Tool das Label «Custom tool».
• Kann der Meetingraum das Locale des Teilnehmers nicht zuordnen, nimmt er das erste Label Ihres Arrays. Setzen Sie Ihren bevorzugten Standard deshalb an den Anfang.
• Antwortet Ihr Endpunkt mit einem Fehler, läuft er in einen Timeout oder gibt er kein Array zurück, zeigen wir keine Custom Tools an. Das Meeting läuft normal weiter.

Häufige Fehler

• meetingId und meetingToken vertauschen. meetingId ist die 24 Zeichen lange, meetingToken die mit den Bindestrichen.
• moderatorToken bei einer festen iFrame-URL erwarten, wo wir ihn nie senden.
• culture in der Anfrage an den API-Endpunkt erwarten. Es wird nur an die iFrame-URL angehängt.
• Das Vorhandensein von moderatorToken als Nachweis für Moderationsrechte werten.
• Die API-Antwort verpacken, statt ein reines Array zurückzugeben.
• Mehr als fünf Tools zurückgeben und sich wundern, wo die übrigen geblieben sind.
• Das Tool über HTTP ausliefern oder mit Headern, die das Einbetten verbieten.
• Einen Teilnehmernamen direkt aus dem Query-String lesen, ohne ihn zu decodieren.