Howto:Learning PIN code

From innovaphone-wiki

Jump to: navigation, search

Some companies supplies a PIN code to their customer. For example haulage firms or service companies. If a customer calls those companies, he hear a message inviting him to enter his delivery or ticket number. In this description, we call that number "PIN". If a dialed PIN is fine, the call goes to one queue, otherwise to another queue. We name the "PIN-OK" queue "priority queue" and the other queue (without or wrong PIN) "normal queue".

If a caller enter a correct PIN and then calls a second time, the system will recognize the calling number and forward the call immediately in the priority queue, therefore without any menu or voice prompt. If the same customer calls from another number (example: first call was from his fixed phone and than he calls from his mobile phone) he has to enter again the PIN. A further call from this number is forwarded immediately to the priority queue: one single PIN can store many external numbers. However, one number can be associated to just one single PIN. This is exactly what companies expect: a automatic association caller number to a "customer number".

Result: the system learn automatically the caller number and associates them to the PIN codes.

The called user answering the calls should see the PIN and also recognize if the PIN was valid or a wrong one and if the caller has entered the PIN for the first time or the system automatically forwarded the call.

The user must also be able to create, delete and handle the PIN codes without complicated procedures or using external software. The length of a PIN code can be set but must be between minimum three and maximum six digits.

A second mode of operation is a simple check of whether a PIN code is in a directory or not: with a valid PIN, the call is forwarded to a destination or other destination if it is incorrect. Please note that using the simple PIN check the voice setup will not work, the customer will add/delete/change the PIN doing this in the directory of the CF/mSATA. To switch the operational mode see chapter “Installation and setup”.

How this free xml service works describes this article.


Applies To

This information applies to:

tested wirth innovaphne PBX V12r2

More Information

An external caller hear an automatic voice prompt inviting him to enter the PIN or to wait for an operator. If the caller enters a correct PIN the system stored his number and the call is immediately forwarded to the priority queue. All further calls from that number skips the voice menu and forward the call immediately to the priority queue.

If the caller enter nothing, dials “#” or dial a incomplete PIN code the call will be forwarded to the normal queue.

If the caller dials a non-existing (= invalid) PIN he will hear the message “invalid PIN” and again the invitation to dial a PIN. Therefore, a caller has a second chance to dial in the correct PIN.

Note: “Priority queue” and “Normal queue” are just numbers; the XML forwards the call to any number (not just to queues) but normally queues are used, therefore in this description we always use these terms.

The called users in the PBX will see on their display the number of the caller followed by the PIN code (if any). The calling number is separated by the PIN with a "#". There is also a second "marker", typically and in this description a "#", but it could also be a "*".

If the system knowns the PIN code it will be mark with an additional "#" at the end, if the PIN code is invalid or incomplete with an "#" at the beginning. The caller number is divided by the PIN with a “#”; therefore a recall will not dial out the PIN.


The caller has the number “0456701943” and the valid PIN is “123456”.

The caller do not enter a PIN or enter just a “#”: the display of the called user shows “00456701943”

The caller enter the PIN “123456” the first time: display = “00456701943#123456”

The caller calls again (with automatic dispatch): display = “00456701943#123456#”

The caller dial a nonexistent or partial PIN: display = “00456701943##1234”

In this way the user in the PBX will be able to check immediately if the caller has performed a PIN code or not, if the code was valid, if the call came from a known number or it is a new entry.

PIN Setup

A PBX user can setup PINs very simple just using a Phone. The access to the service must be done in block dial mode.

Example: the VM-object hat the number "88" and "*" is the setup prefix: dial “88*” and pick up the handset.

Calling the service, a voice menu offers the following choise:

"1, create a new PIN"

"2, delete a PIN"

"3, check a PIN"

"4, clear the numbers associated to a PIN"

"5, clear a calling number"

Once selected the action a further voice prompt invite to enter the PIN (the calling number if the choise was "clear a calling number").

If a new PIN is created follows the message “PIN created”, if a PIN is cleared the message “PIN cleared”.

The length of a pin is know to the system, if a PIN is incomplete or the user enter “#” after just some digits the message “invalid PIN” is played. The timeout for dialing PIN is 5 seconds; in any case a automatic return to the main menu is given. If during entering the user note that his input is wrong he has just to wait, to dial a “#” or disconnect.

Menu 3 ("check a PIN") will play “PIN found” or “PIN invalid”.

Menu 4 deletes all external numbers associated to the PIN. Therefore, if a user from one of those cleared numbers calls again he will hear the message “enter your PIN” (again). If a valid PIN is entered the message “PIN created” is played, otherwise the message “PIN invalid”.

