Menu

Mattering Automations Whereby integration

Connect Whereby to Mattering Automations: create and delete meeting rooms, list cloud recordings and mint expiring download links, queue and collect transcriptions, read room, session, and participant insights, and set per room colors and backgrounds as workflow steps, authenticated with one Whereby Embedded API key.

The Mattering Automations Whereby integration adds the Whereby REST API v1 to your automation canvas: create transient meeting rooms and hand back their URLs, list and delete cloud recordings and mint temporary download links for them, queue transcriptions against a recording and collect them when they are ready, read room, session, and participant insights including per participant call quality, and set a single room's colors, in call background, and knock page background.

The credential is a Whereby Embedded API key, sent as an HTTP Bearer token on every request. It is the only authentication the API documents: no OAuth flow, no signed request, and no key query parameter. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.

The safety modeling is stated on the nodes rather than buried. Of the 22 nodes, 12 read and 10 act, and five carry a destructive flag: Whereby: Delete Meeting, Whereby: Delete Recording, Whereby: Delete Transcription, Whereby: Bulk Delete Recordings, and Whereby: Bulk Delete Transcriptions. Two behaviors are worth knowing before the first run. Deleting a meeting tears down the room, so anyone in the call is removed and the URL stops working. And both bulk deletes report success as soon as Whereby accepts a background job, before anything has been removed, with no job id to poll or cancel.

Before you start

  • A Whereby Embedded account, whose API key you generate yourself in the dashboard. Every call in this integration is authenticated, so there is no read-only or anonymous mode to try it with first.
  • An API key from the Whereby Embedded dashboard. One key authenticates all 22 nodes, and it reaches the organization's meetings, recordings, transcriptions, insights, and room theming, so the person connecting Whereby to Mattering should be someone allowed to hold that level of access.
  • Something to point the first workflows at. An empty organization is fine: Whereby: Create Meeting can make the first room, and the verify path below reads cleanly against an account with no meetings yet.
  • A Mattering workspace with access to the Automations app.
  • Not required here: a customer subdomain. Whereby's subdomain appears inside the room URLs the API returns, not in the API host, so there is nothing host-shaped to configure on the credential.

Get your Whereby Embedded API key

Mattering authenticates to Whereby with an API key sent as an HTTP Bearer token: an Authorization header carrying the word Bearer and the key. Whereby's security note states the model plainly, that the token is provided to the client and it is up to the client to keep it secret, and the API documents no alternative: no basic auth, no request signing, no key as a query parameter. There are no scopes to choose, which makes setup short and makes the key powerful, so store it only in systems built to hold secrets.

Sign in to the Whereby Embedded dashboard and open its API key section.
Create an API key and copy it. It is a single string with no client secret alongside it.
This key reaches everything the API covers: meetings, recordings, transcriptions, insights, and room theming, including the deletes. Never share it publicly or commit it to version control. If it leaks, revoke it in the Whereby dashboard and issue a new one, and remember that revoking it breaks every other place the same key is used, including this integration's credential.
The API host is api.whereby.dev even though Whereby's documentation now lives at docs.whereby.com. There is no per-customer API subdomain: the subdomain you see inside a returned room URL is part of that room's address, not an API endpoint, so nothing about it needs entering here.

Connect Whereby to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Whereby from the list.
Click Create new credential, paste the API key as the bearer token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering calls Whereby's meetings list endpoint, which takes no required parameters: a results list, even an empty one, proves the credential, and a 401 saying the access token is missing or invalid means the key is wrong, mistyped, or revoked.
Click Connect. All 22 Whereby nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Whereby section should list the query and action nodes. Drop Whereby: List Meetings onto the canvas and run a test step. It is the integration's natural probe, since it needs no parameters and every valid key can call it. The response is a results list plus an opaque cursor, so meeting ids sit at data.results[].meetingId and the room URLs beside them at data.results[].roomUrl. Copy a meeting id if you have one, because Whereby: Get Meeting and Whereby: Delete Meeting both ask for it.

