Dialplan applications

This guide explains in detail each Dialplan application and provides practical examples and use cases.

Updated: April 2017
WMS Version: 3.84

Basic information on how Dialplan works: Dialplan: How does it work?

List of Dialplan Applications

  • Call control: Answer the Call; Authenticate user; Call through remote PBX; Correct called number; Dial the phone; Dial the trunk; Hangup; Trunk group
  • Services: Automatic callback; Call group; Conference; Dial by name / Directory; Fax to email; Go to voicemail; Intercom; Paging group; Record call; Voicemail access
  • Conditions: Detect fax; Jump to; Jump to if; Jump to if 3 state switch is on; Jump to if call type is; Jump to if congested/busy; Jump to if switch is on; Jump to if user status is; Verify caller; Verify number of calls; Verify timetable
  • Contacts: Lookup called name in phonebook; Lookup caller name in phonebook; Mobility extension lookup
  • Sounds/IVR: IVR; Play sound; Play sound and wait for digits; Wait for digits
  • Set: Set
  • DTMF: Generate DTMF; Generate Flash Hook
  • Other: Custom application; Remote script

Call control

Answer the call: enables the system to answer the call.

Authenticate user: asks the caller for the user password.

  • Set Number: set up the system to ask for the password associated to another user if you indicate another user
  • Set Options: set up the system to ask for the password only if phone is blocked

Example:

dialplan-application-authenticate-user

The caller is asked for the user password and only in case the entered password is correct, the next Dialplan application “Dial trunk” is executed.

Call through remote PBX: routes the call through another PBX of WMS Network. As a rule, this option is used to route the call through the trunk present on the remote PBX at minor cost.

  • PBX: select the PBX from your WMS Network
  • Procedure: enter the Dialplan procedure name to follow, present on remote PBX
  • Set Number: modify the called number (to match the selected Dialplan procedure on remote PBX)
  • Timeout: enter timeout in seconds, in case of no success within the specified timeout, the system proceeds to the next Dialplan application
  • Set Options: provide music on hold instead of ringing tone

Example:
Suppose our local PBX is situated in Italy and remote one in France.
“users” Dialplan configuration on local (Italian) PBX:


In case the French number is entered, the call is routed via a remote PBX located in France, the Dialplan procedure “users”.
“users” Dialplan configuration on remote (French) PBX:


On the remote PBX situated in France, the number is normalized (the first 5 digits standing for the French international prefix are eliminated) and the call is routed via a local trunk.

Correct called number: verifies if the called number contains international prefix, and if it’s the one defined in Dialplan > General settings (“Country Code”). If matched, the prefix is substituted by the parameter indicated in “outgoing prefix”. If the international prefix is not recognized, “+” is eliminated, outgoing prefix and international prefix are added.

  • Outgoing prefix: enter the prefix to be added to called number after it’s corrected
  • Procedure: select the Dialplan procedure to follow after the called number is corrected

Example:

Suppose the international prefix is 39 (Italy). Here is the “users” Dialplan configuration example:

If the called number is +3904611715112, the system removes +39 and adds 0, the number after normalization is: 004611715112 and it matches the number 00[1-9], so the call is routed via the “local” trunk.

If the called number is +380481234567, the system removes + and adds 000 (00 as International prefix and 0 as Outgoing prefix), the number after normalization is: 000380481234567 and it matches the called number 000[1-9] present in Dialplan procedure, so the call is routed via the “international” trunk.

Dial the phone: routes the call to the selected user.

  • Set Number: modify the called number
  • Timeout: enter timeout in seconds, in case of no success within the specified timeout, the system proceeds to the next Dialplan application
  • Set Options: provide music on hold instead of ringing tone
  • Message for operator: click the button “…” to access the Sounds menu of the PBX to be able to select or record the message to be played back to the call group member before the call is answered (this message, for example, can notify an operator present in several call groups, on the type of the call; e.g. one call agent is present both in Tech Support and in Sales group, the message can notify the user that this call is addressed to Tech Support group)

Example:

For instance, call coming from 021234567 must be routed to the user 100: Set number → Custom: 100

Call coming from 021234533 must be routed to the user 133, call coming from 021234532 must be routed to the user 132, etc: “Set number”: “remove – 7”, “prepend digits – 1” (DID management). Here is an example of Dialplan configuration for incoming calls (“main”) in this case:

