| Option | Meaning | Default |
| Announce Balance | Whether to announce balance upon successful start of application | Yes |
| Normal Calls Are Allowed | Only service codes enabled if this option is False | True |
| Disconnect On Failure | Whether to drop the Calling Card session upon unsuccessful call attempt. Otherwise the application announces that the failure occurred and offers the user to enter another destination. | No |
| Allow Empty PIN | Whether to permit to use the prepaid card accounts with empty PIN | True |
| Preserve Original CLI | CLI from the initial call leg will be used to call destination if this option set to true. The calling card username will be used as CLI otherwise. | False |
| Maximum Call Duration | Maximum call duration | 3600 seconds |
| Card Number Length | Maximum number of digits allowed in a card number | 10 |
| Number_Of_Attempts_To_Enter_A_Card | Maximum number of attempts to enter card number or PIN code | 3 |
| Number Of Wrong Destinations | Maximum allowed number of unsuccessful call attempts in a row | 3 |
| Number Of Timeouts | Maximum number of input timeouts | 3 |
| Minimum Call Duration | Minimum allowed call duration (in seconds). If calculated maximum duration of the call to the requested destination is less than this value then the user will hear the prompt "You have insufficient funds to make this call" | 10 |
| Minimum Card Number Length | Minimum number of digits allowed in a card number | |
| No Seconds In Duration | Do not pronounce seconds while announcing call duration. If the duration is less than 1 minute then this option is ignored. | False |
| No Hours In Duration | Do not speak out hours while announcing call duration, only minutes | False |
| Announce Duration | Should the duration of the call be announced | True |
| Call Several Destinations | Only one call attempt per session is allowed if this option is False | True |
| Outbound SIP Proxy | SIP proxy host:port to send the outbound calls to (this option can also be set from the command line) | <Environment_IP>:5061 |
| Disconnect Warning Time | Say 'Your call will be disconnected in N seconds' before the call disconnect | 60 |
| Play Service Plan Minutes Only | Play service plan minutes instead of a sum of plan minutes and duration calculated by tariff. This option does not affect actual maximum duration of a call which is a sum of plan minutes and duration calculated by tariff. | False |
| Destination Number Completion Regex | Treat the destination number to have been completed and immediately continue with the call when the input matches the given regular expression pattern | |
| Allow Own Accounts Only | Usage of Calling Card application in scope of one customer who owns this application. The option is not restricted to Calling Card application only, it is applicable to every IVR application. (Available from 4.4 only). | False |
Trusted CLI related options
| Option | Meaning | Default |
| Enable CLI Registration | If the CLI Registration subapplication enabled | True |
| Automatic CLI Registration | After calling card has been entered successfully, add the current CLI to the list of trusted CLIs for this calling card. | No |
| Silent Automatic CLI Registration | When this option is set to False the user will be prompted if he wishes to register his phone number (new in 1.7.1). | True |
| CLI Registration Menu Extension Number | Extension number for the CLI Registration Subapplication | |
| Trusted CLI Authentication | CLI mapping is trusted so the PIN is never asked | False |
| Minimum Valid CLI Length | Minimum CLI length that is allowed to trigger the Automatic CLI Registration. | 6 |
Password change
| Option | Meaning | Default |
| Enable Password Change | If password change enabled | True |
| Change Password Menu Extension Number | Extension number for the Change Password Subapplication |
Billing related options
| Option | Meaning | Default |
| Balance Threshold | If the balance of the card is below this threshold then the card number will be asked even if CLI authentication is successful. Please note that this option doesn't disable cards with the balance below threshold, it just forces the PIN to be entered despite the fact the CLI authentication was successful. If you want to disable cards with low balance, please use the Minimum Balance option. (new in 1.8) | The value of the Minimum Balanceoption |
| Minimum Balance | If the balance of the card becomes less than the specified value then the card becomes unavailable. The balance can be specified with or without currency. Currency may follow the balance value, ex: '2 USD'. When no currency specified then the balance checked as an absolute value regardless of card's currency (updated in 1.7.1) | NULL |
| Ignore Connect Fee | Do not use connect_fee in the duration calculations | False |
| Say_Negative_Balance_As_Zero | When option is and if balance is under zero then say "You have zero dollars". Say "You have minus <amount> dollars" if this option disabled. | True |
Authentication
| Option | Meaning | Default |
| Use CLI Authentication Only | Only accounts with existing CLI mapping are allowed to enter | False |
| CLI As Card Number | Try to use CLI as card number first before other methods | False |
| Use VoIP Login As Card Number | Look for a calling card in the accounts table by the authname field (normally the username field is used). | False |
Custom scripts
| Option | Meaning | Default |
| Custom Script To Check Destination | Set the path to the destination check script | |
| Custom Script To Change Announced Duration | Script to calculate custom duration to be announced to the user. |
Hot Dial & Smart Dial
| Option | Meaning | Default |
| Enable Direct Hot Dial | Single digit destinations dialed from main menu will be treated as hot dial keys if this option is true | False |
| Enable Hot Dial | If the Hot Dial sub application enabled | True |
| Hot Dial Edit Menu Extension | Extension number to edit the Hot Dial keys | |
| Hot Dial Menu Extension | Hot Dial extension number | |
| Limit Hot Keys | If true then only keys 1, 2 and 3 can act as the hot dial keys | False |
| Smart Dial Exclusive Mode | Should the Smart Dial DID be shared amongst many accounts. | False |
Top-Up
| Option | Meaning | Default |
| Enable Top-Up feature | If the Topup sub application enabled | True |
| Top-Up Card Length | The maximum allowed number of digits of top-up card | 10 |
| Top Up Menu Extension | Extension number for Top-Up Card Sub application |
Black List
Please note that attempts to enter numbers less than 4 digits long are not treated as fraud activity. Only numbers more than 3 digits long trigger black list.| Option | Meaning | Default |
| Enable Black List | If the blacklist feature turned on. | False |
| Number Of Attempts To Blacklist | How many wrong calling card numbers should be entered in a row to blacklist the current CLI. | 3 |
Miscellaneous
| Option | Meaning | Default |
| Use Word PIN | Use word PIN in all phrases regarding card number. So for example phrase "Enter card number" will sound "Enter PIN code"and so on... Please note that this option disables the password check. | False |
| Suppress Pound Phrase | Do not say "...followed by the pound key" when asking destination number and PIN | False |
| Enable Custom Greeting | If the custom language independent greeting enabled (it is played at the very beginning of the application before the language selection) | No |
| Custom Greeting File | Path to the custom language independent greeting audio file (it is played at the very beginning of the application before the language selection) | |
| Early Greeting Prompt ID | The Prompt ID to be played before the language selection menu. This prompt cannot be localized. See an example at the end of the page. | |
| Late Greeting Prompt ID | The Prompt ID to be played after the language selection menu before balance announcement. This prompt can be localized. See an example at the end of the page. | |
| VoodooVox Source Key | The source key for VoodooVox Ads | None |
| Default Calling Card Language | Default fall back language | en |
| Fallback_To_Default_Calling_Card_Language | Whether to fall back to default language after the maximum number of wrong attempts to select the language have been made. | No |
| Say 'No Card' On Low Balance | Say Wrong card number (PIN code) instead of There is no available balance left in this calling card. (New in 3.0) | True |
Destination Check Script
This is a Python script in the following format. The script is to be put into some file (/home/ssp/check_dest.py for example) and path to this script is to be added to the configuration. This file has to contain the function checkDestination() with six mandatory parameters - CLI, translated CLI, CLD, translated CLD, username of account making the call and original CLI of the IVR session. The function must return boolean value where True means that the destination is allowed and False - destination is prohibited. This script is loaded dynamically so there is no need to restart ivrd after the script has been changed. Should any problem occur during script load, the script is disabled and corresponding error message is written to the log. If any problem occur during script execution, the Calling Card application treats this as a prohibition to make call.Duration Script
The script is run with the following parameters: account's username, account's balance, CLI, CLD, calculated maximum duration (in seconds), i_tariff, translated CLI and translated CLD. The script must print to the stdout a duration that is to be announced to the user. Please note that the duration returned from the script does not affect the maximum session time, it only changes the duration announcement message.Database usage
The application uses the accounts table for authentication purposes, to retrieve the value of the user's balance, to make balance transfers and to change password.
The calling_card_cli_map table is used to store CLI-to-CallingCard mappings. These mappings are used to automatically select the calling card account based on the CLI of the user.
Use of multiple instances of Calling Card Application
The application can be configured not only via central configuration but also by CLD rewriting. This allows to use several differently configured instances of application within the same server. The CLD options always override the corresponding global configuration options.
The following parameters are accepted.
| chpassext<ext> | Specify the Change Password extension for this instance |
| cliregext<ext> | Specify the CLI Registration extension for this instance |
| directhotdial | Destinations 1, 2 and 3 dialed from main menu will be treated as hot dial keys if this option is specified |
| earlymedia | Use early media mode till the destination has answered |
| greet<i_ivr_prompt> | Use prompt from the ivr_prompts table as a greeting (new in 1.7) |
| hotdialext<ext> | Hot Dial extension number |
| hotdialeditext<ext> | Extension number to edit Hot Dial keys |
| keepcli | Use original CLI to call destination |
| lgreet<i_ivr_prompt> | Use prompt from the ivr_prompts table as a late greeting. This greeting is language aware, unlike the greet option (new in 1.7). |
| nocardenter orclimaponly | Exit immediately if no CLI mapping has been found |
| nochpass | Change Password extension is disabled regardless if it specified or not |
| nocliauth | Do not try to use CLI as card number |
| noclireg | CLI Registration extension is disabled regardless if it specified or not |
| nodial | Disallow outside calls. This is useful if service codes only are to be available. |
| nohotdial | Disable Hot Dial fetature, both dial and edit keys capabilities |
| nokeepcli | Use calling card username as CLI to call destination |
| noplaybalance ornobalance | Disallow balance announcement |
| noplayduration ornoduration | Disable call duration limit announcement |
| noredial | Hangup after the call attempt regardless it was successful or not |
| notopup | Top-Up extension is disabled regardless if it specified or not |
| planminutes | Play service plan minutes instead of a sum of plan minutes and duration calculated by tariff. This option does not affect actual maximum duration of a call which is a sum of plan minutes and duration calculated by tariff. |
| playbalance | Allow balance announcement |
| topup | Start Top-Up Card subapplication instead of main Calling Card loop. All functionality except Top-Up Card is disabled. |
| topupext<ext> | Specify the Top-Up extension for this instance |
| trustcli | CLI mapping is trusted so the PIN is never asked |
| trycliauth or cliauth | Try to use CLI as card number first before other methods |
All other two-character parameters are treated as language list specification.
Example of CLD rewriting rule:
s/.*/callingcard_en_th_ru_cliregext003_trustcli_noplaybalance/
The balance of account won't be played in the following cases:
- there is a minutes plan configured in the service plan of the account - service plan status is suspended - account's balance is equal to zero
Late Greeting example
Late Greeting feature allows to make announcement after calling card has been identified and before the balance played. To play the audio the IVR Prompts facility is used. The facility allows to specify a language specific versions of the prompt. Here is how one can prepare a prompt to work as a Late Greeting:
- Create a prompt with the default audio recording:
$ /home/ssp/scripts/ivr_prompt_utils -c default_audio.sln late_greeting 'Long description'
New prompt created with i_ivr_prompt = 29
- As you see the prompt created and was assigned an identifier of 29. Add all needed localized recodings to this prompt (Thai and Chinese are showed in the following example):
$ /home/ssp/scripts/ivr_prompt_utils -u 29 -a thai_audio.sln --lang=th
IVR prompt updated/ivr_prompt_utils -u 29 -a chinese_audio.sln --lang=zh
IVR prompt updated
$ /home/ssp/scripts
- Now you've prepared the prompt and can start to use it - just specify 29 as the value to an advanced parameter Late Greeting Prompt ID.
- As you see the Japan and English languages are included here also but we haven't prepared the corresponding localized prompts. In this example the users of the Calling Card that have chosen Japan or English will hear the announcement in the default language (the audio from the default_audio.sln file).
- Please note that the *.sln files must contain audio in signed linear format. Almost any audio format can be relatively easily converted to the signed linear format. Here is an example how to covert 'file.wav' into 'file.sln':
/usr/local/bin/sox file.wav -t raw -s -2 -r8000 -c1 file.sln
Notes
An i_environment must be specified since version 3.0 in a form:
ivr_prompt_utils.py -E I_ENVIRONMENT -c audio_file name description
Early Greeting example
Early Greeting feature allows to make announcement before the user proposed to choose a language. The procedure of setting up the greeting is very similar to the Late Greeting except the language specific audio is not needed. Here is how to prepare a prompt to work as an Early Greeting:
- Create a prompt with the default audio recording:
$ /home/ssp/scripts/ivr_prompt_utils -c greet_audio.sln early_greeting 'This is an early prompt'
New prompt created with i_ivr_prompt = 30
- The prompt is ready. Specify 30 as the Early Greeting Prompt ID and now configuration is completed.
Notes
- CLI Registration extension relies on correct CLI delivery to the application. Sometimes the CLI is not delivered correctly, or when PSTN user blocks his CLI some bogus CLI is delivered instead. This may result in user registering this bogus CLI and other users not being able to use the service when they also have CLI disabled. Therefore routing shall be configured to block any suspicious CLI, for example the following CLI Translation Rule could be used to only pass 10-digits numeric CLIs that start with 0:
s/(^0[0-9]{9,9}$|^).*$/\1/ - Calling Card application allows the user to disconnect outgoing call by pressing pound sign twice in a row (##) during any phase of the call.
- If you want to deny some CLI the possibility of adding itself to the trusted numbers (someone calls to the DID, that is assigned to Calling card IVR application in our system, authorize using some account "Please, enter your PIN code" and then can be prompted whether he wants to add the number he calls from as a trusted one) you'll have to do the following:
a) Find out the CLI you want to ban b) Add the CLI translation rule to the specific DID number you want to be affected by the change, e.g. to ban CLI 33nonymous from adding it as a trusted one you'll need to add the following translation rule:
s/33nonymous$/Anonymous/
As a result if the incoming CLI = 33nonymous it'll be rewritten to Anonymous, which is not allowed to save itself to the trusted numbers by default. No other CLI will be affected by this change.