Menu 5 clears an external number (while Menu 4 clears all numbers) associated to a PIN followed by he prompt “Number cleared”.

Note that all selections can be entered immediately and without waiting the end of a promt.

Well known numbers

On top some customer have a certain amaount of "well known" and permanent external numbers that should be mapped to destination, typically the priority queue. Imagine for example all the external mobile numbers of the own employees or locations not connected in Voip. You can do this mapping also using the relay routing, but if there are hundreds of numbers it will be easy using this xml also to do this.

Installation and Setup

Unzip the files of the solution on a directory of your PC, open the editor (not Word or similar) and load the XML “CustNumber.xml”. At the top of the code there is the function “Switch”, where all setup prameters are in, modify the values and save the file. The following list shows the default values and the meaning:

<assign out="$TargedNoCode" value="21"/> : target of calls without or with wrong PIN (=”normal queue”)

<assign out="$TargedCodeOK" value="88"/>: target of calls with PIN (=”priority queue”)

<assign out="$WellKnown" value="36"/>: target of calls from well known numbers

<assign out="$CodeLength" value="6"/>: length of the PIN code (from 3 to 6 digits)

<assign out="$SetupCode" value="*"/>: number for access to the PIN setup. This code is in addition to the number of the XML. If the XML itself has the number “88” (your trunk will incoming point on that number) the access to the service for PIN handling will be “88*”

<assign out="$MarkDigit" value="#"/>: digit that will mark the Display.


- if the digit is “#”: The caller “0456701943” calls again -> display = “00456701943#123456#”

- if the digit is “*”: The caller “0456701943” calls again -> display = “00456701943#123456*”

<assign out="$CheckCaller" value="True"/>: if “” the simple check of the PIN code is activated. If this second operational mode is required, please modify also the “SetupCode” to “”

<assign out="$WriteLog" value="True"/>: to switch logging off set this value to “”.

Create a directory on your CF or mSATA and copy all the files and directories.

Create all the voice messages (see relative section) and copy them in the same directory where the xml is in.

Create a VM object in the PBX and fix G711a as codec in the URL.

URL example where the directory on the CF/mSata for that service was “CustNumber”:$_pbxcoder=g711a

Set if requested filters to limit the access to the PIN service menu.

Copy all well known numbers created on your PC in the directory “WellKnown” (see “Well-knows numbers”).

If you do not want that the system remember the caller number just remark or delete the line at the end oft the xml store-cookie root="Caller" name="$CallerID" value="$cdpn".

Voice messages

Typically the message for the caller (“please dial you customer number” or similar) will be defined and recorded from the customer. A good idea is to install the Universal Track recording tool (see link).

This xml requires also all the other prompts mentioned, you can all of them record by yourself using Universal Track recording tool or any other method.

The following list shows the name of the required files and a typical English wording; feel free to realize you own expressions:

Track1.g711a: “Enter your Pin or wait for an operator”

Track2.g711a: “Select 1 to create a new Pin, 2 for delete a Pin, 3 for check a Pin, 4 to clear all numbers on a Pin, 5 for clear a external number.”

Track3.g711a: “Invalid Pin”

Track4.g711a: “Pin created”

Track5.g711a: “Pin not found”

Track6.g711a: “Pin cleared”

Track7.g711a: “Number deleted”

Track8.g711a: “Enter your Pin”

Track9.g711a: “Number”


Well-known numbers

In this directory “WellKnown” are all the well-known external calling numbers in, the number is the filename with a “.txt” extension. If you want to map for example the number "0049703173009” create a file named “004970317300.txt” and copy it in this directory. Please note that mSATA would not accept empty files, therefore at least a space has to be in. The XML simply check the number of the calling party and if that is in the directory, it transfers the call. It is a good idea to test first your setup with one single number and after then proceed with multiple numbers.

PIN codes

This section explains how the XML handle the call, if you are not interested in the details you can skip this explanation.

The only particulary thing you have to understand is that the XML splits the PIN into the first two digits and the rest of the pin and works on that sub-directory. If for example, you create the PIN “123456” the XML creates in the fix directory “Codes” the subdir “12” and inside of the "12" the subdir “3456”: here in will be stored a caller number as also a copy in the directory “Caller”. If a call came in after checking the well knows numbers the xml check if the caller number is in the “Caller” directory and if yes, the relative file will be read out. In the file, there is the code in and, if also in the sub directory there is this number in, the call is a priority call. If not the number is cleared in the Caller directory and the call is passed to the normal call queue.


If logging is switched on, the XML creates automatically a directory Log and the call-transfer to one of the two queues or destinations will create an empty file.

The file name is the log itself, the format is:


Known Problems

Related Articles


  • Download the complete file package of scripts and files described in this article.
Personal tools