Dial the trunk: routes the call through the specified trunk

  • Select trunk: Select the trunk from the list through which the call must be routed
  • Set Number: modify the called number
  • Class: assign the call class for this call to manage the permissions via ACL groups
  • Timeout: enter timeout in seconds, in case of no success within the specified timeout, the system proceeds to the next Dialplan application
  • Max calls: specify max number of calls on trunk
  • Set Options: provide music on hold instead of ringing tone

Example:
The options “timeout” and “max number of calls” allow you to decide when to stop dialing one trunk and try another one, here is an example of “users” procedure configuration:


In our example, the system first tries to dial one trunk, in case the timeout of 30 seconds or the maximum number of 2 calls is reached on this trunk, the system tries to route the call via another trunk.

Hangup: enables the system to terminate the call.

Trunk group: routes the call through the specified Trunk group (Read the chapter of WMS Start Guide, dedicated to Trunk groups).

  • Select trunk group: Select the trunk group from the list through which the call must be routed
  • Set Number: modify the called number
  • Class: assign the call class for this call to manage the permissions via ACL groups
  • Strategy: change the order of trunk occupation within the specified hunt group

Services

Automatic Callback: routes the incoming call directly to the user who had made an outgoing call to this number (within one hour) with Dial Status «No Answer».
Note: The CDR must be enabled on the PBX.

Example: User 100 made a call to the number 39123456789 but no one replied. In forty minutes the called party has noticed a missed call and calls the number displayed on the screen (the office number, e.g. 04611715112). The system routes the call directly to the user 100 who had previously made an outgoing call. To do this, we must edit the Dialplan for incoming calls (“main”), by adding the “Automatic Call Back” Dialplan Application to the office number (04611715112):

Call group: routes the call to the selected Call Group. Call Groups are set up in Dialplan > Call Groups (Read the chapter of WMS Start Guide, dedicated to Call groups)

  • Select Call group: select the call group from the list to which the call is routed
  • Message for operator: click the button “…” to access the Sounds menu of the PBX to be able to select or record the message to be played back to the call group member before the call is answered (this message, for example, can notify an operator present in several call groups, on the type of the call; e.g. one call agent is present both in Tech Support and in Sales group, the message can notify the user that this call is addressed to Tech Support group)
  • Timeout: enter timeout in seconds, in case of no success within the specified timeout, the system proceeds to the next Dialplan application
  • Music on hold class: select the music on hold to be played to the caller

Example:

Here is an example of the Dialplan procedure for incoming calls (“main”), where an incoming call to the tech support number is first routed to the tech support group, if no one answered within the timeout of 20 seconds, the call is routed to the sales group:

Conference: puts the call into multiconference.

  • Room number: enter the conference room ID number; in case the the room number with such ID doesn’t exist, it is automatically created.

Examples:
In the first example of the “main” Dialplan configuration, the incoming calls to the number 021234567 are routed to the conference room 123:

The second example demonstrates DISA configuration in which we have three different conference rooms (1, 2, 3) and the caller is asked to enter the number in order to enter each conference room: e.g. caller must enter 11234 to enter the conference room number 1, 11567 to enter the conference room number 2, 11890 to enter the conference room number 3.

By the way, any user of the system can access these conference room by simply dialing a feature code for Conference access (98 by default) + the conference room number, e.g. 981 for conference room number 1.

To enable an external user to participate in the conference without DISA configuration, you can call this external user and then make a blind transfer of this call to the conference (e.g. 981, to enable an external user to participate in the conference with the room number 1).

Dial by name / Directory: invites caller to enter a part of the name or surname for the search and routes the call to the user in case a match is found.

Note: Users can record their names via Service code Voicemail 81 (call 81, press 0 for mailbox options, then press 3 to record your name).

Fax to email: answers an incoming call using FAX Server and sends the fax to email or to the user, indicated in “set”.

Note: In case the number is used both to receive voice calls and faxes, you can add the Dialplan application “Detect fax” before this one.

  • Set email address: specify one or several email addresses (separated by space) where to route the fax
  • Format: select the format (pdf / tiff)
  • ID fax: enter the fax machine ID (to identify faxes received from different numbers)

