Skip to main content
Classical IVR runs a saved workflow when an assigned number receives a call. Key presses select explicit branches; a phone agent does not interpret them or rewrite your recordings.

​
Enable and create

  1. Open Settings → Voice & Telephony and enable telephony.
  2. Turn on Enable Classical IVR on the same settings page. This makes the IVR trigger and nodes available in Workflows.
  3. Open Channels → Phone. The page contains AI phone agents followed by Classical IVR. Use the Classical IVR section to manage workflows, recordings and phone-number assignments. This section is hidden while Classical IVR is disabled.
  4. Open the WAV recordings tab to upload recordings. In the Workflows tab, select Create IVR. The editor starts with the IVR Incoming Call trigger.
  5. Build the flow, save a version and activate it.
  6. Use Test call in the Workflows tab before assigning a phone number. After testing, use the searchable Phone numbers selector on the workflow row to assign one or more numbers. The selector shows each number’s name and phone number, and you can search by either. Deselect a number to remove its assignment. Numbers assigned to another IVR are labeled; selecting one moves it to this IVR.
Only verified phone numbers can be assigned. Each phone number can have only one inbound destination: an IVR or an AI phone agent. Numbers assigned to a phone agent cannot be selected for an IVR until you unassign them from that agent, and vice versa. Settings → Phone Numbers → Inbound destination shows the assigned IVR or agent name. Assignment changes display Applying routing… while they are saved and applied to incoming calls. The IVR Incoming Call trigger runs only for calls to numbers assigned in the workflow row’s Phone numbers selector. It does not subscribe to other inbound calls, outbound calls or AI phone-agent calls. The workflow list shows each IVR’s assigned numbers in a scrollable table with 10 workflows per page. Use the page controls below the table to browse additional workflows. You need workflow read permission to view flows and recordings, and workflow write permission to upload recordings, edit flows or start a test call. Assigning a number also requires voice-channel settings write permission.
A browser test runs the active flow, including its lookup and session actions. Team transfers ring real available teammates. Use a test organization or test teams when you need isolation.
Turning Classical IVR off preserves workflows, recordings and number assignments. New calls use the number’s usual routing until Classical IVR is enabled again. Changing this setting requires Voice & Telephony write access.

​
Classical IVR nodes

Use existing workflow condition, working-hours, contact lookup and session-note actions alongside these nodes. For example: menu → collect VAT → repeat digits → confirmation menu → contact lookup → team transfer. A VAT match identifies a record; it does not prove the caller is authorized to access it.

​
WAV recordings

Upload mono or stereo WAV files with 16-bit PCM, A-law or mu-law encoding. Supported sample rates are 8, 16, 24, 32, 44.1 and 48 kHz. Files must be at most 20 MB and five minutes long. Unsupported or malformed files are rejected. Uploads are automatically compressed for speech playback. Keep uploading WAV files; no conversion is needed on your side. Each recording is fully loaded before playback, and playback buffers are released when it finishes or is interrupted. Existing uploaded recordings remain playable. Keypad Menu and Collect Digits have two recording selectors: Menu WAV recording plays the main prompt, while Retry WAV recording (optional) plays before a retry after missing or invalid keypad input. Leave the main recording empty to use menu text; leave the retry recording empty to repeat the menu without an extra recording. You can also select Upload WAV recording beside a workflow node’s recording selector. The modal lets you preview a WAV before uploading; the new recording is selected automatically for that node. The recordings table shows 10 recordings per page in a scrollable area. Use the page controls below the table to browse additional recordings. Uploading a recording returns you to the first page. Select Preview to listen before using a recording. Each upload creates a new recording. To replace a recording, upload a new file and select it in a new workflow version. Existing calls keep the workflow version and recording references they started with. For keypad menus, either select a WAV recording or enter fixed menu text and its two-letter language code. A WAV recording takes precedence when both are supplied. Speak Text reads exactly the supplied text; it does not compose a response. When a menu asks callers to choose a language, add a Set Session Language step on each branch with the chosen language code (for example el). Live transcripts of the call are then tuned to that language, and still keep the team’s call languages. See Call languages.

