Smart Dialplan | Custom Applications – Advanced Dialplan

 

Smart Dialplan: this guide on Advanced Dialplan provides examples of Custom applications use for interaction with external software, MySQL server, PHP, CURL request, TAPI, MySQL Microsoft Database.

 

Date: 30/03/2016

 

Variables in Dialplan

Conditions in Dialplan

CURL request

Request from a MySQL server

DTMF function

Implementation of smart Dialplan: accounting

PHP integration

 

Variables in Dialplan

Variables are needed to store the information necessary to execute the application.

 

Syntax used to call a variable:

${foo:offset:length}

 

Where:

foo: is the name of the variable

offset: optional offset in starting to read a variable

length: optional number of characters to read

 

 

Syntax used to set a variable:

set(variablename=value)

 

Where:

variablename: is the name of the variable, it is insensitive to the variables defined by users

value: is the value attributed to the variable

 

Example:

set(foo=123456789)

${foo} → 123456789

${foO:1} → 23456789

${Foo:-4:3} → 678

 

 

Useful variables:

 

${CALLERID(all)}: Caller name and caller number

${CALLERID(name)}: Caller name

${CALLERID(num)}: Caller number

${ANSWEREDTIME}: Elapsed time since the call has been answered

${EXTEN}: Extension

${CONTEXT}: Name of Dialplan procedure

${CHANNEL}: The channel (the called number present in the Dialplan procedure)

 

Example:

 

Screen Shot 2016-10-25 at 16.07.52.png

 

This Dialplan is assigned to user 102

NoOp function serves to display the variable value inside the Dialplan debug

 

 

Dialplan debug:

 

Screen Shot 2016-10-25 at 16.08.57.png


Conditions in Dialplan

Conditional jump is executed using the function Gotolf, which allows jumping to another Dialplan procedure based on the result of the condition.

condition is an expression that the boolean result (true or false) conditions the choice of Gotoif.

 

 

Syntax to use to make a jump:

GotoIf(condition?label1:label2)

 

Where:

label1:label2 are the destinations of the jump, consisting of three parts: context, extension, priority

context: name of Dialplan procedure

extension: extension

priority: line number, usually 1

condition: the choice of GotoIf depends on the boolean result of this expression (true or false)

In Dialplan Custom applications True = 1 and False = 0

$[expr1 operator expr2] 

 

Where:

expr can be a variable or a value; it can be also an expression (expressions can be nested)

operator as a rule it is relational (comparison) operator ( =, <>..); for nested expressions it’s possible to use logical operators AND, OR, NOT

 

Logical operators:

expr1 | expr2 → OR

expr1 & expr2 → AND

!expr → NOT

 

Relational operators:

expr1 = expr2 → equal

expr1 != expr2 → inequal

expr1 < expr2 → less than

expr1 > expr2 → greater than

expr1 <= expr2 → less than or equal

expr1 >= expr2 → greater than or equal

 

Examples

GotoIf(condition?label1:label2)

GotoIf($[${FOO} = 1]?users,101,1:users,102,1)

 

condition : $[${FOO} = 1]

label1: users,101,1

label2: users,102,1

 

If FOO variable is equal to 1, the Dialplan jumps to “users” procedure with extensions 101; else – it jumps to “users” procedure with extensions 102


CURL request

cURL allows sending a request to a web page. As a rule cURL command is used together with Set in order to write down a value received from a web page into a variable.

 

Set(variablename=${CURL(URL)})

 

Example:

