Differences

This shows you the differences between two versions of the page.

--- installation_guide:asterisk:start [2016/02/05 08:57] – created borja
+++ installation_guide:asterisk:start [2017/06/27 20:40] (current) – [Asterisk Global Variables] borja
@@ Line 1: / Line 1: @@
-====== Asterisk integration ======
+====== Voximal Asterisk integration ======
-===== Getting Started =====
+===== The Asterisk Module =====
-Once you have completed installing Voximal, you must configure it before attempting to place calls. The management and configuration procedures completely depend on the integration, as the reference VoiceXML browser components never directly access a configuration subsystem.  Instead, all configuration parameters are passed to the initialization or resource creation functions for each VoiceXML browser component. The VoiceXML browser is configured through a text configuration file. Each line of this file defines a value for a property (parameter) applying to a given VoiceXML Engine; the possible property names are defined in the interface header files for the various components.
+The Voximal installs the app_voximal Asterisk application module that uses the process voximald to execute the VoiceXML pages.
-The configuration file format is described in detail in a comment block at the top of the sample configuration file, /etc/voximald.conf.
-NOTE:
+For more information on applications, just type "core show applications" at the Asterisk CLI prompt.
+To show details of how you use that particular application in this file (the Asterisk Dial plan).
-Before any configuration update, make a backup copy of your voximald.cfg file.
+Type:
+<code>
+*CLI> core show applications
+</code>
-Once you have made a backup copy, review the properties in the configuration file and modify their settings as appropriate. For an explanation of each property, refer to support.  In most cases you can modify the following properties to get started (listed in priority order):
+For example, the voximal application:
+<code>
+*CLI> core show application voximal
+</code>
-Configure the internet access to use http
+===== The Asterisk Application =====
-Configure the cache management
-Activate/ deactivate traces
-Configure the supported MIME types
-===== Cache Management =====
+Application that launch a VoiceXML session in the asterisk channel and when complete, return control.
-In the Client configuration section, set client.inet.cacheDir to the directory where you want to store cached Internet files from URL fetches.
+==== Syntax ====
-Set the client.inet.cacheTotalSizeMB property to the desired size limit in megabytes for the Internet fetch cache.
-Processing VXI* produces standard traces under the /tmp/log.txt file. The trace file names are referenced in the /etc/vxmld.conf (old versions:/etc/openvxi/client.cfg) file. Their format can be found in the Log Files section of this document.
-NOTE:
-To disable the cache entry, set the maxage and maxstale properties to 0. This properties can be change in the default.xml file to globally disable the cache.
+<code>
+Voximal([URL|Name|Number])
+</code>
-===== Webserver Configuration (optional) ======
+The URL can by set with different ways :
+<code>
+No parameter, the application will use the VoiceXML accounts (match called number with accounts numbers) : Voximal()
+Pass the URL as the appplication parameter. Example : Voximal(file://tmp/test.vxml)
+Pass the account name or the account number. Example: Voximal(test)
+Pass the “@” to allocate a VoiceXML channel and pass the execution to this dialplan extension. Example : Voximal(@600)
+</code>
+Set the VOXIMAL_URL variable before executing the Voximal application.
+Don't pass any parameter, and use the configuration accounts section. If account number match with the called number, its URL(s) and parameters will be use.
-The VXI* VoiceXML browser supports running against static content stored as local files as well as static or dynamic content served by a web server. The VoiceXML browser is generally used with a web server.  Content can be VoiceXML documents, audio / images / video files (if supported by your version or license), and grammar files. When a web server delivers the content, it also provides the MIME content type for the content and information about the desired caching behavior for the content.
+The following describes how to execute a VoiceXML session.
-For the MIME content type for VoiceXML documents, a value of application/vxml+xml is recommended, but not mandatory, as the VoiceXML browser can use information within the XML document to verify it is a VoiceXML document. For prompt, recognize and record interfaces the MIME content type is more important. Support for the following audio formats is recommended for play and record operations, but not mandatory.
-^MIME Content ^Type Description^
-|audio/basic|RAW (headerless) 8kHz 8-bits mono mu-law [PCM] single channel. (G.711)|
-|audio/x-alaw-basic|RAW (headerless) 8kHz 8-bits mono A-law [PCM] single channel. (G.711)|
-|audio/x-wav|WAV (RIFF header) 8kHz 16-bits mono [PCM] single channel.|
-|audio/X-WAV|WAV (RIFF header) codec GSM (6.10) 7-bits mono single channel.|
-|audio/x-gsm|GSM (6.10) 7-bits mono single channel.|
-|video/mp4|MP4 (Iso file) H.263 7 fps, mulaw/alaw/AMR-NB|
-|video/3gp|3GP (Iso file) H.263 7fps, AMR-NB|
-The length of time the VoiceXML browser caches an item fetched from a web server is controlled by the caching values returned in the HTTP/1.1 header. The VoiceXML browser currently only supports the “Expires” header, which defines the date and time when the VoiceXML browser must discard the cached copy and re-fetch from the web server. Some web servers allow defining caching property defaults based on the MIME content type, useful for allowing caching of audio files but not dynamically generated VoiceXML documents, for example.
+==== Configuration files ====
-===== Start/Stop VoiceXML Browser =====
+Two configuration files are used :
+       * VoiceXML interpreter configuration file (to overwrite default settings)  : [[installation_guide:openvxi:start|/etc/voximald.conf]]
+       * Asterisk Application/module configuration file : [[installation_guide:configuration_file_voximal:start|/etc/asterisk/voximal.conf]]
+====  Configuration example ====
+Example:
-The VoiceXML browser software is installed in /usr/sbin and /usr/lib/vxml.  The VoiceXML browser setup script on Linux is /etc/init.d/vxml. This safe_asterisk can starts the VoiceXML browser to make sure it is still running (use "EXEC=/etc/init.d/vxml restart" in the script).  If the VoiceXML browser process dies, the script will attempt to restart it.
-To load or unload the VoiceXML browser, use the “vxml start” and “vxml stop” commands:
 <code>
-#/etc/init.d/vxml start
+; VoiceXML Configuration
-#/etc/init.d/vxml stop
+;
+[general]
+wav_codec=gsm
+videosilence=;silence
+audiosilence=;silence
+debug=4
+video=yes
+[license]
+max=100
+key=…
+[account1]
+name=Test1
+url=http://localhost/vxml/index.php
+max=1
+[account2]
+name=Test2
+url=http://localhost/vxml/demo/index.vxml
+max=3
+dialformat=SIP/%s@ovh-out
 </code>
-Starting processes at boot time are different among the different operating systems so it is best to consult your OS documentation on how to do this. In Debian-based systems you can add this to your /etc/init.d file, however this will not shutdown the VoiceXML browser very cleanly during a reboot or shutdown.  In a Debian environment you may be able to get a working /etc/init.d script by running the following commands.  It will then run the following command:
+To assign an extension to a VXML account just follow this example, where we are assigning the previous account to three extensions number in your /etc/asterisk/extension.conf asterisk:
 <code>
-#/sbin/chkconfig --add vxml
+[default]
+exten => 981001001,1,Voximal(Test1)
+exten => 981001002,1,Voximal(Test2)
+exten => 981001003,1,Voximal(Test3)
 </code>
-===== VoiceXML Asterisk module =====
+NOTE:
+When you update your voximal.conf file, remember to refresh configuration making a command “voximal reload” in your CLI*> prompt. If you have added SIP, PRI or new extensions you must launch “sip reload”, “extensions reload”, “dialplan reload” or reload asterisk/voximal processes. Use the command “voximal show accounts” to dump your accounts.
-The Vxi* VoiceXML browser installs the app_vxml Asterisk application module that uses the browser to execute VoiceXML pages.
+<code>
+CLI*> diaplan reload
+CLI*> voximal reload
+CLI*> voximal show accounts
+</code>
-Check the VXML application module
+Example:
-For more information on applications, just type "core show applications" at the Asterisk CLI prompt.
-To show details of how you use that particular application in this file (the Asterisk Dial plan).
-Type:
+Add extensions to the Asterisk dial plan /etc/asterisk/extensions.conf, if you want to set the URL in the dialplan:
-<code>
-*CLI> core show applications
-</code>
-For example, the vxml application:
 <code>
-*CLI> core show application vxml
+exten => 888,1,Answer
+exten => 888,n,Wait(3)
+exten => 888,n,Voximal(file:///root/example.vxml)
+exten => 888,n,Hangup
 </code>
-===== VoiceXML Asterisk Application =====
+You can create and edit the file /root/example.vxml with the GNU text editor, VI, for example.
-Application that launch a VoiceXML session in the asterisk channel and when complete, return control.
-==== Syntax ====
+This example will work if you have text-to-speech configured.  If not, use a pre-recorded wav or gsm file to replace the “Hello world!” text by an <audio> tag.  For more information, see the format extensions supported by Asterisk.
 <code>
-Vxml([URL|Name|Number])
+<?xml version="1.0"?>
+<vxml version = "2.0" xmlns="http://www.w3.org/2001/vxml">
+ <form>
+  <block><audio src="hello.wav"/></block>
+ </form>
+</vxml>
 </code>
-The URL can by set with different ways :
+Save the file in the same directory as the VoiceXML script (relative reference in this example).
+Reload the extensions configuration with:
 <code>
-No parameter, the application will use the VoiceXML accounts (match called number with accounts numbers) : Vxml()
+*CLI> extensions reload
-Pass the URL as the appplication parameter. Example : Vxml(file://tmp/test.vxml)
-Pass the account name or the account number. Example: Vxml(test)
-Pass the “@” to allocate a VoiceXML channel and pass the execution to this dialplan extension. Example : Vxml(@600)
 </code>
-Set the VXML_URL variable before executing the vxml application.
-Don't pass any parameter, and use the configuration accounts section. If account number match with the called number, its URL(s) and parameters will be use.
-The following describes how to execute a VoiceXML session.
+Call the service by calling:
+<code>
+SIP:888@<your server address>
+</code>
-==== Variables ====
+==== Voximal variables ====
 Variables to set before or filled after the Vxml() execution :
-** VXML_URL **
+** VOXIMAL_URL **
-If the variable VXML_URL has been set when vxml runs, the value of that variable will be used for the URL unless the parameter is not set to the application.
+If the variable VOXIMAL_URL has been set when vxml runs, the value of that variable will be used for the URL unless the parameter is not set to the application.
-** VXML_LOCAL **
+** VOXIMAL_LOCAL **
 Force the called number (variable in VoiceXML context session.connection.local.uri).
-** VXML_REMOTE **
+** VOXIMAL_REMOTE **
 Force the caller number (variable in VoiceXML context, session.connection.remote.uri).
-** VXML_MARK **
+** VOXIMAL_MARK **
 Allow to add his value/mark in the VoiceXML browser logs associated to this call/VoiceXML session.
-** VXML_ID **
+** VOXIMAL_ID **
 If the variable VXML_ID has been set when vxml runs, the VoiceXML session ID variable called “telephone.id” is set with this value (in the VoiceXML execution session context).
-** VXML_PARAM **
+** VOXIMAL_PARAM **
-If the variable VXML_PARAM (VXML_AAI is an alias) has been set when vxml runs, the value of that variable will be used as “telephone.param” (in the VoiceXML execution session context) and session.connection.aai.
+If the variable VOXIMAL_PARAM (VOXIMAL_AAI is an alias) has been set when vxml runs, the value of that variable will be used as “telephone.param” (in the VoiceXML execution session context) and session.connection.aai.
-** VXML_RESULT **
+** VOXIMAL_RESULT **
-After execution, the VoiceXML result of <exit> tag and the property ‘expr’ are accessible by the variable VXML_RESULT.
+After execution, the VoiceXML result of <exit> tag and the property ‘expr’ are accessible by the variable VOXIMAL_RESULT.
-** VXML_ERROR **
+** VOXIMAL_ERROR **
 After execution, the VoiceXML application notify the error cause, if the VoiceXML session cannot be launched.
-  * VXML_ERROR=(empty) ; No error occurs.
+  * VOXIMAL_ERROR=(empty) ; No error occurs.
-  * VXML_ERROR=INITALISATION ; Session refused, Asterisk module not connected to the VoiceXML browser.
+  * VOXIMAL_ERROR=INITALISATION ; Session refused, Asterisk module not connected to the VoiceXML browser.
-  * VXML_ERROR=LICENSE ; Session refused, license locking
+  * VOXIMAL_ERROR=LICENSE ; Session refused, license locking
-  * VXML_ERROR=ACCOUNT_LIMIT ; Session refused, max session for the account reached.
+  * VOXIMAL_ERROR=ACCOUNT_LIMIT ; Session refused, max session for the account reached.
-  * VXML_ERROR=SPEECH ; Session refused, cannot allocate the Speech (ASR) ressource.
+  * VOXIMAL_ERROR=SPEECH ; Session refused, cannot allocate the Speech (ASR) ressource.
-  * VXML_ERROR=TTY/TDD ; Session refused, no TTD availabe.
+  * VOXIMAL_ERROR=TTY/TDD ; Session refused, no TTD availabe.
-  * VXML_ERROR=BILLING ; Session refused, billing interface refuse the session.
+  * VOXIMAL_ERROR=BILLING ; Session refused, billing interface refuse the session.
-  * VXML_ERROR=INTERPRETER ; Session refused, critical error with the VoiceXML browser connection.
+  * VOXIMAL_ERROR=INTERPRETER ; Session refused, critical error with the VoiceXML browser connection.
-===== Examples =====
+==== Asterisk global variables ====
+You can set and get variable at any moment from the VoiceXML syntax using the <transfer> tag :
+** GET **
-Example use with an URL parameter:
 <code>
-[incoming]
+     <transfer name="getvar" bridge="true" dest="execute:get(ID)" />
-exten => s,1,Answer
+     <block>
-exten => s,n,Wait(3)
+       <prompt>
-exten => s,n,Vxml(http://links.i6net.com/index.vxml)
+         End of Transfer test <value expr="getvar$.value" />.
-exten => s,n,Hangup
+       </prompt>
+     </block>
 </code>
-Example to catch the Vxml() errors :
+** SET **
 <code>
-exten => _X.,1,Vxml()
+     <transfer name="toto" bridge="true" dest="execute:set(MOMO)=10">
-exten => _X.,n,NoOp(${VXML_ERROR})
+     </transfer>
-exten => _X.,n,GotoIf($["${VXML_ERROR}" == ""]?hangup)
-exten => _X.,n,Busy()
-exten => _X.,n(hangup),Hangup()
 </code>
 ===== Asterisk Online Help ======
 Online help can be accessed by typing the following command at the CLI prompt:
-*CLI> help vxml
+<code>
+*CLI> help voximal
+</code>
 ===== CLI Management Commands ======
-Now your VXI* VoiceXML browser and Asterisk PBX are running, you can manage the VXML service using the Asterisk prompt *CLI>:
+Now your Voximal and Asterisk PBX are running, you can manage the Voximal using the Asterisk prompt *CLI>:
 <code>
-*CLI> vxml debug
+*CLI> voximal debug
 </code>
-Enable VoiceXML debugging for the Asterisk application.
+Enable Voximal debugging for the Asterisk application.
 <code>
-*CLI> vxml debug interpreter all
+*CLI> voximal debug interpreter
 </code>
-Enable VoiceXML debugging for the interpreter application ().
+Enable Voximal debugging for the interpreter application.
 <code>
-*CLI> vxml no debug
+*CLI> voximal no debug
 </code>
-This command disables VoiceXML debugging for the Asterisk application.
+This command disables Voximal debugging for the Asterisk application.
 <code>
-*CLI> vxml no interpreter debug
+*CLI> voximal no interpreter debug
 </code>
-This command disables VoiceXML debugging for the interpreter application.
+This command disables Voximal debugging for the interpreter application.
 <code>
-*CLI> vxml show cache / vxml cache show
+*CLI> voximal show cache / voximal cache show
 </code>
 Print the files in cache (if debug mode is enabled) and/or the number of file in the cache.
 <code>
-*CLI> vxml cache clear
+*CLI> voximal cache clear
 </code>
 Delete all the files in the cache.
 <code>
-*CLI> vxml cache purge
+*CLI> voximal cache purge
 </code>
 Delete all the files in the cache older than the maxage parameter set in the configuration.
 <code>
-*CLI> vxml show license
+*CLI> voximal show license
 </code>
 Use this command to show the license information.
 <code>
-*CLI> vxml reload
+*CLI> voximal reload
 </code>
 Reload the configuration.
 <code>
-*CLI> vxml show configuration
+*CLI> voximal show configuration
 </code>
 Use this command to show the configuration summary of VoiceXML interpreter.
 <code>
-*CLI> vxml show accounts
+*CLI> voximal show accounts
 </code>
 Show the accounts configured.
 <code>
-*CLI> vxml show account <number>
+*CLI> voximal show account <number>
 </code>
 Show the accounts details of the account ID specified.
 <code>
-*CLI> vxml show statitiscs
+*CLI> voximal show statitiscs
 </code>
 Provides a dump statistics on VoiceXML interpreter
 <code>
-*CLI> vxml show dates
+*CLI> voximal show dates
 </code>
 Provides a dump dates on VoiceXML interpreter
-*CLI> vxml show sessions
+*CLI> voximal show sessions
 </code>
 Provides a dump sessions on VoiceXML interpreter.
 <code>
-*CLI> vxml show session
+*CLI> voximal show session
 </code>
 Provides a full dump session on VoiceXML interpreter.
 <code>
-*CLI> vxml originate chantype/number=application(parameters)
+*CLI> voximal originate chantype/number=application(parameters)
 </code>
 Originate an outgoing call, you can request to use a VoiceXML session.
@@ Line 258: / Line 304: @@
 The following entries are the Asterisk CLI commands for the VoiceXML browser.
-===== VoiceXML example ======
+===== Examples =====
 Add extensions to the Asterisk dial plan /etc/asterisk/extensions.conf:
+Example use with an URL parameter:
 <code>
-exten => 888,1,Answer
+[incoming]
-exten => 888,n,Wait(3)
+exten => 888,1,Answer
-exten => 888,n,Vxml(file:///root/example.vxml)
+exten => 888,n,Wait(3)
+exten => 888,n,Voximal(http://localhost/vxml/index.vxml)
 exten => 888,n,Hangup
+</code>
+Example to catch the Vxml() errors :
+<code>
+exten => _X.,1,Voximal()
+exten => _X.,n,NoOp(${VOXIMAL_ERROR})
+exten => _X.,n,GotoIf($["${VOXIMAL_ERROR}" == ""]?hangup)
+exten => _X.,n,Busy()
+exten => _X.,n(hangup),Hangup()
 </code>
@@ Line 299: / Line 357: @@
 </code>
+===== Load Balancer =====
+Example using the Dialplan and 4 different accounts (with differents ASR and TTS ressources).
+<code>
+exten => s,1,NoOp(Balancing)
+exten => s,n,Set(ACCOUNTMAX=4)
+exten => s,n,Set(TRIES=0)
+exten => s,n,Set(ACCOUNT=${RAND(1,${ACCOUNTMAX})})
+exten => s,n(retry),Set(TRIES=$[${TRIES} + 1])
+exten => s,n,Voximal(account${ACCOUNT})
+exten => s,n,ExecIf($["${VOXIMAL_ERROR}" = ""]?Goto(app-blackhole,hangup,1))
+exten => s,n,ExecIf($["${TRIES}" = "${ACCOUNTMAX}"]?Goto(app-blackhole,hangup,1))
+exten => s,n,Set(ACCOUNT=$[${ACCOUNT} + 1])
+exten => s,n,ExecIf($[${ACCOUNT} = ${ACCOUNTMAX}]?Set(ACCOUNT=1))
+exten => s,n,goto(s,retry)
+</code>
 ===== Troubleshooting (for Support) =====
@@ Line 308: / Line 383: @@
 <code>
-/tmp/log.txt (default configuration)
+/var/log/voximal/log.txt (default configuration)
 </code>
 **Log Files**
-The log files contain information about the operation of the VoiceXML Browser. The file is /tmp/log.txt, which details the VoiceXML processing on the VoiceXML Browser.
+The log files contain information about the operation of the VoiceXML Browser. The file is /var/log/voximal/log.txt, which details the VoiceXML processing on the VoiceXML Browser.
-If a failure occurs and you need to contact I6NET support (at support@i6net.com), they may ask you to activate traces to allow analysis of the system functions and make a complete appraisal of the problem. To do so you must follow these
+If a failure occurs and you need to contact Voximal support (at support@voximal.com), they may ask you to activate traces to allow analysis of the system functions and make a complete appraisal of the problem. To do so you must follow these
 procedures:
-Edit the configuration file client.cfg in /etc/openvxi/.
+Edit the configuration file voximald.conf in /etc/.
 The levels are defined by these lines which are the# API/general log traces for each component:
@@ Line 343: / Line 418: @@
 To enable a level, set the 1 value and 0 to disable.
-To validate the modifications, the VoiceXML interpreter must be restarted.  A simple way to do this is to stop and restart this application with the Asterisk and VoiceXML script:
+To validate the modifications, the Voxiaml interpreter must be restarted.
-<code>
+The interpreter is restarted if you restart the Asterisk.
-# /etc/init.d/asterisk stop
-# /etc/init.d/vxml stop
-# /etc/init.d/vxml start
-# /etc/init.d/asterisk start
-</code>
-The log file is generated in the temporary directory, and is named log.txt.  The location and filename are configurable. To purge the file type:
+The log file is generated in /var/log/voxiaml, and is named log.txt.  The location and filename are configurable. To purge the file type:
 <code>
-# > /tmp/log.txt
+# > /var/log/voximal/log.txt
 </code>
 NOTE:
-   - Never delete the /tmp/log.txt directly, otherwise you should restart the VoiceXML browser to generate a new one.
+   - Never delete the log.txt directly, otherwise you should restart the Voximal to generate a new one.
    - An Apache/PHP script exists generate the traces from a standard Internet browser (Internet Explorer, Mozilla/firefox...). Get it from our web site
    - At the end of the trace record, don’t forget to stop it to recover optimal real time function. With the V4.x release, you can dynamically enable/disable the interpreter traces with an Asterisk *CLI> command.
@@ Line 364: / Line 434: @@
 Full traces:
 <code>
-*CLI> vxml debug interpreter
+*CLI> voximal debug interpreter
 </code>
 Disable the interpreter traces:
 <code>
-*CLI> vxml no debug interpreter
+*CLI> voximal no debug interpreter
 </code>
@@ Line 375: / Line 445: @@
 To determine how many VoiceXML sessions are currently active on the system, use the statistics dump on the CLI. This command displays the current number of sessions on the VoiceXML Browser:
 <code>
-*CLI> vxml show statistics
+*CLI> voximal show statistics
 </code>