Run an ordered Voice API action sequence and inspect partial results

The Voice API Execute endpoint runs an ordered list of actions on an existing call-control session. Use it when your application needs a sequence such as speaking a prompt, collecting input and using the result without sending a separate HTTP request for every step.

This is a live call operation. Speech, transcription and calling may have separate charges. You need a control-session reference returned by Create or Answer, an authorized backend and a durable record of the exact batch request. Execute does not make the entire sequence an all-or-nothing transaction.

1. Start with an existing controlled call

Save the returned call_control_id when your application creates or answers the call. Do not substitute a historical public call reference, SIP channel name or browser SDK call ID. Confirm that the call is in an appropriate state for the intended actions.

Serialize actions for this call in your application. Two workers sending competing sequences can produce unexpected ordering even if both requests are valid. Retain one application operation record containing the call reference, exact payload, idempotency key and processing state.

2. Build a small, explicit action list

The following example illustrates a keypad question. Replace the control reference with the one returned for your call. Each action uses the parameters documented for its individual endpoint; the batch wrapper does not remove their requirements.

{
  "call_control_id": "YOUR_RETURNED_CONTROL_ID",
  "actions": [
    {
      "type": "speak",
      "text": "Press 1 for sales or 2 for support."
    },
    {
      "type": "gather",
      "input": "dtmf",
      "timeout_ms": 10000,
      "save_as": "menu_choice",
      "save_field": "digits"
    }
  ]
}

Save this as execute-request.json after replacing the placeholder. The example waits for the prompt before gathering. It does not automatically transfer a call or repeat the menu when no input arrives. Your application must inspect the result and decide what to do next.

Use short sequences you can reason about. A result may be stored with save_as and an explicit save_field for later use. For templated actions, follow the documented variable syntax and validate collected input before it affects a destination or sensitive business action. Never treat spoken text or keypad digits as authorization on their own.

3. Submit with one stable idempotency key

curl --silent --show-error --fail-with-body \
  'https://api.illyvoip.com/api/v1/voice/call-control/execute' \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set the server-side key}" \
  -H "Idempotency-Key: ${BATCH_KEY:?Set the saved logical batch key}" \
  -H 'Content-Type: application/json' \
  --data-binary @execute-request.json > execute-response.json

Persist BATCH_KEY before submitting. A replay of the same completed request with the same key returns its saved result. Reusing the key for changed content produces a conflict. Generating a fresh key merely because the response was slow can create another paid action sequence.

If the request times out, retain the exact body and original key. Reconcile the operation using the documented replay and current call-state behavior. Do not skip straight to a new batch or assume that nothing ran. Bound your recovery attempts and keep unresolved operations visible for review.

4. Inspect every result, not only HTTP status

Read the batch status, returned control reference, results array and vars. Each action result has a type and ok indicator; failures include an error. An HTTP 200 response alone does not establish that all requested actions succeeded or that the caller heard every prompt.

In the example, examine the gather result and the saved menu_choice. Accept only the intended choices. An empty result, caller hangup or failed gather needs a defined branch, such as ending politely or returning control to an operator. Do not invent a default selection that could route the caller incorrectly.

Charges can be absent or null when none applies. Interpret each action’s documented charge fields separately from the call’s overall usage. Do not infer a refund or zero total cost from one null action charge.

5. Handle partial completion and content review

Earlier completed actions remain completed if a later action fails. The normal sequence stops on an error; do not model it as a rollback. Before continuing, inspect the original results and current call state so you do not replay a greeting, duplicate a transfer or gather from an ended call.

A text action can require Communication review. Retain the returned review reference and follow the Portal’s Communication reviews workflow. The rejected text is not played or charged, and later actions stop; earlier work is not undone. Replaying the same key returns the same result, not a fresh review attempt.

Test the sequence before using it with callers

Use local response fixtures for full success, an empty gather, failure after the first action, review-required results, a lost response and a same-key replay. Confirm that your application neither repeats completed actions nor mistakes HTTP success for business completion. A separately authorized live test is needed to establish actual audio, timing and destination behavior.

Related guides and reference

• Place an outbound notification call with the Voice API
• Build a keypad phone menu with the Voice API
• Collect a spoken response with the IllyVoIP Voice API
• Explain your activity in Communication reviews
• Execute action chain reference

Reviewed 10 October 2026 against the current IllyVoIP reference and implementation. SDK examples target version 1.4.2 where applicable. Local example checks do not certify a completed live call, routing change or third-party integration.

Insert a timed wait between actions

Use the wait action when your call flow needs a deliberate pause before the next step. The call remains live during the pause, so normal call charges continue. This is not hold music, digit gathering or a substitute for waiting for an asynchronous playback operation to finish.

The canonical wait parameter is seconds. Use an integer from 1 through 600. The current input handling defaults to 1 and bounds values to that range; validate your intended duration in your own application rather than relying on a clamped value to represent a longer workflow.

{
  "call_control_id": "YOUR_SAVED_CALL_CONTROL_ID",
  "seconds": 3
}

That is the body for POST /api/v1/voice/call-control/wait. When inserting a wait into the ordered execute action list, use the same wait action and seconds parameter in the action structure already described above. Keep the batch’s stable operation identity and original payload across retries.

1. Finish or await the previous action as required by its own completion contract.
2. Insert the intended short wait before the next action. Choose a duration that serves the conversation rather than leaving a caller in silence unnecessarily.
3. Allow enough client response time for the requested pause and normal request overhead. A client timeout shorter than the wait does not mean the call paused for only that timeout.
4. Inspect the action result before continuing. If the caller ends the conversation, stop the remaining flow after reconciling the session status.

Recover without accidentally adding another pause

A standalone repeated wait is another instruction to wait; do not assume it has exactly-once replay semantics. If its response is lost, retain the uncertainty and inspect the call’s status before deciding how to proceed. Do not blindly restart the preceding speech or the entire conversation. Within an execute batch, use the documented batch recovery and partial results rather than submitting a new batch identity for the same work.

For example, a three-second pause between a completed explanation and the next prompt should not cause that explanation to play again after a network timeout. Your saved action progress should make clear what is completed, what is uncertain and whether the call is already terminal. A successful wait confirms the timed action result, not that the caller heard or understood the earlier prompt.

Reviewed 12 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.