Example:
Suppose the office fax number is 021234567. Edit the Dialplan for incoming calls (“main”):

You can enter several extension numbers / email addresses into the field, separated by spaces, in this case the copy of received faxes is sent to multiple destinations:


Read the Fax Server Guide for more information on sending and receiving faxes with Wildix Fax Server.

Go to voicemail: routes the call to the voicemail.

  • Set Number: modify the called number
  • Set Options: select to play beep, play busy or unavailable message to the caller

Intercom: the phone indicated in the “Number” field answers automatically in speaker mode enabling the caller to talk to the user without his/her intervention.

  • Set Number: modify the called number
  • Timeout: enter timeout in seconds, in case of no success within the specified timeout, the system proceeds to the next Dialplan application
  • Set Options: provide music on hold instead of ringing tone
  • Message for operator: click the button “…” to access the Sounds menu of the PBX to be able to select or record the message to be played back to the call group member before the call is answered (this message, for example, can notify an operator present in several call groups, on the type of the call; e.g. one call agent is present both in Tech Support and in Sales group, the message can notify the user that this call is addressed to Tech Support group)

Paging group: similar to “Intercom”, but applied to a group of users (Dialplan menu > Paging Groups); the phones of users present in the selected Paging group answer automatically in speaker mode enabling the caller to talk to the users without their intervention (e.g. in this way you can quickly broadcast an urgent message to the group of listeners).

The following Wildix devices currently support Multicast Paging: old generation of WP phones, WP4X0 2015. Devices must be registered to the same PBX and belong to the same network.

  • Paging group: select the paging group from the list

Record call: records the call and sends the record to the specified email/user.

A copy of the conversation is also sent in the folder defined in Storages in Settings menu.

  • Set Options: start recording not before the call is answered
  • Send to email – user: enter the email address or extension number where to send a copy of the call recording

Examples:
To enable call recording of outgoing calls, modify the Dialplan procedure used for managing outgoing calls (e.g. “users”):

In our example the call recording starts as soon as the call is answered (specified in “Set Options”), and the copy of the recording is sent to the email address of user 100.To enable call recording of incoming calls, modify the Dialplan procedure used for managing incoming calls (“main”):

In this case all the incoming calls to the line 021234567 are recorded and the copy of the conversation is sent to the email address info@wildix.com
Note: in Dialplan General Settings it is possible to define whether to save the call recordings in *.wav or in *.mp3 quality.

Voicemail access: accesses the voicemail number specified in “access voicemail number” value. In “Set” (Options) field it is possible to enable Voicemail access without password request.

  • Access Voicemail number: set the user for Voicemail access; if empty, the system requests the extension number
  • Set Options: skip PIN check

Conditions

Detect fax: answers the call and within a timeout specified in “fax detect time” waits for the tones of a remote fax. Usually 3 seconds is enough. If the fax is detected, the call is passed to another procedure with the possibility to change the number.

  • Fax detect time: enter the timeout for fax detection in seconds
  • Continue the execution: if enabled, the Dialplan execution continues without waiting for the number of seconds specified in “fax detect time” field before the fax is detected (to avoid silence while the fax is being detected)
  • Procedure: select the procedure to route the call in case the fax is detected
  • Set Number: modify called number (to match the selected Dialplan procedure)

Example:
Suppose the company phone and fax number is 021234567. Modify the Dialplan procedure used to manage incoming calls:


In our example the system tries to detect fax during 4 seconds, while the execution of the Dialplan procedure proceeds to the next step and the call is routed to the call group. In case within the 4 seconds the fax is detected, the system stops the execution of application “Call group” and the call is forwarded to the called number “fax” (as defined in “Set Number” option), in which the fax is being sent to email info@wildix.in.

Jump to: jump to another procedure with the possibility to modify the number.

  • Procedure: select the procedure to route the call
  • Set Number: modify the called number (to match the selected Dialplan procedure)

Example:
Suppose we have Sales and Tech Support departments and they both use the same trunk for outgoing calls, but they want to receive call recordings to different email addresses (sales@wildix.com and support@wildix.com) and to have different caller number for outgoing calls (04611715111 for sales and 04611715112 for tech support). For this purpose we must create two different Dialplan procedures for managing outgoing calls (users_sales and users_support). Don’t forget to assign these procedures to users belonging to each group in Users, “Dialplan” (by default “users” is set).