Next, run Whereby: List Recordings and Whereby: List Transcriptions to see the same envelope on the other two families, and note the ids you will need downstream: data.results[].recordingId, data.results[].transcriptionId, and the data.results[].roomSessionId that both listers carry, which is the value the participant nodes want. Whereby: Get Room Insights is the only node that enumerates room names, though Whereby does not document whether rooms that have never had a session appear in it at all, so do not rely on it to enumerate rooms you have only just created. Everything in this verify path is read-only: it cannot reach the five destructive nodes and it changes nothing, so it is safe to re-run whenever you rotate the key.

Node reference

22 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 12

Whereby: Get Meeting

whereby_get_meeting

Fetch one meeting by id, including its room URL and its start and end dates.

Whereby: Get Participant Session Details

whereby_get_participant_session_details

Call quality detail for one participant in one session: display name, role, user agent, and sampled network series for packet loss and bitrate in both directions, taken at the reported sampleRateMs interval. Returns a bare JSON ARRAY, so paths start data[0], not data.results[].

Whereby: Get Recording

whereby_get_recording

Fetch one recording's metadata by id: filename, size, room session id, and start and end dates.

Whereby: Get Recording Access Link

whereby_get_recording_access_link

Mint a temporary download URL for a recording, plus the millisecond timestamp at which it expires. The link EXPIRES (one hour by default, 12 hours at most), so fetch it when you are about to download and never store it as a permanent address. Available for Whereby hosted recordings only: a recording written to your own S3 bucket is fetched from that bucket instead. Nothing is deleted or changed by this call.

Whereby: Get Room Insights

whereby_get_room_insights

Usage summary per room: participant, recorder and streamer minutes, unique participant counts, session count, and the average rating. Also the only place this API enumerates room names. Read the totals as LIFETIME figures for each room, not as activity inside the requested date range: the createdAt filter selects which ROOMS are returned by when they were created, and a room's totals keep growing for as long as it exists. rating is an average and must never be summed.

Whereby: Get Room Session Insights

whereby_get_room_session_insights

Usage per SESSION of one named room: when the session started and ended, participant, recorder and streamer minutes, unique participant counts, and rating. This is the node that turns a room name into the session ids the participant nodes need.

Whereby: Get Transcription

whereby_get_transcription

Fetch one transcription's metadata by id, including its state, which is what tells you whether the file is ready to download.

Whereby: Get Transcription Access Link

whereby_get_transcription_access_link

Mint a temporary download URL for a transcription file, plus the millisecond timestamp at which it expires. The link EXPIRES (one hour by default, 12 hours at most), so fetch it when you are about to download rather than storing it. Available for Whereby hosted transcriptions only (storageType WHEREBY_HOSTED); a SELF_HOSTED transcription is fetched from your own bucket. Nothing is changed by this call.

Whereby: List Meetings

whereby_list_meetings

List the organization's meetings, newest page first, with an opaque cursor for the next page. Also the connector's auth probe: it needs no parameters and a bad key returns 401.

Whereby: List Recordings

whereby_list_recordings

List cloud recordings with their filename, size, room session id, and start and end dates. This is metadata only: use Whereby: Get Recording Access Link to get a downloadable URL.

Whereby: List Session Participants

whereby_list_session_participants

List the participants of a room session with their display name, role, join and leave times, your own externalId if one was passed on the room URL, and any rating, tags and comment they left. Supply the room session id, or the externalId to trace one of your users across sessions.

Whereby: List Transcriptions

whereby_list_transcriptions

List transcriptions with their room name, state (ready, in_progress or failed), type (LIVE_TRANSCRIPTION from a session, or RECORDING_TRANSCRIPTION generated from a recording), duration and storage type. Metadata only: use Whereby: Get Transcription Access Link for the file.

Action nodes 10

Whereby: Bulk Delete Recordings

whereby_bulk_delete_recordings

Destructive and irreversible: delete many recordings at once. Whereby schedules a background job and returns 204 IMMEDIATELY, before anything has been deleted, so a success here means the job was accepted rather than finished; poll Whereby: List Recordings to see the effect. There is no undo and no job id to cancel. The call is idempotent.

Whereby: Bulk Delete Transcriptions

whereby_bulk_delete_transcriptions