Set(foo=${CURL(http://myexample.wildix.com/smartdialplan/echo101.php)})

 

In this example the value returned is 101.

 

In this way we can pass the caller number to a web page using ${CALLERID(num)} as an URL parameter:

 

Set(foo=${CURL(http://192.168.1.1/callernum.php?callernum=${CALLERID(num)})})


Request from a MySQL server

Dialplan can interact with databases, e.g. MySQL. A BDD request requires several steps:

 

MYSQL(Connect connid 192.168.1.1 smartdialplan wildixexample@@ smartdialplan)

MYSQL(Query resultid ${connid} SELECT ext FROM callernum WHERE callernum=${CALLERID(num)})

MYSQL(Fetch fetchid ${resultid} FOO)

MYSQL(Clear ${resultid})

MYSQL(Disconnect ${connid})

 

Connect: Establishing connection to the BDD

Query:  Request execution

Fetch: Reading the result

Clear: Memory cleaning

Disconnect: Disconnection from the BDD

Details of each step:

 

MYSQL(Connect connid dhhost dbuser dbpass dbname)

Connection to the database: at this stage the credentials, the name of the server and the database are provided. Connection identifier is returned in ${connid}. If the connection could not be established, then it returns ${connid} == “”.

 

MYSQL(Query resultid ${connid} query-string)

Executes standard MySQL query contained in query string using established connection identified by ${connid}. Result of query is stored in ${resultid}.

 

MYSQL(Fetch fetchid ${resultid} var1\ var2\ …\ varN)

If result is fetched, ${fetchid} is set to 1, and the single result is contained in ${resultid} and returned fields are written to ${var1}, ${var2} … ${varN} respectively. In case of no result, ${fetchid} is set to 0.

 

MYSQL(Clear ${resultid})

Frees the memory associated to the connection and results.

 

MYSQL(Disconnect ${connid})

Disconnection from the database.

 

 

Example:

 

Database table:

 

Callernum

Ext

0123456789

101

0612345678

102

 

Set MySQL privileges for the PBX to be able to remotely access to this database.

 

Capture d’écran 2016-03-30 à 22.32.36.png


DTMF function

DTMF allows interaction with humans and uses the following functions: Read(), SayNumber() and SayDigits().

 

Read(variable[,filename][,maxdigits][,option][,attempts][,timeout])

Writes a string of digits (terminated by # or containing a certain number of digits)

 

filename: file playback before reading the digits

maxdigits: max acceptable number of digits (in this case user is not required to enter #)

option: There are 3 options:

s(skip): continue the execution immediately if the line is not available.

i(indication): play an indication in case line is not available

n(noanswer): read digits even in case line is not available

attempts: (if greater than 1) number of attempts in the event no data is entered.

timeout: timeout in seconds; if greater than 0, that value overrides the default timeout.

 

SayDigits(digits)

Says the digits, one by one, digits can be a variable.

 

SayNumber(number, gender)

Says number

gender is “f” for female voice; “m” – for male ;”c” – for neutral

 

Example:

Capture d’écran 2016-03-30 à 22.45.01.png

 

Read(FOO,00000/smartdialplan/numcommande,3,,,10)

SayNumber(${FOO},f)

Dial(SIP/${FOO})


Implementation of smart Dialplan: accounting

This service allows granting a user limited access to phone in a hotel or a camping, based on the number of credits he or she has purchased.

 

How it works:

          User calls the dedicated code (555) from the phone

          User enters a secret code for authentication

          Connection to the database is established to check if this code valid; if the code is wrong, playback “code is false”

          Check in the database the remaining credits; if there are no credits left, playback “no credits”; else – ask to enter the number consisting of 10 digits

          The max duration of a call is defined based on the number of credits left

          The other party is called

          Once the call is terminated (by user or if reached the max duration of a call), the database values are updated

 

Implementation:

 

1)      Create a dedicated Dialplan procedure “accounting”

2)      Record the missing sounds using Sounds menu

3)      Prepare the database

 

After these initial steps it’s necessary to set up “accounting” procedure:

 

Context 555 (called number 555)

“Custom applications”:

          Read(CALLER,00000/accounting/code,,,,10)

(secret code for authentication)

          MYSQL(Connect connid examplexx.wildix.com example2016-12 xxxx@xxxx example2016-12)

          MYSQL(Query resultid ${connid} SELECT credit FROM accounting WHERE id=${CALLER})

          MYSQL(Fetch fetchid ${resultid} Current_units)

          MYSQL(Clear ${resultid})

          NoOp(Current Units : ${Current_units})

(connection to the DB and check the number of credits)

          GotoIf($[${Current_units} != NULL]?accounting,0,1:accounting,1,1)

(jump to context 1 if code is wrong, else – context 0)

 

 

Context 1 (called number 1)

Play sound “code is wrong”

Hang up

 

Context 0 (called number 0)

Custom application GotoIf($[${Current_units} > 0]?accounting,00,1:accounting,01,1)

Check remaining credits if = 0, go to context 01, if more than 0, go to context 00

 

Context 01 (called number 01)

Play sound “no more credits”

Hang up

 

Context 00 (called number 00)

Custom applications:

Read(CALLED,00000/accounting/numcorresp,10,,,10)

(requires user to enter 10 digit called number)

Goto(accounting,${CALLED},1)

 

Context 0XXXXXXXXX (called number entered by user)

Custom application Set(TIMEOUT(absolute)=$[${Current_units} + 10])

(set up max duration time of the call)

Dial the trunk

 

h context (called number h) – actions to be executed after hangup (update the max duration and the number of credits in the database)

Custom applications:

Set(New_units=$[${Current_units} – ${ANSWEREDTIME}])
MYSQL(Query resultid ${connid} UPDATE accounting SET credit=${New_units} WHERE id=${CALLER}) MYSQL(Disconnect ${connid})


PHP integration

 

See example: LINK

 

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