​
Input and retries

  • Menus collect one key. Set Allowed menu keys, for example 1239.
  • Digit collection accepts 1–32 digits. Keep identifiers as text to preserve leading zeros.
  • Input completes when its maximum length is reached or the caller presses the configured finish key. Fixed-length input can use None as its finish key.
  • To accept variable-length input without requiring #, enable Submit after a pause and set Inter-digit timeout (seconds). Once the minimum digit count is met, that pause submits the entered digits. This option is off by default; missing or shorter input still follows the timeout branch. Set the minimum length carefully to avoid treating an incomplete identifier as complete.
  • No-input timeout defaults to 10 seconds; the pause allowed between digits defaults to 5 seconds.
  • Maximum attempts defaults to 3 and can be set from 1 to 5. Use Retry WAV recording to select or upload the recording played after missing or invalid input.
  • Keys may interrupt playback when Allow keys during playback is enabled, once the prompt starts playing. Keys pressed while a prompt is loading are ignored.
  • With Allow keys during playback disabled, callers must wait for the entire prompt before entering input. Use this for instructions that must be heard before a selection, such as consent. The no-input timeout starts after playback finishes.
  • Keys pressed between workflow steps are recorded as ignored; they are never carried into the next menu or identifier. Wait for the next prompt before entering the next value.
Branch explicitly for input, no_input, invalid, inter_digit_timeout and error. With Submit after a pause off, a pause before completion never produces successful input. Retrying collection starts with an empty digit buffer. Route missing or invalid identifiers to your chosen fallback; do not treat an input error as the caller declining consent or cancelling a callback.

​
Voicemail for a team

Record Voicemail is available in IVR workflows after voicemail support has been enabled in your deployment. Existing callback menus require this action to record a message; saving a callback number alone does not start recording.
  1. Upload your voicemail greeting under WAV recordings. Include the instructions for leaving a message; the action plays the tone automatically after the greeting.
  2. Add Record Voicemail after your callback-number selection. Select the greeting and the receiving support team.
  3. Set Callback number to a full international number beginning with +, such as +35722123456, and select Number source:
    • Caller number: map the incoming caller number. If caller ID is withheld or unusable, route to number collection first.
    • Entered number: use Collect Digits, validate and normalize the entered number, then pass the full international number to the action. Keypad entry cannot include +; add it after collecting a country code, or apply the correct country prefix for local input. This callback number does not replace the contact’s saved phone number.
  4. Set Maximum message length (seconds), Wait for speech (seconds), Finish after silence (seconds) and Finish key. Defaults are 180 seconds, 10 seconds, 5 seconds and # respectively. Maximum message length accepts 10–300 seconds.
  5. Follow the action with End Call, optionally preceded by a confirmation on completed or a retry/fallback on error. Complete any required recording-consent steps before this action.
Keep IVR unrecorded controls the full-call recording; Record Voicemail explicitly records the message even when that setting is on. Use that setting when the greeting and menus should also be absent from the separate full-call recording. Only the caller’s incoming audio after the tone is saved. The greeting and other IVR playback are excluded. Recording finishes when the caller hangs up, presses the finish key, reaches the maximum length, or stops speaking for the configured period. Keys pressed during the greeting or tone do not finish the message. The selected team receives an open session containing the callback number and a playable Voicemail card in the call history. Agents need session read permission to view it; calling back uses the usual outbound-call permissions. Ending the phone call leaves the session open for the team to handle. Delivery retries preserve later agent changes. Moving a voicemail session to a different team runs team-change workflows. If delivery reopens a closed session, its history records the system reopen and session-reopened workflows run. Deleting a team preserves its historical voicemail; if the selected team is removed or disabled before delivery, the session appears unassigned for follow-up. An empty message returns no_input: callback details remain available and the card says no spoken message was recorded. Interrupted recordings show an incomplete or failed state and retain any recoverable audio. If the recording process disappears unexpectedly, recovery runs after ten minutes of inactivity. Temporary audio is cleaned up after completion; deleting the session also schedules its voicemail audio for deletion. Configure country-to-team routing in the workflow before this action. The receiving team is explicit and does not depend on the callback number’s country code.

​
Business hours and holidays

Add Get Custom Working Hours to read a named schedule from Settings → Office Hours. Branch on isHoliday for holiday handling, then isNowWithinHours for regular open/closed handling. Use exceptionName in internal notes when useful. Keep dates, recurring holidays and opening periods in the schedule rather than duplicating them in workflow code. See Office hours and holidays.

​
Music and announcements while queued

