Custom tools

Overview

Custom tools allow integrators and developers to create custom tools within the meeting room. These tools consist of a label and an iFrame URL.

Configuration

Custom tools are configured in the system settings of a white label instance. A white label instance can only have one custom tool configuration. By default, no custom tool is configured.

Custom tools can either be configured as a static iFrame URL or through an API endpoint.

iFrame URL

A static iFrame tool configuration consists of the iFrame URL and the tool label:

Custom tools iFrame configuration

The iFrame must be served with HTTPS. Furthermore, the webserver must send the correct CORS headers to allow the browser to display the iFrame within the meeting room.

The label is either a fixed string or a pipe-separated string of translations. Examples:

LabelExplanation
My Custom ToolThe label shown in the interface will always read “My Custom Tool”, independent of the user interface language of the web meeting.
en:My Custom Tool|de-CH:Mein eigenes Tool|fr: Mon outil personnaliséA user interface in English will show “My Custom Tool”, the user interface in German will show “Mein eigenes Tool”, etc. A user interface in Spanish (a language not defined in the label configuration) will either show “My Custom Tool” if an English label is available, or the label first defined in the list.

The iFrame will be embedded in the meeting room with additional query parameters to allow the developers to customize the iFrame depending on these additional query parameters. The query parameters added to the iFrame URL are the following:

Query parameter nameExplanation
participantIdThe unique ID of the meeting participant
participantNameThe name of the participant
meetingTokenThe meeting ID in the form of “0000-0000-0000-0000”
meetingIdThe meeting ID in the form of “5349b4ddd2781d08c09890f3”
moderatorTokenOptional, only if available for this specific user.
cultureThe locale code of the participant at the time when the participant enters the meeting room, for example “en” or “en-US” or “de-DE”, etc.

API

The API definition of the custom tool allows for more flexibility on the developer’s side. The developer can decide for each participant if a tool should be displayed or not, and which tool should be displayed. It is even possible to define multiple separate tools (up to 5).

The API tool needs to be configured in the system settings of a white label instance:

Custom tools API configuration

Once configured the web meeting server API will call this end point for each participant who joins the meeting to retrieve the list of tools which should be displayed to this specific participant.

The workflow is summaries as shown below:

Custom tools API workflow

The API request initiated by the web meeting server is an HTTP GET request with the following query parameters:

Query parameter nameExplanation
participantIdThe unique ID of the meeting participant
participantNameThe name of the participant
meetingTokenThe meeting ID in the form of “0000-0000-0000-0000”
meetingIdThe meeting ID in the form of “5349b4ddd2781d08c09890f3”
moderatorTokenOptional, only if available for this specific user.

The API secret defined in the system configuration will be sent as an HTTP header “X-API-KEY”.

The API request expects an HTTP 200 response code and a JSON Array object consisting of a list of tool objects. A tool object is defined as:

Property nameExplanation
iFrameUrlAn URL of an iFrame to be displayed
toolIconSVG string
labelsAn array of “label” objects

Whereas a label object is defined as

Property nameExplanation
cultureThe locale of the label, for example “en” or “en-US” or “de-DE”, etc
labelString, the label displayed, e.g. “My Custom Tool”

Example request:

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

Example response:

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

Not sure how to best implement your project?

Contact our team to talk through the details.