Topolo Docs Topolo Platform
Open workspace

List guest microphone requests

Reads only microphone requests addressed to the active guest authorized by this consumed, host-admitted secret session. Grants no host capability or workspace access.

Reads only microphone requests addressed to the active guest authorized by this consumed, host-admitted secret session. Grants no host capability or workspace access.

Action app_topolo_chat.guest_meetings.audio_controls · GET /api/guest/meeting-sessions/{sessionToken}/audio-controls. Intended audience: public.

Catalog flags: readOnly=True, requiresConfirmation=False, destructive=False, agentAccess=auto. HTTP method and empty permission fields do not override the actual effects or authority below.

Authority and prerequisites

  • Declared authorization mode=public, requiredPermission=empty; actual source identity/resource checks below remain mandatory.
  • Discover the actual identifier and current intended state within existing authority. Examples grant no access and are not executable probes.

Identifiers

  • Use the actual meetingId in the verified workspace, or the participant’s own consumed/admitted guest sessionToken. Do not paste real guest credentials into documentation or enumerate another meeting.

Input

  • sessionToken: type="string"; minLength=1. Required.

The exact native input/output schemas are retained in the hidden paired layer for this version. Top-level undeclared fields are rejected. Nested open records and semantic prerequisites still need source checks.

Effects and important boundaries

  • Reads only microphone requests addressed to the active guest authorized by this consumed, host-admitted secret session. Grants no host capability or workspace access.
  • Member runtime authorization verifies Auth identity, canonical workspace access and this meeting roster; service principals are refused. The nominal meetings:read/write permission is not a substitute for that runtime check.
  • Guest routes are catalog-public transports protected by a secret session token hash. The admission must have been consumed and belong to a joined guest in an open meeting; it confers no workspace access or host privilege. Keep the token secret.
  • Open means live or scheduled. Joined participants, and invited non-guests, pass the audio roster predicate; waiting/removed guests or ended meetings do not. Roster admission is not provider media presence.
  • Control reads return at most 100 newest commands issued by or addressed to this actor. Pending commands are presented as expired after 30 seconds without a read-side status write.
  • No server action in this set enables a microphone or captures media. applied is an executing client acknowledgment, not an independently verified media receipt.

Refusals, failures and recovery

  • 404 not_found: Use a participant from this meeting's published read. Never substitute an identifier from another workspace.
  • 409 participant_not_active: The caller and target must be admitted members or admitted guests in an open meeting. Waiting, removed and ended meetings are refused. Roster admission is not live media presence.
  • 403 moderation_forbidden: Only a host or co-host of this meeting may request remote microphone controls.
  • 403 result_forbidden: Mute results belong to the requesting host. Unmute decisions belong only to the targeted participant; hosts cannot consent for them.
  • 409 request_expired: Requests expire after 30 seconds. Read the current state before explicitly creating another request.
  • 409 request_conflict: Retry only the identical operation and target for a requestId.
  • 409 result_conflict: Read the already completed result. It cannot be overwritten.
  • 400 self_moderation: Use your own microphone control, not a host moderation request.
  • 503 database_unavailable: Retry after the meeting data service is available.

A mute never enables audio. The participant may choose to unmute themselves. Pending requests expire after 30 seconds; never turn on another person's microphone or silently retry an expired request.

Verification

  • Inspect canModerate and each command's current status. Pending is not applied; expired and failed are not success.
  • Retain actual request/receipt identifiers securely, preserve UNKNOWN effects and reconcile before any retry.

Run a reviewed request

Discover the current action and its resource requirements before running it. Save the approved input as reviewed-input.json; replace synthetic examples with values obtained through the intended authorized workflow. If discovery requires a resource binding, provide its published type and resolved ID separately on both plan and call. Stop if validation fails or the plan is not executable.

topolo actions get app_topolo_chat.guest_meetings.audio_controls --json
topolo actions validate app_topolo_chat.guest_meetings.audio_controls --data @reviewed-input.json --json
topolo actions plan app_topolo_chat.guest_meetings.audio_controls --data @reviewed-input.json --json
topolo actions call app_topolo_chat.guest_meetings.audio_controls --data @reviewed-input.json --json

Worked examples

All examples are synthetic and unrun. They cannot authorize access, create human consent, prove media/provider success or establish financial/customer state. Placeholder tokens are unusable. No contact, payment, notification, provisioning or business read was executed.

Authorized empty controls illustration

SOURCE-AUTHORED SYNTHETIC, UNRUN. Output assessment: PASS_STRUCTURAL_ONLY_UNRUN.

Input:

{
  "sessionToken": "opened-guest-session-token"
}

Output illustration or error excerpt:

{
  "participantId": "guest_example",
  "canModerate": false,
  "commands": []
}

200 with no visible commands. canModerate=false is not a missing workspace grant.

Refusal or failure

SOURCE-AUTHORED SYNTHETIC, UNRUN. Source-derived error-code excerpt only; messages/envelope can differ by layer or locale. Not a captured response. Output assessment: ERROR_EXCERPT_NOT_SUCCESS_SCHEMA.

Input:

{
  "sessionToken": "opened-guest-session-token"
}

Output illustration or error excerpt:

{
  "error": "not_found"
}

An absent or unauthorized participant/session does not yield controls.

Invalid input: stop at schema validation

SOURCE-AUTHORED SYNTHETIC, UNRUN. null is a no-response sentinel, not returned JSON null. Output assessment: NOT_APPLICABLE_NO_REQUEST.

Input:

{}

Output illustration or error excerpt:

null

Intentionally invalid input; no request was issued and no HTTP response/status is asserted.

Boundary: expired command remains visible

SOURCE-AUTHORED SYNTHETIC, UNRUN. Output assessment: PASS_STRUCTURAL_ONLY_UNRUN.

Input:

{
  "sessionToken": "opened-guest-session-token"
}

Output illustration or error excerpt:

{
  "participantId": "guest_example",
  "canModerate": false,
  "commands": [
    {
      "id": "audio_example",
      "meetingId": "meeting_example",
      "participantId": "guest_example",
      "requestedBy": "host_example",
      "operation": "request_unmute",
      "status": "expired",
      "createdAt": "2026-10-20T00:00:00.000Z",
      "expiresAt": "2026-10-20T00:00:30.000Z"
    }
  ]
}

An expired command is not provider success and is not permission to silently issue another command.

Source and verification limits

Reviewed against b5577fe8b0441cd07630b44866cb8b059a8bf047 at apps/api/src/handlers/meeting-audio-routes.ts and the published action schema on 2026-10-20. Examples are synthetic and unrun. Source review and schema validation do not prove current deployed behavior, provider completion or business delivery. Response excerpts are labelled where incomplete.

Change log

  • 2026-10-20: Prepared the action guide with paired agent schemas, permission and effect boundaries, worked examples, verification and recovery instructions. Independently checked the pinned source; publication and runtime verification remain separate.