Topolo Docs Topolo Platform
Open workspace

Report a guest microphone request result

Records only this admitted guest's explicit unmute choice or failure. Never enables media by itself. An applied result is valid only after the participant explicitly chose to enable their microphone and the client succeeded.

Records only this admitted guest's explicit unmute choice or failure. Never enables media by itself. An applied result is valid only after the participant explicitly chose to enable their microphone and the client succeeded.

Action app_topolo_chat.guest_meetings.audio_control_result · POST /api/guest/meeting-sessions/{sessionToken}/audio-controls/{commandId}/result. Intended audience: public.

Catalog flags: readOnly=False, requiresConfirmation=True, destructive=False, agentAccess=confirm. 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

  • Obtain commandId from that actor’s authorized controls read. Report applied only after real provider acknowledgment or the participant’s explicit successful unmute choice; no such event occurred in this batch.

Input

  • sessionToken: type="string"; minLength=1. Required.
  • commandId: type="string"; minLength=1. Required.
  • status: type="string"; enum=["applied", "declined", "failed"]. 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

  • Records only this admitted guest's explicit unmute choice or failure. Never enables media by itself. An applied result is valid only after the participant explicitly chose to enable their microphone and the client succeeded.
  • 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.
  • For mute, only the requesting host/co-host may report applied/failed; declined is refused. For request_unmute, only the targeted participant may apply, decline or fail. A host cannot consent for someone else.
  • Repeating the same completed result is accepted; a different completed status is result_conflict. An expired pending request is request_expired. Read current state after uncertain outcomes instead of fabricating completion.

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

  • Call app_topolo_chat.guest_meetings.audio_controls and match the command id and status. Pending is not a muted microphone or consent to unmute.
  • 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_control_result --json
topolo actions validate app_topolo_chat.guest_meetings.audio_control_result --data @reviewed-input.json --json
topolo actions plan app_topolo_chat.guest_meetings.audio_control_result --data @reviewed-input.json --confirm --json
topolo actions call app_topolo_chat.guest_meetings.audio_control_result --data @reviewed-input.json --confirm --json

--confirm must represent approval of the actual request and its effects. The examples do not supply that approval.

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 result illustration

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

Input:

{
  "sessionToken": "opened-guest-session-token",
  "commandId": "audio_example",
  "status": "declined"
}

Output illustration or error excerpt:

{
  "id": "audio_example",
  "meetingId": "meeting_example",
  "participantId": "guest_example",
  "requestedBy": "host_example",
  "operation": "request_unmute",
  "status": "declined",
  "createdAt": "2026-10-20T00:00:00.000Z",
  "expiresAt": "2026-10-20T00:00:30.000Z"
}

200 hypothetical authorized acknowledgment. This example supplies no media proof.

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",
  "commandId": "audio_example",
  "status": "declined"
}

Output illustration or error excerpt:

{
  "error": "result_forbidden"
}

Another host or participant cannot acknowledge this actor’s command or consent.

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:

{
  "commandId": "audio_example",
  "status": "declined"
}

Output illustration or error excerpt:

null

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

Boundary: expiration before acknowledgment

SOURCE-AUTHORED SYNTHETIC, UNRUN. Error-code excerpt only. Output assessment: ERROR_EXCERPT_NOT_SUCCESS_SCHEMA.

Input:

{
  "sessionToken": "opened-guest-session-token",
  "commandId": "audio_example",
  "status": "declined"
}

Output illustration or error excerpt:

{
  "error": "request_expired",
  "code": "request_expired"
}

409; a pending command expired. Do not overwrite it or report applied.

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.