Destructive and irreversible: delete many transcriptions at once. Whereby schedules a background job and returns 204 IMMEDIATELY, before anything has been deleted, so a success here means the job was accepted rather than finished; poll Whereby: List Transcriptions to see the effect. There is no undo and no job id to cancel. The call is idempotent.

Whereby: Create Meeting

whereby_create_meeting

Create a meeting, which mints a transient Whereby room and returns its URL. The room exists from this call until one hour after endDate, then Whereby deletes it automatically. The API takes no attendee list and Whereby documents no invitation or notification for this call, so nothing is sent to anyone: distributing data.roomUrl is the caller's job. Reversible by Whereby: Delete Meeting, which removes the room.

Whereby: Create Transcription

whereby_create_transcription

Queue a transcription of an existing recording. Whereby schedules the job and returns 201 immediately, so the transcription is not ready yet: poll Whereby: List Transcriptions until the row's state is ready (it passes through in_progress, and can end at failed). Reversible by Whereby: Delete Transcription. Nothing is sent to any participant.

Whereby: Delete Meeting

whereby_delete_meeting

Destructive and irreversible: delete a meeting, which tears down its room. Anyone in the room is removed and the room URL stops working; there is no undo and no way to recreate the same URL. The call is idempotent, so deleting an already deleted meeting returns the same 204. Returns no body.

Whereby: Delete Recording

whereby_delete_recording

Destructive and irreversible: delete one recording and its file. There is no undo and no trash to restore from. The call is idempotent, so deleting an already deleted recording returns the same 204. Returns no body.

Whereby: Delete Transcription

whereby_delete_transcription

Destructive and irreversible: delete one transcription and its file. A transcription made from a recording can be regenerated with Whereby: Create Transcription while that recording still exists; a session transcription cannot be regenerated at all. The call is idempotent. Returns no body.

Whereby: Set Room Background

whereby_set_room_background

Set one room's in-call background from Whereby's own presets (a color palette and an optional image), overriding the organization branding for that room only. Reversible: send palette default and theme default to restore the plain default. Uploading a CUSTOM background image is not available here: that variant of the endpoint takes a binary multipart file, which a canvas node cannot author. Returns no body.

Whereby: Set Room Colors

whereby_set_room_colors

Set one room's primary, secondary and focus colors, overriding the organization branding for that room only. Reversible: send tokensPreset default to hand the room back to the organization defaults. Returns no body.

Whereby: Set Room Knock Page Background

whereby_set_room_knock_page_background

Set the background of one room's knock page, the waiting screen a visitor sees before being let into a locked room, from Whereby's own presets. Reversible: send palette default and theme default to restore the plain default. Uploading a CUSTOM image is not available here: that variant takes a binary multipart file, which a canvas node cannot author. Returns no body.

Using the integration

On the automation canvas

Whereby nodes chain with every other node. A confirmed booking can run Whereby: Create Meeting and write the room URL onto the record in the same run, a nightly sweep can read Whereby: List Recordings into a Mattering database, and a support workflow can pull Whereby: List Session Participants when someone reports a bad call. The ids are the joinery: Whereby: List Meetings gives meeting ids, Whereby: List Recordings gives recording ids and room session ids, and Whereby: List Transcriptions gives transcription ids and the room name for each one.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter can drive the same surface. An agent asked what happened on yesterday's call can run Whereby: List Transcriptions, check that the row's state is ready, mint a link with Whereby: Get Transcription Access Link, and summarize the text with whichever AI step you already use. The twelve read nodes are the comfortable surface to hand an agent; keep the five destructive nodes behind conditions or approval steps.

Creating rooms, and who gets told

Whereby: Create Meeting mints a transient room and returns its URL, and the thing to understand about it is what it does not do: the API takes no attendee list and Whereby documents no invitation or notification for the call, so nobody hears about the room until your workflow tells them. That makes it safe to run early and distribute later. Set endDate to when the meeting should finish; the room stays reachable for one hour past that, when Whereby deactivates it, and Whereby deletes it automatically within 24 hours of the endDate. Whereby: Delete Meeting removes it sooner, and Whereby: Get Meeting reads one back by id.

Recordings, transcriptions, and links that expire

