Migration guide
Move an existing call-task integration to the single-target Calls API. Test the new integration before moving production traffic. Goal Run endpoints and request shapes are unchanged; their result readiness rule has changed. See the retirement notice for the legacy interface's planned support deadline.
Calls and SDK 1.0 are available in production. Install the new SDK only after
updating Calls inputs and response handling. Legacy calls methods in SDK 0.7.x
use the old interface and cannot read new Call IDs.
Goal Run users also need the new wait helper. SDK 0.7.x waits for result or
error to become non-null, which can time out on a final unavailable result.
Upgrade to 1.0, or poll the REST resource until result_status is not pending.
An unavailable result is not a technical error and must not trigger an automatic redial.
What changes
| Legacy call tasks | Calls | Required migration |
|---|---|---|
/v1/calls, HTTP 201 | /v2/calls, HTTP 202 | Treat create as acceptance, then wait. |
Optional inferred target or recipients[].phones | Required phone; optional region and locale | Send one destination. Omitted hints are inferred; phone/region conflicts require corrected input. |
| Optional idempotency key | Required Idempotency-Key | Save the key and original request before submission. |
| Optional nested/array result schema | Required closed scalar-object schema | Flatten fields; do not silently discard needed information. |
structured_result | result | Update response parsing. |
failure_code, failure_message | error.code, error.message, error.detail_code | Update error handling and retry decisions. |
Wait for terminal status | Wait until result_status is not pending. | Use the readiness rule for the deployed contract, not just telephone completion. |
| Top-level summary and completion fields | Business fields in result_schema | Ask for the summary or business flag explicitly. |
recipients[].attempts[].transcript_turns | Fixed top-level transcript | Read the recorded turns independently of business result availability. |
| Provider attempt details | Not in the Calls response | Resolve this dependency before migrating that workflow. |
Before and after
The same single-recipient intention has different request shapes. These are request-body examples; use a stable idempotency header for the new request.
Before
Code
After
Code
Update required inputs and result handling together. Changing the endpoint alone is insufficient. The SDK guide contains equivalent examples.
Migrate one workflow
- Inventory dependencies on batch targets, nested schemas, transcripts and old response fields.
- Install SDK 1.0 and update the request builder and readiness rule to use
result_statusandcall_outcome. - Update the receiver using Webhooks. Keep the legacy receiver for call tasks still finishing.
- Run authorized test calls against the test base URL; check results, HTTP retries and duplicate webhook handling.
- Keep each Call ID with the interface used to create it. Retrieve historical records through that interface.
- Switch new calls for the workflow once its dependencies are covered. Continue polling and receiving callbacks for calls already accepted.
Never submit the same phone task to both interfaces to compare results: both requests can place a call. Do not submit through the legacy interface after a timeout. Preserve the exact original input on recovery, including omitted hints and metadata. An already completed or failed Call is not redialed by replaying its key. See Call retry decisions before adding automatic retries.
Workflows that need a decision
Batch calls: Calls accepts one target. Client-side orchestration and aggregation may work if the application can respect account concurrency and maintain one key per logical call. This is not a server-side batch replacement.
Nested results: flatten the business fields or adapt the application's data model. Arrays and nested objects are not supported by the current schema profile.
Transcripts: use the fixed transcript field. Raw ASR updates are not a
substitute for a final transcript. Provider attempts: the Calls
response does not expose these details; resolve that dependency before migrating.
Execution timing: Calls accept immediate execution only. Scheduled and recurring execution are outside this interface.
Historical calls: the new interface does not adopt legacy records. Keep the old ID and its original interface. Post-retirement access and export arrangements will be announced separately; no new archive endpoint is currently available.