Outcome
Create a local incoming ringing-call event using the provider call identifier and supplied phone-number strings.
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.calls.incoming --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 verified external event and its actual providerCallId. This action records that event; it does not initiate telephony.
Request
POST /api/calls/incoming
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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
provider | Required | string | Nonblank trimmed provider label; no provider configuration or supported-provider enum is established. {"minLength":1} |
providerCallId | Required | string | Nonblank trimmed provider event identifier; unique with provider and granted workspace. Do not invent a live event id. {"minLength":1} |
fromNumber | Required | string | Nonblank trimmed string representing the supplied caller; no E.164 or ownership validation occurs. {"minLength":1} |
toNumber | Required | string | Nonblank trimmed destination string; no telephone routing is performed. {"minLength":1} |
The complete input and response schemas are available in the action console and through CLI/MCP action discovery.
Effects
- Creates a new call UUID in the granted workspace and records the acting user as operator_user_id. It does not place, answer or bridge a telephony call.
- Workspace/provider/providerCallId is unique. Replaying the same tuple currently returns an unstructured HTTP 500 rather than an idempotent acknowledgement.
- Attempts a best-effort incoming notification when configured after the database insertion. There is no durable app notification outbox; local success does not prove delivery.
Interpret the response
Use $.data.id for the returned call 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.
Save data.id and confirm status ringing. Read workspace.overview.get in the same workspace for the local event. After a timeout or ambiguous error, inspect recent calls or an authorized organization export for provider_call_id before repeating. The recent list omits providerCallId and is capped at 25.
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 · 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:
{
"provider": "twilio",
"providerCallId": "synthetic_minimal",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
}
CLI:
topolo actions validate app_topolo_voice.calls.incoming --data @payload.json --json
topolo actions plan app_topolo_voice.calls.incoming --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.calls.incoming --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.calls.incoming",
"input": {
"provider": "twilio",
"providerCallId": "synthetic_minimal",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
},
"resourceType": "workspace",
"resourceId": "<id returned by granted resource discovery>",
"confirm": true
}
}
Captured response · HTTP 201:
{
"data": {
"id": "call_399b0403-b561-498d-95aa-d8fa70c583e6",
"status": "ringing",
"createdAt": "2026-10-04T07:54:39.172Z"
}
}
HTTP 201. Save data.id and confirm status ringing. Read workspace.overview.get in the same workspace for the local event. After a timeout or ambiguous error, inspect recent calls or an authorized organization export for provider_call_id before repeating. The recent list omits providerCallId and is capped at 25.
minimal · Refused request · HTTP 500
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:
{
"provider": "twilio",
"providerCallId": "synthetic_minimal",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
}
CLI:
topolo actions validate app_topolo_voice.calls.incoming --data @payload.json --json
topolo actions plan app_topolo_voice.calls.incoming --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
Captured response · HTTP 500:
Internal Server Error
HTTP 500. 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:
{
"provider": "twilio",
"providerCallId": "missed_minimal",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
}
CLI:
topolo actions validate app_topolo_voice.calls.incoming --data @payload.json --json
topolo actions plan app_topolo_voice.calls.incoming --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.calls.incoming --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.calls.incoming",
"input": {
"provider": "twilio",
"providerCallId": "missed_minimal",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
},
"resourceType": "workspace",
"resourceId": "<id returned by granted resource discovery>",
"confirm": true
}
}
Captured response · HTTP 201:
{
"data": {
"id": "call_f276520a-cee6-4e3c-8846-fc14157ae147",
"status": "ringing",
"createdAt": "2026-10-04T07:54:39.490Z"
}
}
HTTP 201. Save data.id and confirm status ringing. Read workspace.overview.get in the same workspace for the local event. After a timeout or ambiguous error, inspect recent calls or an authorized organization export for provider_call_id before repeating. The recent list omits providerCallId and is capped at 25.
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:
{
"provider": "fixture-provider",
"providerCallId": "synthetic_workflow",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
}
CLI:
topolo actions validate app_topolo_voice.calls.incoming --data @payload.json --json
topolo actions plan app_topolo_voice.calls.incoming --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.calls.incoming --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.calls.incoming",
"input": {
"provider": "fixture-provider",
"providerCallId": "synthetic_workflow",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
},
"resourceType": "workspace",
"resourceId": "<id returned by granted resource discovery>",
"confirm": true
}
}
Captured response · HTTP 201:
{
"data": {
"id": "call_772a7b3c-7ee3-4295-b44a-8c4a24e47ba3",
"status": "ringing",
"createdAt": "2026-10-04T07:54:40.127Z"
}
}
HTTP 201. Save data.id and confirm status ringing. Read workspace.overview.get in the same workspace for the local event. After a timeout or ambiguous error, inspect recent calls or an authorized organization export for provider_call_id before repeating. The recent list omits providerCallId and is capped at 25.
workflow · Refused request · HTTP 500
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:
{
"provider": "fixture-provider",
"providerCallId": "synthetic_workflow",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
}
CLI:
topolo actions validate app_topolo_voice.calls.incoming --data @payload.json --json
topolo actions plan app_topolo_voice.calls.incoming --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
Captured response · HTTP 500:
Internal Server Error
HTTP 500. 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:
{
"provider": "fixture-provider",
"providerCallId": "missed_workflow",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
}
CLI:
topolo actions validate app_topolo_voice.calls.incoming --data @payload.json --json
topolo actions plan app_topolo_voice.calls.incoming --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.calls.incoming --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.calls.incoming",
"input": {
"provider": "fixture-provider",
"providerCallId": "missed_workflow",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
},
"resourceType": "workspace",
"resourceId": "<id returned by granted resource discovery>",
"confirm": true
}
}
Captured response · HTTP 201:
{
"data": {
"id": "call_3a8602fc-ada3-4b69-bf7e-b8bdb6a733a6",
"status": "ringing",
"createdAt": "2026-10-04T07:54:40.450Z"
}
}
HTTP 201. Save data.id and confirm status ringing. Read workspace.overview.get in the same workspace for the local event. After a timeout or ambiguous error, inspect recent calls or an authorized organization export for provider_call_id before repeating. The recent list omits providerCallId and is capped at 25.
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:
{
"provider": "fixture-provider",
"providerCallId": "synthetic_privacy",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
}
CLI:
topolo actions validate app_topolo_voice.calls.incoming --data @payload.json --json
topolo actions plan app_topolo_voice.calls.incoming --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.calls.incoming --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.calls.incoming",
"input": {
"provider": "fixture-provider",
"providerCallId": "synthetic_privacy",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
},
"resourceType": "workspace",
"resourceId": "<id returned by granted resource discovery>",
"confirm": true
}
}
Captured response · HTTP 201:
{
"data": {
"id": "call_34f3ad97-75be-4c5d-bb06-ae16acb413e9",
"status": "ringing",
"createdAt": "2026-10-04T07:54:41.559Z"
}
}
HTTP 201. Save data.id and confirm status ringing. Read workspace.overview.get in the same workspace for the local event. After a timeout or ambiguous error, inspect recent calls or an authorized organization export for provider_call_id before repeating. The recent list omits providerCallId and is capped at 25.
privacy · Refused request · HTTP 500
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:
{
"provider": "fixture-provider",
"providerCallId": "synthetic_privacy",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
}
CLI:
topolo actions validate app_topolo_voice.calls.incoming --data @payload.json --json
topolo actions plan app_topolo_voice.calls.incoming --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
Captured response · HTTP 500:
Internal Server Error
HTTP 500. 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:
{
"provider": "fixture-provider",
"providerCallId": "missed_privacy",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
}
CLI:
topolo actions validate app_topolo_voice.calls.incoming --data @payload.json --json
topolo actions plan app_topolo_voice.calls.incoming --resource-type workspace --resource-id "$VOICE_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_voice.calls.incoming --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.calls.incoming",
"input": {
"provider": "fixture-provider",
"providerCallId": "missed_privacy",
"fromNumber": "+15550100001",
"toNumber": "+15550100002"
},
"resourceType": "workspace",
"resourceId": "<id returned by granted resource discovery>",
"confirm": true
}
}
Captured response · HTTP 201:
{
"data": {
"id": "call_069a28ec-eef8-4c21-989e-ac402b49cf6b",
"status": "ringing",
"createdAt": "2026-10-04T07:54:42.238Z"
}
}
HTTP 201. Save data.id and confirm status ringing. Read workspace.overview.get in the same workspace for the local event. After a timeout or ambiguous error, inspect recent calls or an authorized organization export for provider_call_id before repeating. The recent list omits providerCallId and is capped at 25.
Verify the result
- Save data.id and confirm status ringing. Read workspace.overview.get in the same workspace for the local event.
- After a timeout or ambiguous error, inspect recent calls or an authorized organization export for provider_call_id before repeating. The recent list omits providerCallId and is capped at 25.
Errors and recovery
http_error(HTTP 500): The current duplicate workspace/provider/providerCallId tuple fails with plain-text HTTP 500. Retain the HTTP status, request id and context; inspect existing call records before repeating. This is not a structured service error code or a successful replay.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
There is no published per-call delete, provider event replay repair or call rollback. If a genuinely ringing event ends, independently authorize calls.complete or calls.miss using the retained call id. Do not erase organization data to undo one event.
Related actions
- Complete call record: Transition an existing ringing local call record to completed with the supplied nonnegative integer duration.
- Mark call missed: Transition an existing ringing local call record to missed.
- Get Voice workspace overview: Read all-workspace counts and the most recent 25 calls and provider failures in one granted Voice workspace.
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.