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.
Connect Whereby to Mattering
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
Every node suddenly returns 401 after working fine
A room theme write fails or hits the wrong room
A bulk delete reported success but the rows are still listed
A delete or a theme write returns no data
An access link node returns nothing usable, or the link has stopped working
List Session Participants returns a 400
A roomName filter on the recordings or transcriptions lister returns an empty list
Usage totals look wrong when summed across days
A workflow starts getting 429 responses
Related
The Whereby MCP
What connecting Whereby unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.