Register voicemail

Outcome

Create voicemail URL metadata for a missed local call, addressed to the original call operator.

Before you start

• Verify the exact authenticated identity, environment and approved organization context before preparing the request.
• The published application permission is workspace:write. Discover a granted canonical Voice workspace and bind its exact id. A supplied id does not grant access.
• Authorize all documented effects before CLI --confirm or MCP confirm:true. Local events, canonical archival and organization erasure have distinct scope.

Discover the target

topolo whoami --json
topolo actions get app_topolo_voice.voicemails.receive --detail --json
topolo resources topolo-voice --json
topolo workspaces list topolo-voice --json

• Select the actual granted resource id as VOICE_WORKSPACE_ID; synthetic fixture ids authorize no live operation.
• Use a real local call id retained from calls.incoming or recent granted overview. The recent call list is capped at 25; only an independently authorized organization export contains all local provider_call_id values.

Request

POST /api/voicemails/receive

Save the exact action input as payload.json. Set VOICE_WORKSPACE_ID from granted canonical resource discovery. Validate it and inspect the exact path, query and body before executing.

Inspect and test this action in the signed action console.

Input fields

The complete input and response schemas are available in the action console and through CLI/MCP action discovery.

Effects

• Requires the scoped call to exist and have status missed. Stores a new received voicemail row with recipient_user_id copied from the call operator.
• Stores recordingUrl and duration metadata only; it does not fetch/host remote audio, record a provider voicemail or grant recipient access.
• Repeated submissions create additional voicemail UUIDs. Attempts a best-effort recipient notification without a durable app outbox.

Interpret the response

Use $.data.id for the returned voicemail identifier.

Examples retain complete raw Worker responses. CLI/MCP adds a transport envelope; use CLI --detail for the full result. Delegated Auth projections can vary, and the widget uses the canonical SDK contract.

Retain data.id/callId and verify status received. Inspect workspace counts or authorized export for the original operator recipient. The export redacts recording_url to recording_url_present; this action gives no read/played receipt or remote-byte proof.

Worked examples

Actual worker and isolated migrated D1; synthetic Auth identity, nondefault workspace grants and archive transport. Notify and Nexus are disabled. No live telephony, remote audio or transcript hosting/deletion is tested. Refused examples explain boundaries; do not execute them as successful workflows.

minimal · Refused request · HTTP 409

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_399b0403-b561-498d-95aa-d8fa70c583e6",
  "recordingUrl": "https://media.example.com/fixture.wav",
  "durationSeconds": 0
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json

Captured response · HTTP 409:

{
  "error": "call_not_transitionable"
}

HTTP 409. The actual handler refused this request. Inspect the exact cause and current state before deciding whether to retry.

minimal · Refused request · HTTP 404

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_missing",
  "recordingUrl": "https://media.example.com/missing.wav",
  "durationSeconds": 0
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json

Captured response · HTTP 404:

{
  "error": "call_not_found"
}

HTTP 404. The actual handler refused this request. Inspect the exact cause and current state before deciding whether to retry.

minimal · Successful request · HTTP 201

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_f276520a-cee6-4e3c-8846-fc14157ae147",
  "recordingUrl": "https://media.example.com/missed.wav",
  "durationSeconds": 0
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_voice.voicemails.receive",
    "input": {
      "callId": "call_f276520a-cee6-4e3c-8846-fc14157ae147",
      "recordingUrl": "https://media.example.com/missed.wav",
      "durationSeconds": 0
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>",
    "confirm": true
  }
}

Captured response · HTTP 201:

{
  "data": {
    "id": "voicemail_42284c9f-d666-408e-ab09-289c6a3e32c0",
    "callId": "call_f276520a-cee6-4e3c-8846-fc14157ae147",
    "status": "received",
    "receivedAt": "2026-10-04T07:54:39.536Z"
  }
}

HTTP 201. Retain data.id/callId and verify status received. Inspect workspace counts or authorized export for the original operator recipient. The export redacts recording_url to recording_url_present; this action gives no read/played receipt or remote-byte proof.

