Topolo Docs Topolo Platform
Open workspace

Choose your Voice notification language

Save one supported notification language for yourself in the granted workspace and retry your captured notifications.

Save one supported notification language for yourself in the granted workspace and retry your captured notifications.

Action app_topolo_voice.notifications.delivery.set · PATCH /api/notification-delivery. 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

  • Explicit authorization to save language and potentially dispatch self notifications.
  • Declared authorization mode=static, requiredPermission=app_topolo_voice.workspace:write; 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

  • locale: type="string"; enum=["en", "ar", "es", "fr", "de", "pt-BR", "ja", "hi"]. 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

  • Requires a current human session and canonical workspace grant. API keys and arbitrary recipient targeting are refused.
  • Changes only your own preference or notification delivery rows. Captured all-eight translation release and customer facts remain immutable; pending retries retain the first selected language and original idempotency key.
  • 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.
  • PATCH saves only the self locale, then dispatches captured notifications. POST retry requires an actual JSON {} body and can send to Notify. Neither is a documentation probe.
  • 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.
  • Dispatch scopes by organization/workspace/recipient, materializes eligible waiting rows, leases up to 100 pending/expired-sending rows and records delivered/failed/pending states. A sent count means Notify accepted an event, not that email/audio was received.
  • Missing Notify configuration can return all-zero dispatch counts after materializing waiting rows; zero counts are not proof there is no held/backlogged work. Re-read the self preference/count under separate authority when needed.
  • PATCH returns the preference snapshot read before dispatch along with delivery counters. waitingCount can therefore precede the dispatch changes; it is not a final post-dispatch held count.

Refusals, failures and recovery

  • 403 human_recipient_required: Sign in as the intended recipient and resolve their own workspace grant; do not substitute an API-key owner or delegated identity.
  • 422 invalid_notification_preference: Use only the published input schema; do not add recipient or workspace overrides.

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.set --json
topolo actions validate app_topolo_voice.notifications.delivery.set --data @reviewed-input.json --json
topolo actions plan app_topolo_voice.notifications.delivery.set --data @reviewed-input.json --confirm --json
topolo actions call app_topolo_voice.notifications.delivery.set --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.

Self delivery state illustration

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

Input:

{
  "locale": "fr"
}

Output illustration or error excerpt:

{
  "data": {
    "workspaceId": "workspace_example",
    "locale": "fr",
    "status": "configured",
    "waitingCount": 0,
    "delivery": {
      "pending": 0,
      "sent": 0,
      "rejected": 0,
      "failed": 0
    }
  }
}

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:

{
  "locale": "fr"
}

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:

{}

Output illustration or error excerpt:

null

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

Boundary: pre-dispatch preference snapshot

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

Input:

{
  "locale": "fr"
}

Output illustration or error excerpt:

{
  "data": {
    "workspaceId": "workspace_example",
    "locale": "fr",
    "status": "configured",
    "waitingCount": 1,
    "delivery": {
      "pending": 1,
      "sent": 1,
      "rejected": 0,
      "failed": 0
    }
  }
}

The returned waitingCount was read before dispatch; sent is Notify acceptance, not recipient receipt.

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.