Build a read-only view of active IllyVoIP calls with the API

Use GET /api/v1/voice/calls/active to build a read-only view of calls currently visible to your IllyVoIP account. It is a live snapshot, not a final call-history or billing report. Keep API access on your server and expose only the fields each signed-in viewer is allowed to see.

1. Set the account and line scope

The current active-calls API requires an account-owner API key. If you want a single-line view, pass the owned SIP identity in sip_user_id. Do not accept an arbitrary browser-supplied line as authorization: validate the viewer’s allowed scope in your own backend first.

curl --fail-with-body --get \
  -H "X-API-Key: $ILLYVOIP_API_KEY" \
  --data-urlencode "sip_user_id=$ILLYVOIP_SIP_USER" \
  "https://api.illyvoip.com/api/v1/voice/calls/active"

Without a line filter, the request asks for the account scope supported by the endpoint. A forbidden line is an access error, not an empty list. Never send the owner key to browser JavaScript or reuse it as the dashboard viewer’s login credential.

2. Render the current calls

1. Require a successful HTTP response and valid JSON with status and the calls array before replacing the display.
2. Use the returned sip_user_id, from, to, direction, status and duration as the snapshot values. Display only what your operators need.
3. Keep call_id and call_control_id separate. Either can be unavailable for a particular row; do not invent a replacement from a telephone number or timestamp.
4. Show when the snapshot was last successfully refreshed. Label the screen as active calls so it cannot be mistaken for a completed-call report.

Other returned fields include codec, destination, voice_api_control and can_answer_via_api. Capability flags are not an instruction to place control buttons in a read-only display. A call-control ID identifies a controllable session; it is not interchangeable with the public call reference or a SIP packet’s Call-ID header.

3. Make refreshes safe and understandable

1. Start the next refresh after the previous one finishes, or discard responses older than the newest accepted request. This prevents a slow response from bringing an ended row back into view.
2. For a valid successful empty array, clear the previous rows and show that no calls were returned for this scope.
3. For a timeout, HTTP error or malformed response, preserve the last snapshot only with a clear stale-data message and its timestamp. Do not display “no active calls” based on a failed request.
4. Pause unnecessary polling when the view is closed, and use a bounded retry delay after errors. Follow any rate-limit response rather than retrying immediately.

4. Keep history and call control separate

A row disappearing from an active snapshot does not supply the final charge or a complete outcome. Open the Portal call history or the appropriate history endpoint for that information. Likewise, this guide does not answer, hang up or modify any call. If you later add controls, make their authorization and confirmation explicit rather than attaching mutations to a row refresh.

Verify your display before relying on it

Use local fixtures for a populated list, a successful empty list, a missing identifier, a forbidden line, a timeout and responses arriving out of order. Confirm that private caller details are hidden from unauthorized viewers. For an authorized live comparison, read the same account and line scope in the Portal and note that the two snapshots were taken at different times. A difference during a call transition is not automatically a missing call.

Related guides

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

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