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 them in the system settings of a white-label instance: one configuration per instance, and none 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

There are two ways to supply a tool, and each instance uses one of them.

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

A fixed iFrame URL

The URL must be served over HTTPS, and your web server must send headers that let a browser display it inside our page.

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). A fixed iFrame cannot tell whether the viewer is a moderator.
• If your URL already contains a ?, the parameters are appended with &, so a URL with its own query string keeps working.

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

An API endpoint

An API endpoint decides which tools each participant sees, and it can return up to five.

When someone joins, we call your endpoint and show them whatever it returns.

The request

We send an HTTP GET with 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, it carries no valid token, so validate the value itself instead of relying on the parameter being present. 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: unlike the REST API, nothing here 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. Anything beyond the fifth in your array 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.