Learn the essential rules for building error-free IVR flows. This guide ensures your IVR designs are logical, efficient, and aligned with system behavior.
When building IVR flows, ensure these rules are followed to prevent errors and maintain smooth operation.
📘
NOTE
Primary and alternate paths are represented by green and red dots, respectively, within an element. 📘 Example: once a call enters the queue and is answered by an agent, we can hang up after the call. However, if no agent is available, the caller will hear a message explaining the unavailability and prompting them to leave a voicemail after the beep.
Illustration of the primary and alternate paths
Every IVR flow must begin with the Start element.
All IVR flows should end with the Hangup element. If omitted, the default action will be to terminate the call automatically.
Each element (except Hangup) must include at least one primary path.
Primary paths are triggered based on the element’s logic. For instance, in the Playback element, the primary path is activated once the playback file completes.
The number of primary paths is limited by the element logic.
📘 Example:
The Playback element allows one primary path.
The Menu element permits up to ten primary paths, one for each digit.
Alternate paths are restricted to one per element and are only available for specific elements. These connections are triggered when the element logic encounters an error.
Any missing logic in an IVR flow will immediately terminate the call.
📘 Example:
If a Playback element lacks a primary path, the call will end after the playback file finishes.
Reference on IVR Elements
The following sections outline the technical functionality and behavior of each IVR element within the system and explain their parameters and logic.
Start
Description
Image
Start is a default element that marks the beginning of the IVR flow and must initiate each flow.
📘 A webhook with the calling action will be triggered here.
Answer
🚧
Answer Call Must Exist Before Certain Elements
Our system must answer the call first to enable features such as call recording, real-time media processing (e.g., transcoding or inserting announcements), and advanced routing. This requirement exists because RTP (media) becomes available only after the call is answered. Before that, only signaling (SIP messages) occurs.
If the call is simply passed through without being answered, media flows directly between the endpoints, preventing our system from processing or modifying the audio. By answering the call, the system actively participates in media handling, making these advanced features possible.
Description
Image
Answer indicates that the system detects and accepts an incoming call.
🟩 The primary path will be triggered if the call is successfully answered; otherwise, the call will hang up.
📘 Most elements, like bridging the caller to an agent, need media, so
“answer” elements must exist before any media-dependent elements.
PreAnswer
Description
Image
PreAnswer notifies the agent that an incoming call is about to be received.
🟩 The primary path is triggered if the call is successfully pre-answered; otherwise, the call will hang up.
Hangup
Descriptions
Image
Hangup ends the call from the IVR side. This element is always placed at the logic's end and does not allow any elements after it.
📘 A webhook with the hangup action will be triggered here.
Sleep
Description
Parameters
Image
Sleep inserts a pause, allowing the client to wait for the connection. The caller will hear silence during the pause.
- Seconds: Set the number of seconds after which the 🟩 primary path will be triggered.
Playback
Description
Parameters
Image
Playback sequentially plays specified audio messages for the client.
A 🟩 primary path is triggered after all files have finished playing.
- Playbacks: Select a playback recording from the drop-down list.
- Click Add to add more recordings.
Record
Description
Parameters
Image
Record enables call recording and stops recording after the specified
Max Length seconds or upon detecting silence for the
Silence Length duration. The recording is saved to the call extension data.
- Max Length: Define the recording duration in seconds.
- Silence Length: Define the silence duration in seconds.
A 🟩 primary path is triggered after the recording is finished.
Transfer
Description
Parameters
Logic
Image
Transfer redirects the call to a different DID.
- Destination: Must follow the format sofia/internal/{extension} or sofia/external/{SIP URI}.
Destinations that do not start with sofia/ will be converted to sofia/internal/{destination}.
❗Set a destination following the same logic as when setting **Campaign SIP Forward URIs**.
- Destination in variable: Retrieve the destination URI from an existing value in the incoming call channel.
- Waiting recording: Select a recording file from the drop-down list. It will play until the destination is answered.
- Timeout: Set a number of seconds after which an 🟥 alternate path is triggered if the call is not answered.
IVR automatically starts recording the call and bridges the caller to the destination once it is answered.
When the call ends, the recording will stop.
- A 🟩 primary path is triggered if the destination URI is successfully answered.
- An 🟥 alternate path is triggered if the destination URI is not answered.
Transfer to IVR
Description
Parameters
Image
Transfer to IVR starts a configured IVR logic without requiring a prefix or DID.
This function bypasses external calling and starts running the logic of the configured IVR elements.
A 🟩 primary path is triggered after the logic of the transferred IVR finishes.
- Destination: Select a configured IVR from the drop-down list.
Menu
Description
Parameters
Image
Menu plays a file and allows the caller to press a digit (0-9) to trigger up to 10 🟩 primary paths.
🔹 Allowed DTMFs: Digits 0-9 (single-digit input only).
🟩 A primary path is triggered when the caller presses a valid DTMF.
🟥 An alternate path is triggered after the maximum attempts or timeout is reached.
- Max attempts: Number of incorrect DTMFs allowed before the 🟥 alternate path is triggered.
- Timeout: Seconds after prompt playback ends. If the caller doesn’t input a digit, the prompt replays until max attempts are reached.
- Prompt recording: Select an audio file to play when the menu starts.
- Error recordings: Select an audio file to play after each incorrect DTMF input.
Connect to Groups
Description
Parameters
Logic
Image
Connect to Groups bridges the caller to an available agent from a selected user group.
🔍 How it operates:
- Searches for available agents based on the selected group and search type.
- If no agents are found, an 🟥 alternate path is triggered.
📘 A webhook with the bridge action will be triggered here.
- Groups: Select a user group to search for agents.
- Timeout: Define seconds to wait before stopping the connection attempt.
- Found agent recording: Select an audio file to play when an agent is found.
- Waiting recording: Select an audio file to play while dialing agents.
- Search type: Choose between Online only or Online + Offline (includes agents via softphone, PBX, or WebRTC).
- Exit key: Select a DTMF key that allows the caller to exit the queue.
1️⃣ If no available agents are found, trigger an 🟥 alternate path.
2️⃣ If agents are found, play the **Found agent recording**.
3️⃣ Start recording the call after playback finishes.
4️⃣ Dial all available agents in parallel, triggering the **Waiting recording**.
5️⃣ If timeout is reached or the exit key is pressed, trigger an 🟥 alternate path.
6️⃣ The first agent to answer gets bridged with the caller.
7️⃣ If no agents answer, an 🟥 alternate path is triggered.
8️⃣ If the call is bridged or ends, a primary path is triggered.
❗ **Only agents with valid SIP URI, PBX extension, or WebRTC can be connected.**
❗ **Online agents are always prioritized in the search.**
Connect to Users
Description
Parameters
Image
Connect to Users works similarly to Connect to Groups, but instead of searching for agents within a group, it searches based on a specified user list.
🔍 How it operates:
- Routes an incoming call to the selected users as a ringing group.
- Defines a timeout period for searching available agents.
- If no agents are found, an 🟥 alternate path is triggered.
📘 A webhook with the bridge action will be triggered here.
- Users: Select a user to connect with the caller.
- Timeout: Set a duration in seconds to stop trying to connect the caller.
- Found agent recording: Select an audio file to play when an agent is found.
- Waiting recording: Select an audio file to play while attempting to connect.
- Search type:
- Online only: Agents who are clocked in.
- Online + Offline: Includes all registered agents (softphone, extension, WebRTC) regardless of clocked-in status.
- Exit key: Select a DTMF key to allow the caller to exit and trigger an 🟥 alternate path.
Connect to Assigned User
Description
Parameters
Logic
Image
Connect to Assigned User functions similarly to
Connect to Users,
but searches for an agent based on lead assignment.
🔍 How it operates:
The IVR looks up the most recent campaign lead assigned to an agent based on the caller ID.
If a match is found, it attempts to bridge the call to the assigned user.
If no lead is found, an 🟥 alternate path is triggered.
📘 A webhook with the bridge action will be triggered here.
Timeout: Set the maximum duration (in seconds) to attempt connecting the caller.
Found agent recording: Select an audio file to play when an agent is found.
Offline agent recording: Select an audio file to play when an assigned agent is offline.
Waiting recording: Select an audio file to play while trying to connect.
Search type:
Online only: Agents currently clocked in.
Online + Offline: Includes all agents (softphone, extension, WebRTC) regardless of clocked-in status.
Exit key: Select a DTMF key to allow the caller to exit and trigger an alternate path.
Search for the most recent lead with assigned_user_permanent = 1.
Ensure the assign_user field is not empty.
Match any of the phone fields (phone, phone2, phone_normalized, or phone_normalized2) with the caller ID.
If no lead is found, an alternate path is triggered.
If a match exists, follow the Connect to Users logic.
If no caller ID is present, an alternate path is triggered.
Connect to User Virtual Extension
Description
Parameters
Image
Connect to User Virtual Extension functions similarly to
Connect to Users,
but searches for an agent based on their virtual extension.
🔍 How it operates:
The IVR searches for an agent using a specified virtual extension.
If an agent is found, it attempts to bridge the call.
If no matching extension exists, an 🟥 alternate path is triggered.
📘 A webhook with the bridge action will be triggered here.
User extension in a variable: Define a user extension the IVR should search for (refer to the Set Variable element).
Timeout: Set the maximum duration (in seconds) to attempt connecting the caller.
Found agent recording: Select an audio file to play when an agent is found using the extension ID.
Offline agent recording: Select an audio file to play if the agent is unavailable or unreachable.
Waiting recording: Select an audio file to play while the system tries to connect the caller to the agent's URI or extension.
Search type:
Online only: Agents currently active and clocked in.
Online + Offline: Includes all agents (softphone, extension, WebRTC) regardless of status.
Note: If the user extension does not exist, an alternate path will be triggered.
Connect to Call Center Region Users
Description
Parameters
Image
Connect to Call Center Region Users connects the call
in a ringing group methodology to all users
associated with the selected call center region.
🔍 How it operates:
The IVR searches for all users in the selected call center region.
It attempts to bridge the call using a ringing group method.
If no agents are found, an 🟥 alternate path is triggered.
📘 A webhook with the bridge action will be triggered here.
Call Center Region: Select a call center region in which to search for agents.
Timeout: Set the maximum duration (in seconds) to attempt connecting the caller.
Found Agents Recording: Select an audio file to play when agents are found in the group based on the search type.
Waiting Recording: Select an audio file to play while attempting to connect the caller to agents.
Search Type:
Online only: Includes only currently active and clocked-in agents.
Online + Offline: Includes all agents (softphone, extension, WebRTC), regardless of status.
Exit Key: Select a DTMF key to allow the caller to exit and trigger an alternate path.
Lead Exists and Matches Fields
Description
Parameters
Logic
Image
Lead Exists and Matches Fields verifies whether the lead is valid and not fraudulent.
🔍 How it operates:
The IVR searches for a lead using the Caller ID and optional filters.
The search is conducted using the most recent lead where the Caller ID matches one of the following fields:
phone
phone2
phone_normalized
phone_normalized2
Allowed Fields: Static lead fields.
Filter By:
Equal
Not Equal
Begins With
Ends With
More Than
Less Than
Multiple filter conditions are combined using the "AND" operator, meaning all conditions must be true for the lead to be considered a match.
The Dialer searches for the most recent lead that matches the Caller ID.
If filters are set, they are applied using the "AND" aggregation.
If no lead is found, an alternate path is triggered.
If the Caller ID does not exist, an alternate path is also triggered.
Lead in Campaign
Description
Parameters
Logic
Image
Lead in Campaign? checks whether the lead is part of a specific campaign.
🔍 How it operates:
The IVR searches for the most recent campaign lead using the Caller ID.
The search compares the Caller ID with the following fields:
phone
phone2
phone_normalized
phone_normalized2
Campaigns: Select campaigns from the drop-down list.
The Dialer searches for the most recent campaign lead that matches the Caller ID.
If a lead is found, the Dialer checks whether its campaign ID is included in the selected campaigns list.
If no lead is found or the Caller ID does not exist, an alternate path is triggered.
Caller Prefix Related to Country
Description
Parameters
Logic
Image
Caller Prefix Related to Country determines whether the call originates from an allowed country before forwarding.
🔍 How it operates:
Identifies the country based on the Caller ID prefix.
Matches the Caller ID against a predefined list of countries.
Uses simple phone prefix detection, though some non-standard prefixes may not be recognized correctly.
Countries: Select allowed countries from the drop-down list.
The Dialer attempts to match the Caller ID prefix to an allowed country.
If the Caller ID does not exist or cannot be matched, an 🟥 alternate path is triggered.
Called via DID
Description
Parameters
Image
Called via DID identifies the DID through which the incoming call enters the flow.
🔍 How it operates:
Checks if the destination number (the number called from the IVR) matches any in the provided DIDs list.
DIDs: Search for a Caller ID and select it.
The DIDs can be set as a comma-separated list without spaces, such as 4477123456,12125551211.
Input
Description
Parameters
Usage Example
Image
Input triggers an action based on the lead's input.
🔍 How it operates:
Allows the caller to input digits.
The entered digits are stored in a specified variable name.
This variable can be used in subsequent IVR elements.
Max attempts: The number of retries the caller can attempt to set a value.
Timeout: If the caller does not provide input within the specified time (in seconds), an 🟥 alternate path will be triggered.
Prompt recording: Select a recording to play before the caller sets the value.
Error recordings: Select a recording to play after each invalid or disallowed input.
Variable name: Enter the variable's name where the caller’s input will be saved.
Max digits: Specify the maximum number of digits the caller can enter (minimum: 1, maximum: 20).
The system plays a message: "If you know the agent extension, enter the 4-digit extension now."
The caller enters 1005, which is saved in the variable extension_number.
The extension_number variable can be used in subsequent elements.
For example, the Connect to User Virtual Extension element can use extension_number to connect the caller to the correct agent.
Set Variable
Description
Parameters
Image
Set Variable defines a variable name and value within the IVR settings.
🔍 How it operates:
Allows storing values dynamically within the IVR.
These values can be referenced later in the call flow.
Variable Name: Enter the name of the variable.
Variable Value: Enter the value assigned to the variable.
Send Report
Description
Parameters
Logic
Image
Send Report sends an email to the lead at the end of the process.
🔍 How it operates:
After the call ends, an email containing call details is sent.
Optionally, the Dialer can search for an agent using a virtual extension variable.
User Extension in Variable: (Optional) Enter a variable for the Dialer to search for an agent based on a virtual extension value.
Default Email: Specify an email address.
The Dialer sends an email with call details after the call ends.
If User Extension Variable is set, the Dialer searches for an agent based on this virtual extension value.
If a user is found:
The email will be sent to the default email configured in the element.
Additionally, it will be sent to the email address specified in the user's settings.
Variable
Description
Parameters
Image
Variable? checks if a variable matches a specified value.
🔍 How it operates:
The IVR verifies whether a predefined variable contains a specific value.
If the condition is met, the workflow proceeds along the 🟩 primary path.
If not, an 🟥 alternate path can be triggered.
Variable Name: Enter the name of the variable.
Variable Value: Enter the value the variable should be compared against.
User Virtual Extension Exists
Description
Parameters
Logic
Image
User Virtual Extension Exists? detects the user extension based on the value set in the Variable.
🔍 How it operates:
The system checks if the specified variable corresponds to a valid user virtual extension.
If a match is found, the workflow follows the 🟩 primary path.
If no match is found, an 🟥 alternate path is triggered.
Variable Name: Enter the name of the variable containing the extension.
If the user exists, a 🟩 primary path is triggered.
If the user does not exist, an 🟥 alternate path is triggered.
Say Digits From Variable
Description
Parameters
Logic
Image
Say Digits From Variable announces the digits stored in an existing variable.
🔍 How it operates:
If the caller sets the user extension using the Input element, the IVR can announce the digits the caller just entered.
This helps confirm the input before proceeding to the next step.
Variable Name: Enter the name of the variable containing the digits.
The IVR retrieves the digits stored in the specified variable.
The system announces these digits to confirm the caller's input.
This step ensures the caller has entered the correct information before proceeding.
Enter Queue
Description
Parameters
Image
Enter Queue bridges the caller to a specific agent queue configured under
Inbound Configurations > Queues Management. This element works similarly to
Connect to Users, but only agents assigned to the selected queue can receive the call.
🔍 How it operates:
The caller remains in the queue until an agent becomes available.
If no agent is available within the timeout period, an 🟥 alternate path is triggered.
Optionally, the caller can press an exit key to leave the queue.
Queue: Select the queue for the caller.
Announce Exit: Choose a recording to play before the caller exits.
Timeout: Enter the number of seconds to wait before stopping the queue attempt.
Exit Key: Specify a DTMF key the caller can press to leave the queue.
Search Type:
Online Only – Assigns calls to agents who are actively online.
Online + Offline – Includes agents registered via softphone, extension, or WebRTC.
Enter Personal Queue
Description
Parameters
Image
Enter Personal Queue forwards the call to the agent's personal queue. The Dialer initiates a call to the agent, and once the agent answers, they are bridged with the incoming caller.
While the caller is waiting (e.g., the agent is unavailable or on another call):
The agent sees an indicator on the Dialer page showing waiting callers.
The agent can view live details of the waiting caller.
User: Select a user to bridge with the caller.
Announce Exit: Choose a recording file to play.
Playback: Select a recording file to play.
Exit Key: Specify a DTMF key that, when pressed, will trigger an 🟥 alternate path.
Timeout: Enter the number of seconds after which the system stops trying to connect the caller to agents.
Search Type: Choose between:
Online Only: Connects to agents who are currently online.
Online + Offline: Includes agents registered via softphone, extension, or WebRTC.
Enter Personal Queue for User Virtual Extension
Description
Parameters
Image
Enter Personal Queue for User Virtual Extension functions like
Enter Personal Queue but specifies the agent via their virtual extension.
User Extension in Variable: Enter the extension.
Announce Exit: Select a recording file from the drop-down list.
Send SMS
Description
Parameters
Logic
Image
Send SMS sends a predefined message using a selected SMS template.
It sends an SMS using a template containing call and lead details.
The SMS is sent to the lead based on the detected Caller ID.
If the Caller ID is not detected, an 🟥 alternate path is triggered.
If the Caller ID is detected but the lead is not found, the SMS will still be sent,
but without any lead details.
Communication channel SMS event: select an event from the drop-down list.
The SMS is sent to the lead based on the detected Caller ID.
If the Caller ID is not detected, an 🟥 alternate path is triggered.
If the Caller ID is detected but the lead is not found, the SMS will still be sent, but without any lead details.
Save Missed Calls
Description
Parameters
Logic
Image
Save missed calls
User: Select an option from the drop-down list.
Queue: Select an option from the drop-down list.
Phone Verification Prompt Playback: Select an option from the drop-down list that will prompt the caller to confirm the dialed number.
Callback Time Prompt Playback: Select an option from the drop-down list for the system prompt that will allow the caller to select a preferred callback time.
The Queue input is currently not in use.
The phone verification prompt playback starts. The system plays a prompt stating:
"To confirm the dialed number (IVR will say the number to the user), press 0. Otherwise, please enter your phone number."
The caller either presses 0 or enters their phone number.
After providing the phone number, a callback time prompt is played.
The caller selects their preferred callback time by entering one of the following options (default is 9 - Any):
1: Morning
2: Noon
3: Evening
9: Any
The caller is prompted to enter a user ID.
The IVR attempts to detect the user based on the entered ID.
If no user is selected, the IVR tries to detect an extension based on a predefined variable.
Not completed calls are saved on the Dialer page under Workplace > Recent Calls > Missed Calls.
Calling Hours
Description
Parameters
Logic
Image
Calling Hours checks if the current time falls within the calling hours specified in the element.
Timezone: Select a timezone from the drop-down list to determine whether the current time falls within the configured calling hours.
From: Set the starting point of the configured calling hours.
Till: Set the ending point of the configured calling hours.
If the current time falls within the configured calling hours gap, a 🟩 primary path will be triggered.
If the current time is outside the specified calling hours gap, an 🟥 alternate path will be triggered.
Caller Is a Contact
Description
Parameters
Image
Caller is a contact? verifies whether a caller identified by a Caller ID exists in the Dialer and is associated with at least one user within the Dialer.
User: Select an option from the drop-down list.
Voicemail
Description
Parameters
Logic
Image
Voicemail will save the recording and send it to the provided email.
Playback: Select a recording file the drop-down list.
Max Length: Define the recording duration in seconds.
Silence Length: Define the silence duration in seconds.
Email: Enter an email address.
The customer will first hear the provided playback.
Then, the recording session will begin and will automatically end when one of the following occurs:
The recording reaches the maximum length.
There is silence for the configured duration.
The customer hangs up.
Send Remote Request
Description
Parameters
Logic
Image
Send Remote Request will Send a request to a remote URL, allowing placeholders for lead details.
Request:
Method:
Send WhatsApp Business
Description
Parameters
Image
Send WhatsApp sends WhatsApp messages via the communication channel event, including call and lead details. If the caller ID is detected but no lead is found, the message will be sent without lead details.
Communication channel: Select a channel from the drop-down list.
Send Email
Description
Parameters
Image
Send Email sends a predefined message using a selected email template. It sends an email via the communication channel event. If the Caller ID is detected but no lead is found, the email will be sent without lead details.
Mail template: Select a template from the drop-down list.
Send Telegram
Description
Parameters
Image
Send Telegram sends a Telegram message via the communication channel event. If the caller ID is detected but no lead is found, the message will be sent without lead details.
Communication channel: Select a channel from the drop-down list.
Loopback
Description
Parameters
Image
Loopback allows you to manually draw connection lines to create custom connections and loops.
