Setting up DID for Calling Card IVR Application


  1. Add an IVR Application of type 'Calling Card' in 'IVR Applications' menu on the Web. After creation of the application use Advanced Parameters to customize the application for your needs.
  2. Use the 'DID Pool' menu to add a DID and assign your newly created Calling Card IVR Application to it.


Call routing setup (obsolete)


  1. Add vendor connection. Set the Asterisk's host/port in the Destination field of Vendor Connection (ex: 192.168.0.100:5062).
  2. Set the CLD Translation Rule for the connection to the value s/.*/callingcard/. Optionally the set of options can be specified in the CLD - see the specs below.
  3. Add route to this connection and specify the Calling Card Extension number.


Configuration options


Basic options:


Option
Meaning
Default
Announce BalanceWhether to announce balance upon successful start of applicationYes

Normal Calls Are Allowed

Only service codes enabled if this option is False
No outgoing calls will be processed by this CC IVR application while only the Service Codes will be processed if that option option set to 'false' .

True
Disconnect On FailureWhether 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 PINWhether to permit to use the prepaid card accounts with empty PINtrue
Preserve Original CLICLI 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 DurationMaximum call duration3600 seconds
Card Number LengthMaximum number of digits allowed in a card number10
Number_Of_Attempts_To_Enter_A_CardMaximum number of attempts to enter card number or PIN code3
Number Of Wrong DestinationsMaximum allowed number of unsuccessful call attempts in a row3
Number Of TimeoutsMaximum number of input timeouts3
Minimum Call DurationMinimum 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 LengthMinimum number of digits allowed in a card number
No Seconds In DurationDo not pronounce seconds while announcing call duration. If the duration is less than 1 minute then this option is ignored.False
No Hours In DurationDo not speak out hours while announcing call duration, only minutesFalse
Announce DurationShould the duration of the call be announcedTrue
Call Several DestinationsOnly one call attempt per session is allowed if this option is False. Equal to noredial option
True
Outbound SIP ProxySIP proxy host:port to send the outbound calls to (this option can also be set from the command line).

This option can be useful if the outgoing calls should be processed by the external switch\server instead of the built-in b2bua service for placing the outbound calls to your Vendors.

<Environment_IP>:5061
Disconnect Warning TimeSay  'Your call will be disconnected in N seconds'  before the call disconnect60
Play Service Plan Minutes OnlyPlay 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 RegexTreat the destination number to have been completed and immediately continue with the call when the input matches the given regular expression pattern
The Reason For Diversion *
The reason parameter for the Diversion SIP header
unconditional

* starting from Sippy 2020


Trusted CLI related options


Option
Meaning
Default
Enable CLI RegistrationIf the 'CLI Registration' sub application is enabled, then the corresponding IVR prompt will be played and the user will be asked to link its <ANI\CLI> number as the 'Trusted Number' to the used <Calling Card\PIN> for further possible PINless dialing.


Automatic CLI RegistrationAfter calling card has been entered successfully, add the current CLI to the list of trusted CLIs for this calling card. If the authorization is successful after entering the <Calling Card\PIN>, then the user's <ANI\CLI> number will be added as the 'Trusted Number' to the used <Calling Card\PIN> for further possible PINless dialing.
No
Silent Automatic CLI RegistrationWhen this option is set to False the user will be prompted if he wishes to register his phone number (new in 1.7.1).
The same as in Automatic CLI Registration, but the user will be asked whether its number should be added as the 'Trusted Number' to the used <Calling Card\PIN> for further possible PINless dialing
True
CLI Registration Menu Extension NumberExtension number for the CLI Registration Subapplication. Exact extension number that can be entered to reach the CLI Registration Sub application while connected to that CC IVR application.any value from 0 to 9
Trusted CLI AuthenticationAllow to use Trusted Numbers for authentication.False
Minimum Valid CLI LengthMinimum CLI length that is allowed to trigger the Automatic CLI Registration.6


Password change


OptionMeaning
Default
Enable Password ChangeIf password change enabled
True

Change Password Menu Extension Number

Extension number for the Change Password Subapplication.

any value from 0 to 9

Billing related options
:

OptionMeaningDefault
Balance ThresholdIf 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 Balance option
Minimum BalanceIf 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 FeeDo not use connect_fee in the duration calculationsFalse
Say_Negative_Balance_As_ZeroWhen 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


OptionMeaningDefault
Use CLI Authentication OnlyOnly accounts with existing CLI mapping are allowed to enter. IVR system will authorize incoming calls by trust CLI method.False
CLI As Card NumberTry to use CLI as card number first before other methodsFalse
Use VoIP Login As Card NumberLook for a calling card in the accounts table by the authname field (normally the username field is used).False
PIN-less CLI AuthenticationOption applicable for any IVR application since 4.4, if any kind of CLI authentication has succeeded then do not ask for PIN even if it is set. The CLI authentication includes CLI As Card Number, Trusted Numbers and Smart Dial.False
Allow Own Accounts OnlyOption applicable for any IVR application since 4.4, if enabled then only accounts of the customer that has created this IVR application would be allowed to use it.
False


