Prepare a voice call before its connector opens

Status: Current | Last reviewed: 2026-10-10

An inbound flow can start the published agent's lifecycle.on_start workflow before playing its welcome. The connector then joins the same operation. This overlaps caller lookup and interaction-record creation with audio the caller already hears.

Call sequence

1. Call POST /api/workflows/{workflowId}/prepare on ai-manager using a server-held token with agents:run and AIManager:RunAgents.
2. Supply agent_id (the bare published ID), conversation_id (UUID), ani and dnis. Use exactly the call identity that the connector will receive. Phone formatting is normalized, including the tel: prefix.
3. Continue to the existing welcome on success, failure or timeout. The acceptance request has a five-second deadline and does not wait for the Salesforce workflow. Its response contains only status, execution_id and workflow_version; it never returns the patient roster to Genesys.
4. Set connector session variable startup_preparation to the string true on every outcome, including an uncertain acceptance response.
5. The orchestrator's on-start hook calls POST /api/v1/workflows/{workflowId}/prepare on async-agent with a bounded wait_seconds (at most 30). A ready result supplies the normal lifecycle output variables. A pending/failed result supplies no verified context. It never falls back to a second synchronous create.

Unmarked calls retain synchronous on-start execution. Authenticated simulation attempts retain their pinned lifecycle execution and do not use preparation. Patient selection remains conversational: preparation may look up the caller and create the parent interaction, but does not select a patient or create patient child Cases.

Amazon Connect and agent-owned preparation

An agent can opt in with a declared mutable string variable named startup_preparation, default "true". The runtime reads this authored default before constructing the variable store or invoking the start hook. This keeps the durable join enabled even when the early callout fails or times out. Authenticated evaluation attempts still use their pinned workflow execution.

For Connect Voice Connector calls, preparation uses the validated X-Amzn-ConnectInitialContactId carried through ARI and Media Proxy, falling back to the current ContactId. It does not replace the runtime transport or conversation identity. Other prepared calls retain UUID identities; non-UUID transport identifiers use the persistence layer's deterministic UUID mapping. When a direct Preview has no DNIS, preparation uses the bare agent ID. The prepared workflow's platform-neutral trigger channel is voice. Preview's lifecycle history links preparation by the persisted contact ID and routed agent within the authorized tenant, so the early workflow remains visible in AI Activity after the voice session is correlated.

The dedicated Allianz startup Lambda calls the same authenticated acceptance API. It uses its configured agent/workflow and manager endpoint, the flow's resolved trueserveCallerId, and the initial contact ID. Its DNIS is 4873, matching ARI's pipeline route. The flow waits only for acceptance (bounded to seven seconds), then plays the recording while the durable workflow runs. Both success and error edges continue to the welcome and AI transfer. See Allianz setup.

Identity, persistence and retries

Postgres owns the operation. Its execution UUID is stable for the tenant, agent, workflow and conversation. A fingerprint additionally binds ANI, DNIS and the published workflow revision. The service resolves the agent's published on-start binding server-side and pins the queued job to that workflow version. A conflicting caller, revision or start-hook binding returns 409; it does not create another operation.

A transaction/advisory lock serializes acceptance. A committed pending execution is a recoverable dispatch intent. A retry may enqueue the same execution again after an uncertain broker response; the consumer atomically claims pending → new once before entering normal workflow execution. Checkpointing, run outputs and terminal status remain on the native consumer path. This is not a second workflow engine or a guarantee that arbitrary downstream providers implement exactly-once writes.

Redis caches completed results for up to five minutes. A missing/unavailable cache reads the durable run. Preparation expires after fifteen minutes and returns 410; expiry does not recreate records. A claimed execution interrupted before it starts may require normal execution reconciliation; acceptance must not replay potentially committed work. Workflows containing top-level wait or human-review nodes are rejected.

Diagnosis and qualification

StartupPreparation logs execution ID, status, workflow version and elapsed wait. The orchestrator logs the prepared lifecycle join separately. These timings exclude voice-provider connection, greeting generation and media delivery. Measure first non-silent output audio, not the first silent audio packet or an accepted greeting instruction.

The Takeda harness apps/ai-manager/scripts/takeda-demo/dynamic-patient-voice-test.ts accepts TAKEDA_TEST_PREPARE_LEAD_MS: omit for the existing synchronous path, set zero for a cold connector join, or set a positive value to simulate the welcome's preparation lead. TAKEDA_TEST_STARTUP_ONLY=true checks greeting and absence of premature patient Cases without exercising the whole call. Full replays are still needed for conversation and transfer qualification.

The initial native preparation check completed one workflow run, one voice activity and zero patient child Cases under concurrent acceptance. Acceptance took 60–73 ms, completion took about 6.7 seconds, and a cached join took 8 ms. These are local Vanguard measurements, not a PSTN latency guarantee.

Later native prepared openings measured 4.3 and 2.6 seconds with a ten-second simulated welcome lead. A cold comparison took 19.9 seconds and exercised Live's single reconnect after a missing startup acknowledgment. The samples have different provider startup behavior; do not attribute the whole difference to preparation. See Live startup recovery for its no-replay and buffered-audio boundaries.

The Genesys example uses the tenant's server-held startup token in its integration credentials. The October 7 token expires January 5, 2027; rotate it through the normal API-token and Genesys integration credential controls before that date. Never put that token in an Architect input, flow variable, source file or browser response.