On Transfer Call, select a team destination whose Telephony pacing is enabled in Settings → Teams. The following settings are optional: Use music, announcements, or both. An announcement requires both its recording and at least one time. To turn announcements off, clear both settings. Leave queue audio unconfigured to preserve the usual transfer behavior. The caller joins the queue once. Music loops and announcements do not change their position, restart their wait, or move them to another team. Announcements interrupt the music; the music restarts from its beginning after each announcement. An agent can accept during either recording, and queue audio stops before the agent connects. For recordings that offer choices, configure Allowed announcement keys to match the recording. The same keypad handling used by Keypad Menu accepts one key during playback or the input window afterward. Invalid keys or no input resume the music without changing the queue entry or waiting time. A valid selection finishes the queued transfer with outcome: input and the selected key in digits. Branch on these values using the existing workflow condition and action steps. For example, configure 1 for a callback offer, then route input with digits: 1 to your callback steps. The caller stays connected while those steps run. Agent acceptance and a key selection cannot both win. Only a valid choice leaves the queue. Audio alone never does. A later Transfer step starts a new queue wait; this does not reserve callback priority after the caller hangs up. Ordinary Keypad Menu and Collect Digits steps retain their existing behavior. The team’s maximum queue wait remains in effect. Announcements scheduled after the queue ends do not play, and the wait is never extended to finish a recording. Overlapping or missed announcement times are skipped. A recording that cannot load does not remove the caller from the queue; the remaining available audio can continue. A playback failure or connection interruption stops queue audio for that transfer while normal call handling continues. Queue audio does not enable recording or change Keep IVR unrecorded, Record human call, private agent whispers, or post-call continuation. Phone-number and SIP destinations do not support these queue-audio settings.

​
Transfers and version changes

Transfer Call uses an existing team, phone-number or SIP transfer destination. Team transfers use the team’s availability and ring settings. By default, an actual teammate joining ends the IVR and leaves the human call connected. When no eligible teammates exist, or nobody answers, the workflow continues with no_eligible_agents or no_answer. Add a callback-choice branch or a closing message for those outcomes. For a carrier handoff, choose a Phone Number destination containing a full international number beginning with +. The incoming telephone carrier must support transferring the call. If that handoff is rejected, configure Keep external call in session to place a separate outgoing call through your verified business number instead. OpenCX does not automatically retry a rejected carrier handoff in this mode. Browser preview calls and extensions are not supported by this IVR action; to keep the caller on the OpenCX call, enable the option described below or use a SIP destination. A successful carrier handoff returns transferred and ends the IVR; it does not confirm that a person answered. A rejected transfer returns error, so add a fallback branch. After handoff, OpenCX no longer controls the remote call’s recording, whisper or queue behavior. Record human call does not control recording after a carrier handoff. For an external call that needs recording or a private recipient whisper, enable Keep external call in session on Transfer Call (bridgeExternalCall: true in workflow input):
  1. Select a Phone Number destination with a full international number.
  2. Ensure the called business number is verified in your organization and has an outbound route. The outgoing call uses that route’s caller ID, not the incoming caller’s number.
  3. Enable Keep IVR unrecorded on the trigger and map Record human call to the caller’s consent. Route a declined consent choice to End Call if consent is required to continue.
  4. While a private whisper transfer connects, the caller hears ringing until the recipient is ready to join. The ringing stops before the recipient joins the caller. Optionally choose an Agent whisper recording of at most 15 seconds. The recipient hears it before joining the caller. The caller never hears it, and it is excluded from the session recording. If the whisper fails, the call ends rather than connecting without it.
  5. Add a branch after the transfer: completed means the recipient hung up; no_answer means no one answered; error means dialing failed. Add End Call, a survey or your chosen fallback. This mode always continues after the recipient leaves, without needing Continue IVR after the human call.
The external conversation stays in the same session and follows the recording consent setting. It lasts at most three hours. If the caller hangs up, the external leg ends too. If recording was already enabled before the transfer, this option cannot remove previously captured audio. Deploy external-bridge support to the backend and phone workers before activating a workflow that uses it; test consent, decline, no answer, whisper privacy and recording on a real call before rollout. Existing external transfers keep carrier-handoff behavior unless you enable this option. For a team transfer, optionally select Agent whisper recording. The picker lists uploaded recordings of at most 15 seconds. After a teammate accepts, the dashboard plays it privately before joining the caller. It is not published into the call or included in the call recording. If the recording cannot be loaded, acceptance continues without an announcement. If browser playback is blocked or fails, the teammate sees a warning and the call connects without the announcement; a stalled playback is limited to 20 seconds. Use headphones and enable browser call audio before testing auto-answer. Switching organizations during the announcement ends the accepted call, so it cannot remain assigned without a teammate. Browser refresh/recovery after joining does not replay the whisper. Activating a new version applies to new calls. Removing a number’s call-flow assignment restores its other configured routing. Unassign a flow from its numbers before deactivating it. Browser tests use your microphone, speakers and the on-screen keypad. They verify the call media and workflow behavior without changing number assignments. A successful browser test does not verify a carrier connection; test a real incoming call before rollout. When an IVR-only call ends, its final status and duration are saved before Phone Call Finished workflows run. The session closes unless the call has entered a Record Voicemail action, which leaves it open for the receiving team. A successful team transfer keeps the human call open until it ends.