Custom scripts:


OptionMeaningDefault
Custom Script To Check DestinationSet the path to the destination check script.
Destination Check Script - is a Python script. 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. 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.

Custom Script To Change Announced DurationScript to calculate custom duration to be announced to the user. 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.


Hot Dial & Smart Dial


OptionMeaningDefault
Enable Direct Hot DialSingle digit destinations dialed from main menu will be treated as hot dial keys if this option is trueFalse
Enable Hot DialIf the Hot Dial subapplication enabled. Enable Direct Hot Dial option is applied for accounts which use Hot Dial feature.
In this case, single digit destinations dialed from main menu will be treated as hot dial keys.
For example account uses Hot Dial Key 5 with Destination number 123456. Pressing 5# in Calling
Card IVR initiates call to the 123456 destination if Enable Direct Hot Dial = True and returns error
if Enable Direct Hot Dial = false (by default).
True
Hot Dial Edit Menu ExtensionExtension number to edit the Hot Dial keys
Hot Dial Menu ExtensionHot Dial extension number
Limit Hot KeysIf true then only keys 1, 2 and 3 can act as the hot dial keysFalse
Smart Dial Exclusive ModeShould the Smart Dial DID be shared amongst many accounts.

This option should be left false by default. If it is set to true, only 1 account will be able to add DID number assigned to this IVR application as Smart Dial number.

False



Top-Up


OptionMeaningDefault
Enable Top-Up featureIf the Topup subapplication enabledTrue
Top-Up Card LengthThe maximum allowed number of digits of top-up card  
10
Top Up Menu ExtensionExtension number for Top-Up Card Subapplication.

any value from 0 to 9

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.


OptionMeaningDefault
Enable Black ListIf the blacklist feature turned on.False
Number Of Attempts To BlacklistHow many wrong calling card numbers should be entered in a row to blacklist the current CLI.3


Miscellaneous


OptionMeaningDefault
Use Word PINEnable one-step authentication. With the Use Word Pin option set to false the PIN would be asked after entering the card number for accounts that have PIN configured. Case PIN is not set for Account, authentication will proceed without it, unless Allow Empty PIN is set to false, in such case call would be dropped with PIN set request.
Thus if you need to add extra security to the system, setting this parameter to False would be a good idea, as it'd require entering both card number and a secret PIN of that card.
Also applicable to Top-Up IVR application, to enable top-up vouchers PINs.
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.
True
Suppress Pound PhraseDo not say "...followed by the pound key" when asking destination number and PINFalse
Enable Custom GreetingIf the custom language independent greeting enabled (it is played at the very beginning of the application before the language selection)No
Custom Greeting FilePath to the custom language independent greeting audio file (it is played at the very beginning of the application before the language selection). Path has to be specified omitting the file extension, in the same folder there must be versions for all needed extensions (sln, g729, possibly g723). Example:
/usr/home/ssp-root/my_custom_prompt

Early Greeting Prompt IDThe Prompt ID to be played before the language selection menu. This prompt cannot be localized. See an example at the end of the page. This option let you use the custom greeting when you're calling to the IVR app.

Late Greeting Prompt IDThe 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 KeyThe source key for VoodooVox AdsNone
Default Calling Card LanguageDefault fall back languageen
Fallback_To_Default_Calling_Card_LanguageWhether 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 BalanceSay "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
directhotdialDestinations 1, 2 and 3 dialed from main menu will be treated as hot dial keys if this option is specified
earlymediaUse 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
keepcliUse 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 or climaponlyExit immediately if no CLI mapping has been found
nochpassChange Password extension is disabled regardless if it specified or not
nocliauthDo not try to use CLI as card number
nocliregCLI Registration extension is disabled regardless if it specified or not
nodialDisallow outside calls. This is useful if service codes only are to be available.
nohotdialDisable Hot Dial fetature, both dial and edit keys capabilities
nokeepcliUse calling card username as CLI to call destination
noplaybalance or nobalanceDisallow balance announcement
noplayduration or nodurationDisable call duration limit announcement
noredialHangup after the call attempt regardless it was successful or not
notopupTop-Up extension is disabled regardless if it specified or not
planminutesPlay 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.
playbalanceAllow balance announcement
topupStart 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
trustcliCLI mapping is trusted so the PIN is never asked
trycliauth or cliauthTry 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 (new in 1.7)


Late Greeting lgreet 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


For<=2022 systems:

$ /home/ssp/scripts/ivr_prompt_utils -E I_ENVIRONMENT -c default_audio.sln late_greeting 'Long description'
New prompt created with i_ivr_prompt = 29


For>=2023 systems:

