Let callers request a callback through the IllyVoIP Voice API

Offer callers a callback by collecting their explicit choice during an IllyVoIP API-controlled call and saving the request in your application. Your backend manages the destination, contact window and fulfillment. This is a custom callback workflow, not a native virtual-queue position or a promise of an exact callback time.

Use a backend with authorized account API access and keep X-Api-Key out of browser code. The API base is https://api.illyvoip.com. Check HTTP status and the JSON result. Examples below are request templates, not records of completed transactions.

Start with an eligible incoming call answered through Voice API Control, or a deliberately created outbound API call confirmed active and answered. Keep its call_control_id. Save a separate action key and exact payload before each billable gather or speech action. Calls and speech processing can incur charges.

1. Decide what the callback offer means

Set the audience, supported hours, maximum outstanding requests and a realistic response policy before enabling the offer. Explain whether a person will review the request and whether the caller can remain on the current call instead. Do not promise a queue position your application does not actually maintain.

1. Choose a known eligible callback destination associated with the customer.
2. Verify that the person may request contact at that destination; presented caller ID alone is insufficient.
3. Store the applicable timezone and permitted contact window.
4. Choose an expiry policy for requests that cannot be fulfilled.
5. Provide a way to cancel or correct an outstanding request through your application.

For an unknown caller, use your established verification or an operator-assisted process. Do not turn any caller-supplied number into an automatic outbound call. A keypad “yes” records a choice; it does not verify ownership of a third party’s number.

2. Ask for a specific choice

Once the destination is verified and the current call is active, POST a short menu to /api/v1/voice/call-control/gather. The following body is a template for the choice only:

{
  "call_control_id": "YOUR_ACTIVE_CALL_CONTROL_ID",
  "input": "dtmf",
  "prompt_text": "To request a callback to your verified contact number, press 1 then hash. To leave without a callback, press 0 then hash.",
  "timeout_ms": 10000
}

Save this action’s exact request and key. On completed API success, require input=dtmf and compare the entire digits value. Exactly 1 requests the callback; exactly 0 declines. Empty input, 11 and unsupported keys do not express a valid request. Use a bounded clarification or finish without creating one.

3. Commit one request before confirming it

1. Create a durable request under the customer account, call control ID and workflow step.
2. Store the verified destination, explicit choice, timezone, contact window and creation time.
3. Enforce a unique request identity so a repeated gather response cannot create a second callback.
4. If the caller already has an open request, apply your reviewed merge or duplicate policy explicitly.
5. Commit the result before telling the caller it has been saved.

If storage fails or the outcome is uncertain, do not announce a confirmed callback. Reconcile the same request identity and give an honest fallback while the call remains active. If the caller disconnects after the request was committed, preserve that saved choice rather than creating another request on a repeated event.

4. Finish the current conversation

Use a short speech confirmation stating that the request was received and describing the actual service window. For /api/v1/voice/call-control/speak, the current runtime supports wait_for_playback_completion: true. Wait for completed playback before requesting /api/v1/voice/call-control/hangup; a prompt accepted for playback is not a finished prompt. Generated clients should check current schema coverage for this completion option.

Record the callback request separately from the original call outcome. Hanging up the original call does not itself schedule, create or fulfill an outbound callback.

5. Fulfill through an authorized operator or worker

Before dispatch, atomically claim the pending request and recheck its permission, destination, time window and cancellation state. An operator can call through the normal IllyVoIP workflow. An application that creates an outbound Voice API call should use the established outbound guide, with its own saved request key and eligible SIP identity and caller ID.

Persist the resulting call-control identity and actual outcome. A create response or ringing state is not a successful conversation. A timeout is not proof that no call was placed; leave the request uncertain until reconciled. Do not start another paid call merely because the worker missed a response.

6. Test the complete request lifecycle

Use local fixtures for valid consent, refusal, invalid input, a duplicate result, a failed database commit, cancellation just before dispatch and a worker crash after call creation. Confirm a late worker cannot revive an expired request. Check timezone boundaries using your actual scheduling policy. Only a separately authorized live call can verify prompt timing and the eventual callback experience.

Related guides

• Route an incoming number to Voice API Control and answer it from your application
• Build a keypad phone menu with the Voice API
• Place an outbound notification call with the Voice API
• Run and supervise a calling campaign

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.