minimal · Successful request · HTTP 201

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_f276520a-cee6-4e3c-8846-fc14157ae147",
  "recordingUrl": "https://media.example.com/missed-again.wav",
  "durationSeconds": 0
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_voice.voicemails.receive",
    "input": {
      "callId": "call_f276520a-cee6-4e3c-8846-fc14157ae147",
      "recordingUrl": "https://media.example.com/missed-again.wav",
      "durationSeconds": 0
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>",
    "confirm": true
  }
}

Captured response · HTTP 201:

{
  "data": {
    "id": "voicemail_428c666d-e7c1-4bcf-892b-253b092555c1",
    "callId": "call_f276520a-cee6-4e3c-8846-fc14157ae147",
    "status": "received",
    "receivedAt": "2026-10-04T07:54:39.564Z"
  }
}

HTTP 201. Retain data.id/callId and verify status received. Inspect workspace counts or authorized export for the original operator recipient. The export redacts recording_url to recording_url_present; this action gives no read/played receipt or remote-byte proof.

workflow · Refused request · HTTP 409

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_772a7b3c-7ee3-4295-b44a-8c4a24e47ba3",
  "recordingUrl": "https://media.example.com/fixture.wav",
  "durationSeconds": 0
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json

Captured response · HTTP 409:

{
  "error": "call_not_transitionable"
}

HTTP 409. The actual handler refused this request. Inspect the exact cause and current state before deciding whether to retry.

workflow · Refused request · HTTP 404

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_missing",
  "recordingUrl": "https://media.example.com/missing.wav",
  "durationSeconds": 0
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json

Captured response · HTTP 404:

{
  "error": "call_not_found"
}

HTTP 404. The actual handler refused this request. Inspect the exact cause and current state before deciding whether to retry.

workflow · Successful request · HTTP 201

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_3a8602fc-ada3-4b69-bf7e-b8bdb6a733a6",
  "recordingUrl": "https://media.example.com/missed.wav",
  "durationSeconds": 8
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_voice.voicemails.receive",
    "input": {
      "callId": "call_3a8602fc-ada3-4b69-bf7e-b8bdb6a733a6",
      "recordingUrl": "https://media.example.com/missed.wav",
      "durationSeconds": 8
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>",
    "confirm": true
  }
}

Captured response · HTTP 201:

{
  "data": {
    "id": "voicemail_816f3eb8-657b-4876-b7b7-fa54c785bf57",
    "callId": "call_3a8602fc-ada3-4b69-bf7e-b8bdb6a733a6",
    "status": "received",
    "receivedAt": "2026-10-04T07:54:40.511Z"
  }
}

HTTP 201. Retain data.id/callId and verify status received. Inspect workspace counts or authorized export for the original operator recipient. The export redacts recording_url to recording_url_present; this action gives no read/played receipt or remote-byte proof.

workflow · Successful request · HTTP 201

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_3a8602fc-ada3-4b69-bf7e-b8bdb6a733a6",
  "recordingUrl": "https://media.example.com/missed-again.wav",
  "durationSeconds": 0
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_voice.voicemails.receive",
    "input": {
      "callId": "call_3a8602fc-ada3-4b69-bf7e-b8bdb6a733a6",
      "recordingUrl": "https://media.example.com/missed-again.wav",
      "durationSeconds": 0
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>",
    "confirm": true
  }
}

Captured response · HTTP 201:

{
  "data": {
    "id": "voicemail_1262aecd-95cd-4280-a852-b13e406f46db",
    "callId": "call_3a8602fc-ada3-4b69-bf7e-b8bdb6a733a6",
    "status": "received",
    "receivedAt": "2026-10-04T07:54:40.546Z"
  }
}

HTTP 201. Retain data.id/callId and verify status received. Inspect workspace counts or authorized export for the original operator recipient. The export redacts recording_url to recording_url_present; this action gives no read/played receipt or remote-byte proof.

privacy · Refused request · HTTP 409

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_34f3ad97-75be-4c5d-bb06-ae16acb413e9",
  "recordingUrl": "https://media.example.com/fixture.wav",
  "durationSeconds": 0
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json

Captured response · HTTP 409:

{
  "error": "call_not_transitionable"
}

HTTP 409. The actual handler refused this request. Inspect the exact cause and current state before deciding whether to retry.

privacy · Refused request · HTTP 404

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_missing",
  "recordingUrl": "https://media.example.com/missing.wav",
  "durationSeconds": 0
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json