In both cases the system starts the call recording of the outgoing call, but the copy of call recording is sent to different email addresses; the caller number set on trunk is different for Sales and Tech support. At the third step “Jump to”, the system routes the call to the Dialplan procedure “users”, where both types of calls (the one made by Sales or by Tech Support department), use the Dialplan application “Dial the trunk”:

Jump to if: jump to another procedure in case matched the condition with the possibility to modify the number.

  • Condition: select from the list of available conditions or enter your own one (read the Guide Smart Dialplan for more information on conditions)
  • Procedure: select the procedure to route the call
  • Set Number: modify the called number (to match the selected Dialplan procedure)

Jump to if 3 state switch is on: verifies the state of the 3 states switch (set up in Dialplan > Timetable / Switch). If the switch is status is ON, the Dialplan routes the call to another procedure and number, otherwise proceeds to the next step.

  • Select switch: select the 3 state switch from the list
  • (is On) Procedure: select the procedure to route the call in case the switch status is “Enabled”
  • Set Number: modify the called number (to match the selected Dialplan procedure)
  • (or Blinking) Procedure: select the procedure to route the call in case the switch status is “Extra”
  • Set Number: modify the called number (to match the selected Dialplan procedure)

Note: it is possible to change the status of the switch by calling a Feature code (94 by default) or by pressing a corresponding BLF button on WP your phone (BLF keys can be added via WMS > Users or via Wildix Collaboration > Settings > Function keys)

Example:
In our example, in case the switch status is ON, the incoming calls are routed to the procedure “Closed”, in case the switch is in status “extra”, the incoming calls are routed to another Dialplan procedure “Mobile_number” (modify the procedure used for incoming calls, “main” by default):

In case the 3 state switch (called “Switch1”) is off, the Dialplan continues its execution and the call is routed to the Call group.

In case the switch status is ON, the call is routed to the procedure “Closed”, where the message is played to the caller that the offices are closed and the caller is invited to leave the Voicemail message.

In case the switch status is EXTRA (blinking), the call is routed to the procedure “mobile_number”, where the call is sent to the predefined mobile number via the GSM trunk.

Jump to if call type is: verifies the type of call, if matched, jumps to another procedure with the possibility to modify the number.

Note: You can set the call type for each contact in Collaboration > Phonebooks > “Type of contact” field

  • Select call type: select the type of call (internal / external / blacklist / whitelist)
  • Procedure: select the procedure to route the call in case of matching the selected type of call
  • Set Number: modify the called number (to match the selected Dialplan procedure)

Note: you can associate each contact to call type in Phonebook (whitelist / blacklist); otherwise, in case you have imported a phonebook from some DB where you have some custom call class, e.g. “myclass”, you can set up this custom call class in “Select call type” section:

14608945_1791186147837121_8183221006914207242_o

Jump to if congested / busy: analyses the status of the call. If the “state” (BUSY, NOANSWER, CONGESTION, CHANUNAVAIL.) corresponds to the call, Dialplan jumps to another procedure with the possibility to modify the number. If no match was found, Dialplan proceeds to the next step.

  • Select Dial status: select the dial status (BUSY, NOANSWER, CONGESTION, CHANUNAVAIL)
  • Procedure: select the procedure to route the call in case of matching the selected dial status
  • Set Number: modify the called number (to match the selected Dialplan procedure)

Jump to if switch is on: verifies the state of the switch (set up in Dialplan > Timetable / Switch). If the switch status is ON, the Dialplan routes the call to another procedure and number, otherwise proceeds to the next step.

The Dialplan application “Jump to if switch is on” works in the same way as “Jump to if 3 state switch is on”, but the usual switch has only two statuses: Off/On (Read the chapter of WMS Start Guide, dedicated to Switches)

Note: it is possible to change the status of the switch by calling a Feature code (93 by default) or by pressing a corresponding BLF button on WP your phone (BLF keys can be added via WMS > Users or via Wildix Collaboration > Settings > Function keys)

  • Select switch: select the switch from the list
  • Procedure: select the procedure to route the call in case the switch status is “Enabled”
  • Set Number: modify the called number (to match the selected Dialplan procedure)