The listers return metadata only. Whereby: Get Recording Access Link and Whereby: Get Transcription Access Link are what produce a downloadable URL, and both return the timestamp at which that URL dies: one hour by default, 12 hours at most. Store the recording id or transcription id, call the link node at the moment of download, and nothing in your archive ever goes stale. Both nodes cover Whereby hosted files; a recording or transcription written to your own S3 bucket is fetched from that bucket instead. Neither call changes any stored state.

The transcription cycle is a poll, not a line

Whereby: Create Transcription queues a job against an existing recording and returns before the work is done, so a workflow that immediately asks for the file will not find one. The shape that works is a scheduled follow up: run Whereby: List Transcriptions and act on rows whose state has turned ready, since a row passes through in progress and can end at failed. Whereby: Get Transcription answers the same question for a known id. The picker on the transcription fields groups by state for exactly this reason, because only a ready row has a file behind it.

Insights, and the number that is not what it looks like

Whereby: Get Room Insights returns one row per room with participant, recorder, and streamer minutes, session counts, unique participants, and an average rating. The minutes, the session counts, and the unique participant counts are totals for the room rather than for a window you asked about, and its date filter chooses which rooms come back by when they were created rather than scoping those totals. The rating is narrower than it looks: Whereby documents it, and the rating count beside it, as the average and the number of ratings for the room's LAST session, so it is not a lifetime figure and not something to chart over time. For anything time based, work from Whereby: Get Room Session Insights, whose rows are individual sessions with their own start and end times. From a session id, Whereby: List Session Participants shows who was there with join and leave times and any rating, tags, or comment, and Whereby: Get Participant Session Details returns the sampled packet loss and bitrate series for one participant. That last node returns a bare JSON array, so its paths start at data[0] rather than data.results[]. Every rating shaped field here, on the rooms, the sessions, and the participants, requires session ratings to be enabled for the organization, so those fields stay empty until someone turns that on.

Room theming, one room at a time

Whereby: Set Room Colors sets a room's primary, secondary, and focus colors, and Whereby: Set Room Background and Whereby: Set Room Knock Page Background choose from Whereby's own palette and image presets for the in call view and the waiting screen a visitor sees before being let in. Each write overrides organization branding for that one room and each has a documented way back, so a client facing room can carry that client's look and be handed back to the defaults later. Two limits: uploading a custom image is not available here, because that variant of the endpoint takes a binary file upload, and the room name in these paths needs care, because the rest of the API reports room names with a leading slash and Whereby does not state which shape the theme path expects, so take the name from the roomUrl Whereby: Create Meeting returned.

The five destructive nodes, gated

Whereby: Delete Meeting is the sharpest, because it removes the room rather than a record: participants are ejected, the URL stops working, and a new room gets a newly generated name, so the same URL is not something you can mint again. Whereby: Delete Recording and Whereby: Delete Transcription take the file with the row and there is no trash to restore from, though a transcription generated from a recording can be regenerated with Whereby: Create Transcription while that recording still exists, and a session transcription cannot be regenerated at all. Whereby: Bulk Delete Recordings and Whereby: Bulk Delete Transcriptions add asynchrony to finality: they report success as soon as the background job is accepted. All five are idempotent, which is a small mercy on retries and no protection at all against pointing them at the wrong thing, so keep them behind a retention condition or an approval task.

Troubleshooting