​
Transfers to a SIP destination

Choose a SIP destination to connect the caller to an external SIP endpoint, such as an external virtual assistant or another contact center, without handing the call away. The caller stays on the OpenCX call while the destination talks to them, so the session keeps one call, one recording and one transcript, and the IVR decides what happens next: The destination is hung up as soon as its hand-back is accepted, before the next step runs, so it never hears the rest of the call; if it cannot be hung up, the call ends instead of continuing. A hand-back is accepted only after the destination answered. If the caller hangs up during the transfer, the destination is hung up too and the flow ends. A transfer lasts at most three hours. Recording follows the same rules as a team transfer: with Keep IVR unrecorded enabled, the answered transfer is recorded only when Record human call is true, and the recording continues after a hand-back into the teammate’s call. When the destination hangs up and the flow continues, the recording stops first, as it does before a post-call survey. When live transcripts are enabled for your organization, the destination’s speech appears in session history under the destination’s name.

​
SIP headers from the workflow

Use SIP headers (optional) on Transfer Call to send values from earlier steps, such as the dialed number from the trigger or a customer tier from a lookup, as custom X- headers. Headers apply to external phone and SIP transfers.
  • Every transfer carries the session ID as X-OPENCX-SESSION-ID, unless a SIP destination’s allowed headers leave it out. Destinations that hand calls back need it, so add it to their list.
  • A header whose value is empty when the step runs is not sent. Names must start with X- and cannot start with X-OPENCX-; values are up to 255 printable characters; a step can set up to 20 headers.
  • A header the SIP destination already sends from its own settings cannot be set again by the workflow, and neither can X-Zendesk-Ticket-Id, which comes from the session.
  • With Keep external call in session enabled, workflow headers also cannot replace headers saved on the selected outbound trunk. Header names are compared without regard to capitalization.
  • A SIP destination with Send only allowed headers receives only the names on its list, the session ID included. SIP transfers send no other headers: not the organization’s internal identifiers, and not the headers that arrived on the caller’s call.
Configure caller ID, encryption and allowed headers on the destination; see SIP transfer destinations.

​
Transfers to an AI phone agent

Add Transfer to AI phone agent to let one of your AI phone agents talk to the caller, then bring them back to the menu. The caller stays on the same call and session; the agent greets them with its own first message.
  • Phone agent: any phone agent in your organization. Map it from an earlier step to choose the agent while the call runs.
  • Context for the agent (optional): added to the agent’s instructions for this call only, such as the menu choice or account number the caller entered. The agent knows nothing else about the menu, so pass what it needs here.
While it holds the caller, the agent can return them to the menu. The step’s reason output carries the agent’s own words, so later steps can route on it. If the caller hangs up while the agent is talking, the IVR ends there, as it does for other steps. A step that gets no result within 24 hours continues with error. The session stays with the IVR and closes when the call ends, like other IVR calls. AI voice minutes count only while the agent is on the call, not the time in the menu. If the IVR is recording the call, that recording includes the agent’s part. With Keep IVR unrecorded enabled, the agent’s part is not recorded. Otherwise the agent records according to its own Record calls setting. While the menu is waiting for it, the agent cannot switch the caller to another AI phone agent; it returns them to the menu instead. To hand callers between agents outside an IVR, see AI phone agent handovers. Test the step with a browser test call: confirm the agent greets with its first message, use the context you passed, return you to the menu, and that each outcome reaches the branch you expect.

​
Post-call keypad surveys

For team transfers, enable Continue IVR after the human call on Transfer Call. The IVR stays silent while the teammate speaks with the caller. When the teammate clicks End call, the teammate leaves and begins their normal wrap-up; the caller stays connected to hear the following IVR steps. The human-call recording is stopped before the survey starts. Call duration includes the caller’s time in the survey; teammate wrap-up starts when the human call ends. Build the survey in the same incoming-call workflow:
  1. Optionally play your survey invitation before Transfer Call.
  2. Enable Continue IVR after the human call on the team transfer.
  3. Branch on the transfer outcome. Run the survey only for completed; keep your existing fallback for failed or unanswered transfers.
  4. Add a Keypad Menu using your rating recording, allowed keys 12345, and finish key None. Configure missing-input and invalid-input branches separately.
  5. On input, add Save Keypad CSAT Rating and supply that menu’s step ID. It reads the accepted digits from this run; it cannot submit an arbitrary score or use another session’s input.
  6. Play your acknowledgement recording, then End Call. End missing or invalid responses without creating a rating.
