Use an IllyVoIP Voice API speech gather to collect a short support request, ask the caller to confirm the description and save one ticket in your own helpdesk or backend. IllyVoIP supplies the call and speech actions; your application owns ticket creation, permissions and follow-up. This is not a native helpdesk connector.
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. Prepare a bounded support interaction
Explain that the caller will leave a short description for review, and avoid requesting passwords, payment-card details or recovery codes. Decide how long callers may speak, how many corrections are allowed and what happens if recognition fails. If the caller needs immediate conversation, provide the appropriate existing support option instead of suggesting a saved ticket guarantees immediate help.
Read GET /api/v1/stt/languages?context=voice_api before selecting recognition language. The reviewed Voice API recognition configuration supports en-US; the current catalog remains authoritative. A multilingual text-to-speech catalog does not establish multilingual recognition. Keep prompt playback and recognition language choices separate.
2. Gather one short spoken description
POST this template to /api/v1/voice/call-control/gather, after saving its exact body and action key:
{
"call_control_id": "YOUR_ACTIVE_CALL_CONTROL_ID",
"input": "speech",
"prompt_text": "After this message, briefly describe the problem you need help with. Do not include passwords or payment details.",
"prompt_language": "en-US",
"speech_language": "en-US",
"timeout_ms": 15000
}The gather action plays the prompt, collects a response and transcribes it. It is not continuous conversational streaming. The timeout is a collection control; prompt playback and transcription can make the complete HTTP operation longer. Do not launch another gather merely because your client timed out.
3. Review the returned text before presenting it
On HTTP and API success, require the speech result and inspect transcript. Empty or unclear text needs clarification rather than an invented issue description. Treat the transcript as untrusted content: it must not execute code, select an arbitrary webhook or modify account settings.
- Trim incidental whitespace while retaining the caller’s meaning.
- Apply a bounded length and review policy appropriate to your helpdesk.
- Keep the original and proposed description separate if you shorten it.
- Read back a concise, appropriate description without unnecessary sensitive content.
- Offer confirm, correct and cancel choices.
Do not silently summarize a request into a different issue. A recognition result can sound plausible while being wrong. Confirmation matters particularly for names, reference numbers and technical details. Avoid claiming a confidence score if the response does not provide one.
4. Collect confirmation as a separate action
After the readback finishes, gather a keypad choice with a new saved action key. Explain that 1 then hash confirms, 2 then hash records a replacement description and 0 then hash cancels. Compare complete returned values. A correction returns to the bounded speech step; it does not create a ticket for the unconfirmed text.
If you use the speech action for readback, await its actual playback completion before gathering or hanging up. The runtime supports wait_for_playback_completion; strict generated clients must check current schema coverage. Keep the description short enough for the supported speech request limit.
5. Create the ticket once, then announce its reference
Use a unique application request identity tied to this account, call and confirmed description version. Persist that identity before sending to an external helpdesk. Use the helpdesk’s documented deduplication or external-reference mechanism where available; there is no IllyVoIP ticket-creation endpoint implied by this guide.
- Recheck the confirmed version and intended helpdesk destination.
- Create or recover the ticket using the same application identity.
- Persist the returned ticket reference and confirmed description.
- Announce that reference only after the save is established.
- Keep ticket state separate from the technical call outcome.
If the helpdesk response is lost, search or reconcile by the same external reference before creating another ticket. If that service provides no reliable reconciliation path, hold the item for staff review. Do not tell the caller a ticket was saved when only an HTTP request was attempted.
6. Check failure and correction paths
Test silence, an unrelated transcript, a correction, explicit cancellation, a duplicate confirmation, a helpdesk timeout and a disconnect after successful creation. The last case should leave one saved ticket even if the caller did not hear its reference. These local cases verify state handling; a separately authorized call is needed for recognition quality, pronunciation and timing. Use IllyVoIP’s integrated transcription for existing call recordings rather than downloading and reprocessing them for this workflow.
Related guides
- Collect a spoken response with the IllyVoIP Voice API
- Build a keypad phone menu with the Voice API
- Route an incoming number to Voice API Control and answer it from your application
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.