Jump to if user status is: verifies the user status (DND / away) and based on the result routes the call to the specified Dialplan procedure with the possibility to edit the called number

  • DND / away: select the user status
  • Set Number: set up the user extension number whose status you wish to verify
  • Procedure: select the procedure to route the call in case the user status is “DND / Away”
  • Set Number: possibility to specify the called number present in the Dialplan procedure where call is routed

Verify caller: jump to another procedure, if the number or the caller name contains certain symbols.

  • If [caller name | caller number] contains: enter the symbols
  • Procedure: select the procedure to route the call in case the called number / name contains the symbols entered in the field above
  • Set Number: modify the called number (to match the selected Dialplan procedure)

Verify number of calls: jumps to another procedure, if the number of calls exceeds a certain quantity.

  • If more than (active calls): enter the max number of active calls
  • Procedure: select the procedure to route the call in case the max number of active calls specified in the field above is reached
  • Set Number: modify the called number (to match the selected Dialplan procedure)

Verify timetable: checks the timetable status (set up in Dialpan > Timetable / Switch). If the selected timetable’s status is “always on”, the call is routed to the specified Dialplan procedure, if the selected timetable’s status is “check time”, the system checks if the actual date and time matches the intervals specified in the timetable, and if the match is found, the call is routed to the specified Dialplan procedure. If the match is not found or if the timetable’s status is “never active”, the Dialplan execution proceeds to the next step. (Read the chapter of WMS Start Guide, dedicated to Timetables)

  • If matched: select the timetable from the list
  • Procedure: select the procedure to route the call in case the timetable status is “always on” or in case the timetable’s status is “check time” and the actual date and time matches the interval specified in the timetable
  • Set Number: modify the called number (to the one present in the selected Dialplan procedure)

Contacts

Lookup called name in phonebook: searches for the called name in the specified phonebook with the option to modify the called number in case the match is found.

  • Select phonebook: select the phonebook from the list, in which to perform the search
  • Set Number: modify the called number
  • Set Options: search for the exact match

Lookup caller name in phonebook: searches for the caller name in the specified phonebook with the option to modify the called number in case the match is found.

  • Select phonebook: select the phonebook from the list, in which to perform the search
  • Set Number: modify the called number
  • Set Options: search for the exact match

Mobility extension lookup: if the caller number (modifiable via the option “Set – caller number”) corresponds to the mobile number of one of the users, Dialplan jumps to the procedure predefined for the outgoing calls of this user, as if the call was made from this user’s extension number. User is asked to dial the number to call and the call is treated as a usual outgoing call made by this user.

Note: to make it work, make sure that the mobile number is present in User profile (WMS > Users)

  • Set Number: modify the called number (to match the number present in the procedure predefined for the outgoing calls for this user, e.g. Users procedure)
  • Set Options: hang up and make a call back to the user

Sounds / IVR:

IVR: starts the execution of the selected IVR (set up IVR in Dialplan > IVR)

(Read the chapter of WMS Start Guide, dedicated to IVR)

  • Select IVR: select the IVR from the list

Play sound: reproduces an audio file to the user.

(Read the chapter of WMS Start Guide, dedicated to audio messages)

  • Audio file: click the button “…” to access the Sounds menu of the PBX to be able to select or record the message to be played back to the caller
  • Do not answer the call: if enabled, the the Audio file is played without answering the call

Play sound and wait for digits: reproduces an audio file to the user. During the playback, the system analyses the DTMF tones received from the caller and searches for the match to called numbers present in the current Dialplan procedure or in the Included procedures.

  • Audio file: click the button “…” to access the Sounds menu of the PBX to be able to select or record the message to be played back to the caller
  • Do not answer the call: if enabled, the the Audio file is played without answering the call

This Dialplan application is very useful for DISA management, e.g. the message invites the caller to enter an extension number and then the call is routed to the number entered. (Read the chapter of WMS Start Guide, dedicated to DID and DISA (Post Selection) configuration)

With the help of this Dialplan application you can enable external users to participate in the audio conference:

  1. Create a new Dialplan procedure “Conference” and edit a Dialplan procedure for incoming calls (“Main” by default) by specifying an office number devoted to conference management as “Called number” (in our example, 04611715109) and adding an operation “Jump to” – “Conference” procedure:
  2. Edit a Dialplan procedure “Conference”.