Test Connection fails with a 401
Whereby answers 401 with a message about the access token being missing or invalid when the Authorization header does not carry a valid key, so a failure here is about the credential itself rather than permissions. Check for leading or trailing whitespace picked up in the copy, and paste only the key: Mattering adds the Bearer prefix, so a value that already includes the word Bearer produces a malformed header. If the key was revoked or reissued in the Whereby dashboard after you saved it, the old value stops working immediately.
Every node suddenly returns 401 after working fine
The key was almost certainly revoked or reissued, which invalidates it everywhere at once rather than per integration. Issue a new key in the Whereby Embedded dashboard, update the credential under Connectors, and run Test Connection again. Because one key covers the whole organization, a rotation done for any other tool breaks this one too; if keys rotate on a schedule, put updating this credential on the same schedule.
A room theme write fails or hits the wrong room
Room names are reported with a leading slash, for example the /room-prefix form, by insights, transcriptions, and the meeting schema. Whereby's own reference uses that same leading slash form in its example for the theme path parameter, and it does not state which shape the endpoint requires, so the shape is worth watching rather than assuming. Pasting the reported value straight into a path can produce a doubled slash in the URL, and encoding the whole value produces an escaped slash inside the path instead. The node strips a leading slash before building the request, so either shape should work, but the reliable source for these three nodes is the roomUrl that Whereby: Create Meeting returned for the room you are theming. Whereby: Get Room Insights is a poor source here for a second reason: Whereby does not document whether rooms that have never had a session appear in it at all, so do not rely on it to find a room you just created and want to brand.
A bulk delete reported success but the rows are still listed
That is the documented behavior, not a lag in Mattering. Whereby: Bulk Delete Recordings and Whereby: Bulk Delete Transcriptions schedule a background job and answer immediately, before anything has been removed, and there is no job id to poll or cancel. So the success status means the job was accepted. Build the check into the workflow: wait, then re-run Whereby: List Recordings or Whereby: List Transcriptions with the same filter and confirm the rows are gone before anything downstream treats the deletion as complete.
A delete or a theme write returns no data
Also expected. Every delete, bulk delete, and room theme write in this API answers with a success status and no response body, so the node's data output is an empty object and the result lives in the status and success fields instead. Do not branch on a returned object for these steps; branch on success, and read the effect back with the matching lister when the workflow needs proof rather than acknowledgement.
An access link node returns nothing usable, or the link has stopped working
Three causes, in the order worth checking. The link expired: it is valid for one hour by default and 12 hours at most, so it must be minted at the moment of download rather than stored. The file is not Whereby hosted: these nodes serve Whereby hosted recordings and transcriptions, and anything written to your own S3 bucket is fetched from that bucket instead. Or the transcription is not finished: only a row whose state is ready has a file behind it, so check the state with Whereby: List Transcriptions before asking for the link.
List Session Participants returns a 400
That endpoint needs either a room session id or an externalId, and supplying neither is what produces the 400. Whereby's own specification is inconsistent on this point, marking the room session id required while its description says either identifier will do, so the field is left optional in the node and Whereby's error is passed through rather than pre-empted. Room session ids come from Whereby: Get Room Session Insights, and both Whereby: List Recordings and Whereby: List Transcriptions carry a roomSessionId on every row. The externalId is whatever your own system passed on the room URL when the participant joined.
A roomName filter on the recordings or transcriptions lister returns an empty list
Whereby documents that filter only as the name of the room, without stating whether the match is exact or whether the leading slash belongs, so a value copied from insights can silently match nothing and read like a room with no recordings. Until the matching rule is confirmed against your own data, filter downstream instead: list without the room filter and match on roomSessionId, which every recording and transcription row carries and which Whereby: Get Room Session Insights resolves from a room name.
Usage totals look wrong when summed across days
Whereby: Get Room Insights reports totals per room rather than activity inside a requested window, and its createdAt filter selects which rooms are returned by when they were created rather than scoping those totals. Summing those rows by date therefore produces minutes belonging to rooms created that day, which is a different quantity from minutes used that day and will be read as the latter on any dashboard. Use Whereby: Get Room Session Insights for anything time based, since each row is one session with its own start and end. Two more fields resist arithmetic: the rating is an average for the room's last session, so it is neither a running total nor something to add up, and unique participant counts are distinct counts that cannot be summed across rows.
A workflow starts getting 429 responses
Whereby meters the API in points rather than plain request counts, and the cost of a call depends on its complexity: each request consumes between 1 and 10 points, with a low complexity read of a single resource at 1 point, a moderate complexity write or a read spanning multiple resources at 3, and a complex read, an aggregation, or a batch operation at 5 to 10, all against a budget set per organization. Whereby states that a read-only request is not guaranteed to be low cost, so do not assume the listers are the cheap option: a lister is a multi resource read and can cost more than a single get. Rather than guessing at the budget, read it from the response: Whereby returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, and a throttled call answers 429 with a Retry-After header and a body carrying the milliseconds remaining. Pace bulk sweeps from those headers rather than from an assumed cost per call.

Whereby is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products