End an IllyVoIP Voice API call and verify it has finished

Send a hangup request for the saved call_control_id when your application has finished an IllyVoIP Voice API conversation. Then read the session status to confirm that it is terminal. A local timeout or a closed browser window is not evidence that the telephone call ended.

Before you send hangup

Use the account’s server-side API key and the call-control ID returned by the original create or answer operation. Keep that ID with your business job. Do not use a destination number, public call ID or SIP Call-ID in its place. Serialize control actions for the session so another worker is not simultaneously starting speech or gathering digits.

1. Decide that the conversation should end. If a final prompt must finish first, wait for the documented playback completion rather than hanging up immediately after playback acceptance.
2. Record that termination has been requested for this exact call-control ID. Stop scheduling further call actions for it.
3. Send POST /api/v1/voice/call-control/hangup with the JSON body shown below, using your existing session reference.

{
  "call_control_id": "YOUR_SAVED_CALL_CONTROL_ID"
}

Use the current API authentication and content-type headers. If your client supplies an idempotency header as shown in the API reference, retain it with this logical operation. Recovery still depends on checking the same call’s state; a header does not replace that check.

Confirm that the session has ended

1. Save the hangup HTTP result and response. A success is the service’s termination result; read status to reconcile your application state.
2. Send POST /api/v1/voice/call-control/status with the same call_control_id.
3. Use the returned terminal indicator and state to stop all further actions and mark your job complete. Do not classify every unfamiliar state as terminal.
4. If the status is not terminal, keep the job in an ending or review state and perform a bounded follow-up check. Preserve uncertainty if the service cannot determine the live state.

Hangup can succeed idempotently when the session is already terminal and no live call remains. That does not mean the caller stayed connected until your request: the caller may have ended the conversation first. Avoid using the time your application received the response as a fabricated exact call-end time.

Recover from a lost response

1. If hangup times out, keep the original call-control ID and mark the result unknown.
2. Read status for that same session. If it is terminal, finish local cleanup without another call.
3. If it is still active, retry termination for the same session according to your bounded recovery policy. Do not create a new outbound call as a retry of hangup.
4. If status or hangup reports an unavailable or unverifiable state, retain the operation for review and record the error and time. A “not found or already ended” message alone is not a detailed final billing record.

Reconcile history separately

Use call history when you need the final duration, outcome or charge. It can arrive separately from call-control completion, so do not invent a zero charge while waiting for the record. For troubleshooting, provide Support with the call-control reference privately, the public call reference if available, operation times and redacted response. Never include the API key or unrelated recordings.

Before deploying your workflow, test caller-first hangup, duplicate hangup, a lost response and a nonterminal status with local fixtures. These checks validate your recovery logic without placing a call; a real end-to-end call check is a separate authorized activity.

Related guides

• Place an outbound notification call with the Voice API
• How to Read and Understand Your VoIP Call Reports (CDR)

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