An example of configuration for this Dialplan procedure is provided below:

  • The user is invited to enter the PIN code of the conference (Play sound and wait for digits)
  • The system waits for 4 seconds (Wait for digits)
  • In case the user has entered the valid conference PIN number, the call is routed to the conference room (“called number – XXXX” (Conference PIN code), “Jump to” – “pbxfeatures” procedure – “98” (Feature code to access to the conference)
  • In case the user has entered a wrong number, he is invited to try again (Play sound and wait for digits)
  • After the second unsuccessful attempt, the call is hung up (Hangup).

Wait for digits: normally this Dialplan application used to give more time to the caller after the audio file is reproduced

  • For (seconds): enter the timeout in seconds

Set

Set: set up different parameters for the current call

  • Tags: select the tags that that you would like to set for this type of calls

Tags are added in Settings > PBX > CDR, CDR Settings – “Tags”.

Tags can be also set via Wildix Collaboration (read the Wildix Collaboration Guide). Tags set via Collaboration have more priority over tags set up via Dialplan.

  • Language: select the language among the supported ones

In this language the system audio messages are played to the caller

  • SRTP security: enable SRTP security for incoming/outgoing/both call directions
  • Direct RTP: “yes” – direct RTP is used for all devices (you can specify the networks in which direct RTP must be used in SIP-RTP settings); no – direct RTP is turned off for all devices (if not set up via Dialplan, direct RTP is used only for Wildix devices)
  • Codecs: force the usage of selected codec for this type of calls (select codec from the list of supported ones)

Note: you can also manually insert several codecs separated by comma:

  • Music on hold: select the music on hold from the list
  • Type of call: select the type of call to set for these calls (Internal / External / Whitelist / Blacklist)

Type of call can be also set in Wildix Collaboration > Phonebooks, “Type of contact” field

  • Caller name: set the caller name for this type of calls (click “Set”)
  • Caller number: set the caller number for this type of call (click “Set”)

This Dialplan application allows you to rewrite or edit the caller number of the incoming call, it is often used for number normalization (e.g. so that it’s possible to call back the number right away)

  • Caller number on trunk: set the caller number on trunk (click “Set”)
  • Timeout: set the timeout in seconds (select among the available options – 10/20/30 or enter your own value)

Usually used for outgoing calls (“users” procedure) before the Dialplan application “Dial trunk”, allowing you to set the caller number on this trunk.

DTMF

Generate DTMF: generates a DTMF tone

This Dialplan application allows you to insert the DTMF that can be used during a call, for example, in case you are often asked to enter the same code while calling a particular number, via this Dialplan application, you can enable the system to enter the code automatically when calling this number.

Generate Flash Hook: generates Flash Hook

Flash Hook is used for integration with legacy PBX and legacy phones. Read the FXO White Paper to find examples of usage.

Other

Custom application: used to execute custom Dialplan applications, not present in the standard list of Dialplan applications, if recommended by Wildix Support Team or on Wildix Forum.

Read the Smart Dialplan guide to learn more about the use of custom applications for interaction with external software, MySQL server, PHP, CURL request, TAPI, MySQL Microsoft Database.

Remote script: enter the path to the remote script

Example:
Wildix PBXs can interact with external programs via AGI interface. You can create for example, a script that includes a PHP AGI library (already present in the WMS) and execute it via this Dialplan application.

Script example:

agiexapmple1

When this script is executed, the system pronounces the number (1234), reproduces the file (in your script use the name of the audio file that exists on your PBX) and then dials the user (340).

Make sure that the owner is wms (chown) and give the permissions to execute the script (chmod).

Indicate the path to the place where the remote script is located in the Dialplan application:

In our case, when calling 333, the script “php.test” is executed.

Note: This topic on Wildix Forum describes how to run a script from Dialplan via “Custom application”, however with WMS 3.80.x it’s possible to run the same script using the application “Remote script”.

Example of Main procedure configuration

Example of Users procedure configuration

 

    1 Star2 Stars3 Stars4 Stars5 Stars (8 votes, average: 4.38 out of 5)
Loading...