Captured response · HTTP 404:

{
  "error": "call_not_found"
}

HTTP 404. The actual handler refused this request. Inspect the exact cause and current state before deciding whether to retry.

privacy · Successful request · HTTP 201

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_069a28ec-eef8-4c21-989e-ac402b49cf6b",
  "recordingUrl": "https://media.example.com/missed.wav",
  "durationSeconds": 8
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_voice.voicemails.receive",
    "input": {
      "callId": "call_069a28ec-eef8-4c21-989e-ac402b49cf6b",
      "recordingUrl": "https://media.example.com/missed.wav",
      "durationSeconds": 8
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>",
    "confirm": true
  }
}

Captured response · HTTP 201:

{
  "data": {
    "id": "voicemail_8610b6d4-cc73-4c66-8bdb-c507d9772ba3",
    "callId": "call_069a28ec-eef8-4c21-989e-ac402b49cf6b",
    "status": "received",
    "receivedAt": "2026-10-04T07:54:42.343Z"
  }
}

HTTP 201. Retain data.id/callId and verify status received. Inspect workspace counts or authorized export for the original operator recipient. The export redacts recording_url to recording_url_present; this action gives no read/played receipt or remote-byte proof.

privacy · Successful request · HTTP 201

Actual local worker response and migrated D1. Auth identity/grants/archive are simulated. Notify and metering are disabled; no telephony or remote audio/transcript provider is contacted. Fixture identifiers authorize no live action.

Input · payload.json:

{
  "callId": "call_069a28ec-eef8-4c21-989e-ac402b49cf6b",
  "recordingUrl": "https://media.example.com/missed-again.wav",
  "durationSeconds": 0
}

CLI:

topolo actions validate app_topolo_voice.voicemails.receive --data @payload.json --json
topolo actions plan app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.voicemails.receive --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --confirm --detail --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_voice.voicemails.receive",
    "input": {
      "callId": "call_069a28ec-eef8-4c21-989e-ac402b49cf6b",
      "recordingUrl": "https://media.example.com/missed-again.wav",
      "durationSeconds": 0
    },
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>",
    "confirm": true
  }
}

Captured response · HTTP 201:

{
  "data": {
    "id": "voicemail_ea2a9af5-7f9e-4d48-a7b2-4466a58b4b84",
    "callId": "call_069a28ec-eef8-4c21-989e-ac402b49cf6b",
    "status": "received",
    "receivedAt": "2026-10-04T07:54:42.374Z"
  }
}

HTTP 201. Retain data.id/callId and verify status received. Inspect workspace counts or authorized export for the original operator recipient. The export redacts recording_url to recording_url_present; this action gives no read/played receipt or remote-byte proof.

Verify the result

• Retain data.id/callId and verify status received. Inspect workspace counts or authorized export for the original operator recipient.
• The export redacts recording_url to recording_url_present; this action gives no read/played receipt or remote-byte proof.

Errors and recovery

• call_not_transitionable (HTTP 409): Inspect the current call status. Complete/miss require ringing and voicemail requires missed. Do not repeat a terminal transition or invent a new state.
• call_not_found (HTTP 404): The id is absent from this organization/workspace. Discover or retain the actual local call id in the approved context; supplied ids grant no access.
• organization_required (HTTP 403): The authenticated request has no organization. Stop and establish the approved owning organization; supplied workspace ids do not create membership.

Auth, resource resolution and published input validation can refuse a request before its handler. Retain the actual error, request id and approved context. A plain-text HTTP 500 is surfaced by CLI/MCP as http_error; that transport code is not a structured Voice handler error.

Recovery boundary

No published individual voicemail delete, mark-read or remote audio erase exists. Inspect existing local metadata before repeating an ambiguous request. Do not use organization erasure as a per-voicemail undo.

Related actions

• Get Voice workspace overview: Read all-workspace counts and the most recent 25 calls and provider failures in one granted Voice workspace.
• Export Voice organization data: Read six local Voice table sets across every workspace of the authenticated organization, with remote artifact URLs redacted.

Evidence

Actual worker and isolated migrated D1; synthetic Auth identity, nondefault workspace grants and archive transport. Notify and Nexus are disabled. No live telephony, remote audio or transcript hosting/deletion is tested.