Use IllyVoIP call control to contact an approved on-call person and collect an explicit acknowledgement. Your application owns the incident, roster and escalation rules. This is a custom service-alert workflow, not an emergency or life-safety service.
Use an authenticated backend and the API base https://api.illyvoip.com. Send X-Api-Key and JSON bodies. Keep credentials out of browser code. Calls, SMS, lookups and speech can incur charges; examples are templates, not completed transactions.
1. Create one durable incident
- Deduplicate repeated monitoring events using the incident’s stable identity.
- Store the incident state, authorized roster version and next eligible recipient.
- Set limits for total attempts, simultaneous calls, elapsed time and spending in your worker.
- Define what resolution, acknowledgement and escalation mean before enabling calls.
Use a short non-sensitive spoken description. A telephone may be answered by someone other than the intended on-call person. Direct the recipient to an authenticated incident view for private details; caller ID and an answered state do not verify identity.
2. Start one tracked call
Acquire the incident’s worker lock or equivalent transaction before creating a call. POST the approved sip_user_id, to and eligible from to /api/v1/voice/call-control/calls, using the attempt’s persisted idempotency key. Save the returned control ID before allowing another worker to act.
Poll /api/v1/voice/call-control/status with a bounded delay and deadline. Continue only when the call is answered and active. Ringing, a create response or an answered timestamp alone is not acknowledgement. Do not claim automatic answering-machine detection.
3. Ask for acknowledgement explicitly
POST this template to /api/v1/voice/call-control/gather with a separately saved prompt-action key:
{
"call_control_id": "YOUR_ACTIVE_CALL_CONTROL_ID",
"input": "dtmf",
"prompt_text": "A service alert needs review. Press 1 then hash to acknowledge this notification. Open your incident dashboard for details.",
"timeout_ms": 10000
}On successful completed gathering, require input=dtmf and exactly digits=1. Store the acknowledgement against the incident and this attempt in one transaction. If the incident was resolved while the call was underway, preserve that newer state rather than reopening it.
4. Stop unsent work after acknowledgement or resolution
- Commit the new incident outcome before marking queued attempts canceled.
- Have each worker recheck the incident immediately before a paid call.
- For a call already created, inspect its current status and deliberately finish the active session when appropriate.
- Keep the acknowledgement and technical call outcome separately for later review.
Canceling an application job does not hang up an existing telephone call. If an active caller needs a final message, await its playback before hangup. Acknowledgement also does not mean the underlying service recovered; your monitoring system remains responsible for resolution.
5. Escalate only from a reconciled result
Advance to the next permitted recipient after the current attempt has a known terminal outcome and the incident still needs attention. If a create, gather or hangup response is lost, pause that incident’s escalation while reconciling it. A local timeout does not prove the earlier call ended. Avoid calling the whole roster because one request remains uncertain.
Record no answer, busy, invalid input, declined acknowledgement and transport failure distinctly. Use bounded backoff and stop at the configured limits. No article setting creates an account-wide spend guarantee; review actual charges and service constraints separately.
6. Test recovery paths
Simulate duplicate alerts, two workers, acknowledgement arriving just before the next attempt, resolution during ringing and lost responses. Confirm there is no automatic second paid call while the first is unresolved. After those tests, arrange a controlled call with the on-call team and verify the complete audible acknowledgement path.
Related guides
- Place an outbound notification call with the Voice API
- Build a keypad phone menu with the Voice API
- Send Zabbix problem and recovery alerts through IllyVoIP SMS
- Send Prometheus Alertmanager alerts through IllyVoIP SMS
Reference
Current instructions and technical reference: IllyVoIP API documentation.
Reviewed 13 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.