$ /usr/local/bin/ivr_prompt_utils -E I_ENVIRONMENT -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):


For<=2022 systems:

$ /home/ssp/scripts/ivr_prompt_utils -u 29 -a thai_audio.sln --lang=th
IVR prompt updated
$ /home/ssp/scripts/ivr_prompt_utils -u 29 -a chinese_audio.sln --lang=zh
IVR prompt updated


For>=2023 systems:

$ /usr/local/bin/ivr_prompt_utils -u 29 -a thai_audio.sln --lang=th
IVR prompt updated
$ /usr/local/bin/ivr_prompt_utils -u 29 -a chinese_audio.sln --lang=zh
IVR prompt updated


 - Now you've prepared the prompt and can start to use it. Modify your CLD translation rule to include lgreet29. So the final rule

   may look like:


s/.*/callingcard_en_th_zh_ja_lgreet29/


- 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



Early Greeting example (new in 1.7)


Early Greeting greet 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:


For<=2022 systems:

$ /home/ssp/scripts/ivr_prompt_utils -E I_ENVIRONMENT -c greet_audio.sln early_greeting 'This is an early prompt'
New prompt created with i_ivr_prompt = 30

For>=2023 systems:

$ /usr/local/bin/ivr_prompt_utils -E I_ENVIRONMENT -c greet_audio.sln early_greeting 'This is an early prompt'
New prompt created with i_ivr_prompt = 30


  • The prompt is ready. Modify your CLD translation rule to include greet30. So the final rule may look like:


s/.*/callingcard_en_th_zh_ja_greet30/


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:
    
    1. Find out the CLI you want to ban
    2. 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.

     




Calling Card options explanation



1.Normal Calls Are Allowed
 Only service codes enabled if this option is False

No outgoing calls will be processed by this CC IVR application while  only the Service Codes will be processed if that option option set to  'false' .


2. Outbound SIP Proxy

SIP proxy host:port to send the outbound calls to (this option can also be set from the command line)

This option can be useful if the outgoing calls should be processed by  the external switch\server instead of the built-in b2bua service for  placing the outbound calls to your Vendors.


3. Enable CLI Registration
 If the CLI Registration sub application enabled

If the 'CLI Registration' sub application is enabled, then the  corresponding IVR prompt will be played and the user will be asked to  link its <ANI\CLI> number as the 'Trusted Number' to the used  <Calling Card\PIN> for further possible PINless dialing.


4 Automatic CLI Registration
 After calling card has been entered successfully, add the current CLI to the list of trusted CLIs for this calling card.

If the authorization is successful after entering the <Calling  Card\PIN>, then the user's <ANI\CLI> number will be added as  the 'Trusted Number' to the used <Calling Card\PIN> for further  possible PINless dialing.


5.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).

The same as in 4th case, but the user will be asked whether its number  should be added as the 'Trusted Number' to the used <Calling  Card\PIN> for further possible PINless dialing


6 CLI Registration Menu Extension Number
 Extension number for the CLI Registration Sub application

Exact extension number that can be entered to reach the CLI Registration  Sub application while connected to that CC IVR application.


7 Trusted CLI Authentication
 CLI mapping is trusted so the PIN is never asked

That option enables the PINless dialing based on the Trusted Number. If  the user has already entered the <Calling Card\PIN> successfully  during the previous session and its <ANI\CLI> has been added to  the Trusted Numbers of the used <Calling Card\PIN> and if that  user calls the CC IVR application second time using the same  <ANI\CLI>, then no PIN will be asked (no authorization) in such  case, so that it will be only asked for the destination number to call.


8. Use CLI Authentication Only
 Only accounts with existing CLI mapping are allowed to enter

You IVR system will authorize IVR call only by trust CLI method.


9. Custom Script To Check Destination
Set the path to the destination check script

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.


10 Custom Script To Change Announced Duration
 Script to calculate custom duration to be announced to the user.

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.


11 Enable Direct Hot Dial
 Single digit destinations dialed from main menu will be treated as hot dial keys if this option is true

Enable Direct Hot Dial option is applied for accounts which use Hot Dial  feature. In this case, single digit destinations dialed from main menu  will be treated as hot dial keys. For example account uses Hot Dial Key 5  with Destination number 123456. Pressing 5# in Calling Card IVR  initiates call to the 123456 destination if Enable Direct Hot Dial =  True and returns error if Enable Direct Hot Dial = false (by default).


12 Smart Dial Exclusive Mode
 Should the Smart Dial DID be shared amongst many accounts

This option should be left false by default. If it is set to true, only 1  account will be able to add DID number assigned to this IVR application  as Smart Dial number.


13 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.

This option should let you use your custom greeting when you're calling that IVR application.


14 VoodooVox Source Key
 The source key for VoodooVox Ads

This option is related to the VoodooVox ads provider. Please contact us if you need more details about it.