Build a short keypad survey with the IllyVoIP Voice API

Build a short keypad survey by gathering one answer at a time on an IllyVoIP API-controlled call. Your backend owns the questions, consent, answer storage and reporting. There is no implied native survey dashboard or automatic survey after a transferred agent call.

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.

Begin with an eligible incoming call answered through Voice API Control, or a deliberately created outbound call whose status confirms it is answered and active. Retain call_control_id. Persist a separate Idempotency-Key for each paid prompt action and reconcile a pending result with the same key before deciding on a new action.

1. Define the survey before placing a call

1. Use an audience you are authorized to contact and explain the purpose of the survey.
2. Store a fixed survey version, ordered question IDs and allowed choices.
3. Set a maximum call duration and a small retry limit per question.
4. Provide a clear exit choice and decide how partial responses will be retained.

For example, ask two questions using ratings 1–5 and reserve 0 to exit. Keep the scale’s meaning consistent. Do not change a question’s wording while a call is in progress; start a new survey version for later respondents instead.

2. Ask one question and persist its action identity

POST to /api/v1/voice/call-control/gather with the current call’s control ID. Save the survey attempt, question ID and action key before submission. The hash key terminates a short entry; compare the complete returned value, not its first digit.

{
  "call_control_id": "YOUR_ACTIVE_CALL_CONTROL_ID",
  "input": "dtmf",
  "prompt_text": "How clear was the information? Rate from 1, not clear, to 5, very clear, then press hash. Press 0 then hash to leave the survey.",
  "timeout_ms": 10000
}

On HTTP and API success, confirm input is dtmf and read digits. Empty input, a failed action and a pending request are different outcomes. Do not store a score for an unresolved response.

3. Validate the answer and advance once

def survey_choice(digits):
    if digits == "0":
        return ("exit", None)
    if digits in {"1", "2", "3", "4", "5"}:
        return ("answer", int(digits))
    return ("invalid", None)

1. For a valid answer, transactionally save one result for this survey attempt and question.
2. Mark the action processed so a repeated response cannot advance the question twice.
3. Select the next question from the saved survey version.
4. For invalid or empty input, use the remaining completed-attempt allowance; otherwise end with a partial result.

Do not count a request still marked voice_request_pending as a completed retry. Reconcile it before another prompt. If the caller disconnects, retain the answers already committed and mark the attempt incomplete rather than inventing the remaining scores.

4. Finish with the correct outcome

After the final answer is stored, mark the survey completed and speak a short thank-you. For a voluntary exit, record that outcome separately. When speaking through /api/v1/voice/call-control/speak, the current implementation supports wait_for_playback_completion: true. Await completion before posting the control ID to /api/v1/voice/call-control/hangup. Never run prompt and hangup concurrently.

5. Check the workflow before launch

Use local fixtures for 1, 5, 0, silence, 11, repeated responses, a question-version change and a disconnect after the first answer. Confirm the result store cannot record two answers for the same question unintentionally. Then arrange an authorized call to check prompt clarity, DTMF and timing on real equipment. Keep aggregate reporting separate from identifying information and retain only the survey data your process requires.

Related guides

• Build a keypad phone menu with the Voice API
• Place an outbound notification call with the Voice API
• Send a customer-feedback survey link 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.