Enable Phone in your CSAT settings before saving keypad ratings. This action saves the rating in native CSAT reporting and session history, with the session’s assigned teammate and team at submission time. It does not send an SMS. Review any resolution-triggered Send CSAT workflows and exclude phone sessions if you only want keypad surveys; those message actions still use SMS for phone sessions. Continuation requires an explicit End call from the teammate. If the caller hangs up first, the survey is cancelled. A browser disconnect allows a 30-second reconnection period; it does not immediately start the survey. If the teammate does not reconnect and no continuation arrives, the call ends. External carrier handoffs do not support continuation. External calls with Keep external call in session enabled continue after the recipient hangs up. If the survey cannot start safely, End call still ends the call and starts teammate wrap-up. If another End request is already processing, a conflicting request can report an error; retry after that request finishes. Leave continuation off for calls that should end normally. Activate and test a new workflow version only after the post-call capability is available. Test teammate-end, caller-end, invalid input, missing input, recording behavior and saved scores before assigning live numbers.

​
Companion and API

Companion can author the same ivr-incoming-call workflows and use the Classical IVR node definitions. It can list/upload recordings and assign an active flow to a number. Review the flow before activation and number assignment. API access uses workflows:read for listing recordings, workflows:write for uploading, and both phone:write and workflows:write for number assignment. Use existing workflow endpoints to create versions, validate and activate them. A SIP destination returns callers with phone-calls:write.

​
Session history and call recordings

Open the call’s session in Inbox to review the IVR. By default, recording includes the IVR and continues if the caller reaches a teammate. Recording availability depends on recording being enabled and processing completing successfully. To collect recording consent without recording the menu:
  1. Enable Keep IVR unrecorded on the IVR Incoming Call trigger.
  2. Collect consent with a keypad menu and branch explicitly on the caller’s choice. Use a recording that explains that declining recording still connects the call.
  3. Continue both choices to Transfer Call. Set Record human call to true only for an explicit acceptance. Set it to false for declined, missing or invalid consent.
With this setting enabled, recording starts only after a teammate accepts an approved transfer. Declining recording does not prevent routing or disconnect the caller. Without Record human call enabled, the accepted transfer stays unrecorded. Later teammate transfers in that same call keep the original recording decision. The call keeps the settings of the workflow version it started with. Leaving Keep IVR unrecorded off preserves recording from the beginning of the IVR; a consent menu or transfer setting alone cannot undo audio already captured. This setting controls audio recording, not separately configured live transcripts. Each IVR run appears as one IVR selection event in session history, collapsed by default. Expand it to review the timestamped prompts, key presses, and outcomes together. Actions are emphasized and long details are truncated; hover over or focus a step to read its full details:
  • Prompt playback starts show the exact text or the uploaded recording’s name. A start does not mean the caller heard the entire prompt.
  • Key presses show the key, the associated menu prompt, and the attempt number. The event identifies keys that interrupted the prompt or were ignored while keypad input was disabled, including loading and transitions. A transition key is associated with the preceding command; it is not input to the next step.
  • Each attempt records its result, including invalid input, no input, or a timeout between digits. Retry prompts appear inside the same expandable event.
When IVR recording is enabled, play the session’s call recording to hear the audio around a selection. With Keep IVR unrecorded enabled, use the IVR selection events to review that portion of the call. Keep session events visible when reviewing session history. IVR selections stay grouped even when Group similar events is turned off. These entries are internal and are not sent to the caller. History is captured for new calls; earlier calls cannot be reconstructed from final workflow results alone.

​
Troubleshooting

If Classical IVR is missing, check both telephony and Classical IVR enablement and your workflow permissions. If a recording will not play, check its preview and the call’s workflow run. If a transfer fails, check the destination’s team, available membership, business hours and call capacity. For a SIP destination, run Test connection on the destination, and check that the endpoint accepts the caller ID and headers it is sent. A hand-back that returns 409 arrived after the transfer ended; check the transfer’s outcome in the workflow run. Use the IVR selection event and workflow step results to distinguish invalid input, lookup results and transfer failures.