Build a language menu by mapping a keypad choice to reviewed prompt text, a supported Voice API language and a permitted destination. Store that selection for the current call. Choosing a language does not translate text or enable automatic speech-language detection.
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. Read the catalog in the correct context
Request GET /api/v1/tts/languages?context=voice_api. Choose a returned language value, then request GET /api/v1/tts/voices with that language and context=voice_api. Keep the language and exact voice identifier together. Do not copy a voice from the standalone Speech API catalog without checking this context.
- Confirm the returned language matches the requested language.
- Choose a suitable returned voice or the applicable catalog default.
- Prepare and review the actual wording for each supported choice.
- Keep an explicit default path for callers who cannot make a selection.
Do not assume a multilingual TTS catalog means multilingual speech recognition. This guide uses keypad input throughout. The reviewed Voice API recognition catalog is limited to its currently returned language choices; it is not used to infer the caller’s language here.
2. Write a short selection prompt
Keep the initial menu understandable for the intended audience. If different language phrases require separate audio preparation, prepare and review that audio deliberately rather than expecting one TTS language setting to pronounce every phrase correctly. Avoid a long list that callers must remember.
{
"call_control_id": "YOUR_ACTIVE_CALL_CONTROL_ID",
"input": "dtmf",
"prompt_text": "For English, press 1 then hash. For German, press 2 then hash.",
"timeout_ms": 10000
}This example offers English and German. Enable those choices only after confirming both catalog entries and the corresponding service path. Review the initial menu for your audience; use approved multilingual audio when one spoken language would leave callers unable to choose. POST it to /api/v1/voice/call-control/gather with its own saved action key.
3. Map complete values to saved choices
After a completed successful DTMF response, map exactly 1 or 2 to the server’s configured language record. Reject 12, arbitrary text and empty input according to a small retry allowance. Keep a pending request unresolved until its actual result is known.
- Save the selected language against this control session.
- Choose the next reviewed text in that language.
- Use its compatible catalog voice and language fields for speech; for gather prompts use the supported prompt-language field.
- Keep the selected destination in an allowlisted server-side map.
Do not let a keypad value become an arbitrary SIP target. If a language is temporarily unavailable, offer an honest fallback instead of silently selecting a different service and claiming it matches the caller’s choice.
4. Follow the next action to completion
For another keypad question, create a separate prompt action and preserve the language choice. For a transfer, POST the control ID and configured target to /api/v1/voice/call-control/transfer. Save transfer_id and follow transfer status. Ringing is not proof that a language-capable agent answered; handle a failed transfer with the reviewed fallback in the selected language.
5. Review each language path
Test valid choices, silence, repeated input, unavailable catalog values and transfer failure with fixtures. Then have a fluent reviewer check each real prompt during an authorized test call. Check pronunciation, meaning and the receiving team, not just the HTTP response. Keep the wording and catalog selection versioned so a later change does not affect calls already underway.
Related guides
- Build a keypad phone menu with the Voice API
- Collect a spoken response with the IllyVoIP Voice API
- Convert text to speech with the IllyVoIP API and save the audio
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.