Custom tools

Overview

Custom tools put your own interface inside the meeting room, alongside video, documents, and the whiteboard. A tool is an icon, a label, and one of your pages displayed in an iFrame.

You configure custom tools in the system settings of a white-label instance. There is one configuration per instance, and no configuration by default.

Using this page with an AI assistant

If you are using an AI coding assistant, copy the text below into it and add a sentence describing what you want to build. AI assistants accessing this page receive a separate, token-optimized version of our full developer documentation, specifically tailored by our engineers for AI coding assistants.

Before writing any code, read this page:
https://www.veeting.com/en/developer-documentation/custom-tools

It documents custom tools in the Veeting Rooms meeting room.
Keep these five rules in mind:

1. An API endpoint must return a BARE JSON array of tools, not an
   object with a data property.
2. meetingId is the 24-character ID and meetingToken is the dashed
   number. Do not swap them.
3. A fixed iFrame URL receives culture but never moderatorToken. An
   API endpoint receives moderatorToken but never culture.
4. moderatorToken is always appended to the API call, so its presence
   proves nothing. Validate the value itself.
5. At most five tools are shown, and a tool without an iFrameUrl is
   skipped.

What I want to build:

Choosing a source

You supply a tool in one of two ways, and each instance uses one of them.

Whichever you choose, custom tools must be enabled for the instance before anything appears.

A fixed iFrame URL

Serve the URL over HTTPS. Your web server must also send headers that let a browser display your page inside ours.

The label

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

What we append to your URL

We add query parameters so your page knows who is looking at it:

Two things to know:

• moderatorToken is not sent here. It is only sent to an API endpoint (see below). With a fixed iFrame URL you cannot tell whether the viewer is a moderator.
• If your URL already contains a ?, we append the parameters with &, so a URL with its own query string keeps working.

Values are URL-encoded, so decode them before you use them. A participant name containing a space or an ampersand arrives intact.

An API endpoint

With an API endpoint you decide per participant which tools appear, and you can return up to five.

When someone joins, we call your endpoint and show that person the tools it returns.

The request

We send an HTTP GET with these query parameters, and your configured secret in an X-API-KEY header:

Note: culture is not sent to an API endpoint, and moderatorToken is always appended. For a participant who is not a moderator, the parameter is still present but holds no valid token, so validate the value itself rather than relying on the parameter being present. All values are URL-encoded.

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, */*'

The response

Respond with HTTP 200 and a bare JSON array of tool objects. Do not wrap it in an envelope: this is not the REST API, and nothing unwraps a data property for you.

A label object:

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

Limits and fallbacks

• At most five tools. We stop after the fifth usable tool; anything after that is ignored.
• A tool with no iFrameUrl is skipped entirely.
• If labels is empty or missing, the tool is labeled "Custom tool".
• If the meeting room cannot match the participant's locale, it uses the first label in your array. Put your preferred default first.
• If your endpoint errors, times out, or returns something that is not an array, no custom tools are shown. The meeting continues normally.

Common mistakes

• Swapping meetingId and meetingToken. meetingId is the 24-character one; meetingToken is the dashed one.
• Expecting moderatorToken on a fixed iFrame URL, where it is never sent.
• Expecting culture at an API endpoint, where it is never sent.
• Treating the presence of moderatorToken as proof the participant is a moderator.
• Wrapping the API response in an envelope instead of returning a bare array.
• Returning more than five tools and wondering where the rest went.
• Serving the tool over HTTP or with headers that forbid framing.
• Reading a participant name straight from the query string without decoding it.