Topolo Docs Topolo Platform
Open workspace

Read your Voice notification language

Read the current signed-in recipient notification language and held count in the granted workspace.

Read the current signed-in recipient notification language and held count in the granted workspace.

Action app_topolo_voice.notifications.delivery.get · GET /api/notification-delivery. 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=static, requiredPermission=app_topolo_voice.workspace:read; 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 intended human session and verified workspace context. The strict body accepts only locale, or {} for retry; no userId/workspaceId/organizationId override is accepted.

Input

Pass {}; no body/query recipient override is accepted.

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

  • Requires a current human session and canonical workspace grant. API keys and arbitrary recipient targeting are refused.
  • Ensures the local workspace identity mirror; reads your scoped preference and held count.
  • The pinned Voice source manifest omits some destructive/agentAccess fields and marks PATCH/retry requiresConfirmation=false, while the current published catalog marks both mutations requiresConfirmation=true and agentAccess=confirm. Preserve the stricter current catalog confirmation boundary; no source/catalog policy change is made by this guide.
  • Requires auth.mode=remote, a real signed-in human user and the canonical workspace grant. API keys/service recipients, arbitrary recipient IDs and cross-workspace overrides are refused.
  • Even the catalog readOnly=true GET ensures the app’s local workspace identity mirror before reading the self preference and waiting_locale count. The mirror is not a new canonical workspace or grant.
  • Waiting rows select their originally captured language snapshot; pending retry envelopes keep their first selected language and original idempotency key. Invalid captured release/copy cannot be silently replaced with current strings.

Refusals, failures and recovery

  • 403 human_recipient_required: Use the intended human session and granted workspace.

A saved preference can be replaced with another supported locale for future held notifications. Already pending/delivered snapshots and delivered external notifications cannot be undone here. Retry transient failures with the original self scope.

Verification

  • Read notifications.delivery.get on the same granted workspace and human session.
  • For a retry, inspect sent/rejected/failed counts. Sent means Notify accepted an event, not that email or remote audio was received.
  • 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_voice.notifications.delivery.get --json
topolo actions validate app_topolo_voice.notifications.delivery.get --data @reviewed-input.json --json
topolo actions plan app_topolo_voice.notifications.delivery.get --data @reviewed-input.json --json
topolo actions call app_topolo_voice.notifications.delivery.get --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.

Self delivery state illustration

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

Input:

{}

Output illustration or error excerpt:

{
  "data": {
    "workspaceId": "workspace_example",
    "locale": null,
    "status": "unconfigured",
    "waitingCount": 2
  }
}

200 synthetic source-shaped data; no transport or preference action was executed.

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:

{}

Output illustration or error excerpt:

{
  "error": "human_recipient_required"
}

API keys and non-human callers cannot target a human recipient.

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:

{
  "unexpectedRecipientId": "other_user"
}

Output illustration or error excerpt:

null

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

Boundary: configured user with held rows

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

Input:

{}

Output illustration or error excerpt:

{
  "data": {
    "workspaceId": "workspace_example",
    "locale": "fr",
    "status": "configured",
    "waitingCount": 1
  }
}

The count is scoped held work, not evidence of transport failure or successful delivery.

Source and verification limits

Reviewed against eddfc32b3d42db6aa9b22fb77fe6f5ae426f1e0f at apps/api/src/notification-delivery.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.