Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision | ||
installation_guide:asterisk:start [2016/02/05 08:59] – [VoiceXML Asterisk module] borja | installation_guide:asterisk:start [2017/01/25 21:45] – [Examples] borja | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Asterisk integration ====== | + | ====== |
- | ===== Getting Started | + | ===== The Asterisk Module |
- | Once you have completed installing | + | The Voximal |
- | The configuration file format is described in detail in a comment block at the top of the sample configuration file, / | + | |
- | NOTE: | + | For more information on applications, |
+ | 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: |
+ | < | ||
+ | *CLI> core show applications | ||
+ | </ | ||
- | Once you have made a backup copy, review the properties in the configuration file and modify their settings as appropriate. | + | For example, the voximal application: |
+ | < | ||
+ | *CLI> core show application voximal | ||
+ | </ | ||
- | 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 / | + | |
- | 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. | + | < |
+ | Voximal([URL|Name|Number]) | ||
+ | </ | ||
- | ===== Webserver Configuration | + | The URL can by set with different ways : |
+ | < | ||
+ | No parameter, the application will use the VoiceXML accounts | ||
+ | Pass the URL as the appplication parameter. Example : Voximal(file:// | ||
+ | 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) | ||
+ | </ | ||
+ | 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. | + | The following describes how to execute |
- | For the MIME content type for VoiceXML documents, a value of application/ | + | |
- | ^MIME Content ^Type Description^ | ||
- | |audio/ | ||
- | |audio/ | ||
- | |audio/ | ||
- | |audio/ | ||
- | |audio/ | ||
- | |video/ | ||
- | |video/ | ||
- | 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 |
+ | Two configuration files are used : | ||
- | ===== The Asterisk Module ===== | + | * VoiceXML interpreter configuration file (to overwrite default settings) |
- | The Voximal installs the app_voximal | + | |
- | For more information on applications, | + | |
- | To show details of how you use that particular application in this file (the Asterisk Dial plan). | + | ==== Configuration example ==== |
+ | |||
+ | Example: | ||
- | Type: | ||
< | < | ||
- | *CLI> core show applications | + | ; VoiceXML Configuration |
- | </ | + | ; |
+ | [general] | ||
+ | wav_codec=gsm | ||
+ | videosilence=; | ||
+ | audiosilence=; | ||
+ | debug=4 | ||
+ | video=yes | ||
+ | |||
+ | [license] | ||
+ | max=100 | ||
+ | key=… | ||
+ | |||
+ | [account1] | ||
+ | name=Test1 | ||
+ | url=http:// | ||
+ | max=1 | ||
+ | |||
+ | [account2] | ||
+ | name=Test2 | ||
+ | url=http:// | ||
+ | max=3 | ||
+ | dialformat=SIP/ | ||
+ | </ | ||
+ | |||
+ | 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 / | ||
- | For example, the voximal application: | ||
< | < | ||
- | *CLI> core show application voximal | + | [default] |
+ | |||
+ | exten => 981001001, | ||
+ | exten => 981001002, | ||
+ | exten => 981001003, | ||
</ | </ | ||
- | ===== VoiceXML Asterisk Application ===== | + | 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/ | ||
- | Application that launch a VoiceXML session in the asterisk channel and when complete, return control. | + | < |
+ | CLI*> diaplan reload | ||
+ | CLI*> voximal reload | ||
+ | CLI*> voximal show accounts | ||
+ | </ | ||
- | ==== Syntax ==== | + | Example: |
+ | Add extensions to the Asterisk dial plan / | ||
< | < | ||
- | Vxml([URL|Name|Number]) | + | exten => 888, |
+ | exten => 888,n,Wait(3) | ||
+ | exten => 888, | ||
+ | exten => 888, | ||
</ | </ | ||
- | The URL can by set with different ways : | + | You can create and edit the file / |
+ | |||
+ | This example will work if you have text-to-speech configured. | ||
< | < | ||
- | No parameter, the application will use the VoiceXML accounts (match called number with accounts numbers) : Vxml() | + | <?xml version=" |
- | Pass the URL as the appplication parameter. Example : Vxml(file://tmp/test.vxml) | + | <vxml version = "2.0" xmlns=" |
- | 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) | + | < |
+ | </ | ||
+ | </ | ||
</ | </ | ||
- | 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 | + | Save the file in the same directory as the VoiceXML |
+ | Reload the extensions configuration with: | ||
+ | < | ||
+ | *CLI> extensions reload | ||
+ | </ | ||
+ | |||
+ | Call the service by calling: | ||
+ | |||
+ | < | ||
+ | SIP: | ||
+ | </ | ||
+ | |||
==== Variables ==== | ==== Variables ==== | ||
Line 89: | Line 142: | ||
Variables to set before or filled after the Vxml() execution : | Variables to set before or filled after the Vxml() execution : | ||
- | ** VXML_URL | + | ** VOXIMAL_URL |
- | If the variable | + | If the variable |
- | ** VXML_LOCAL | + | ** VOXIMAL_LOCAL |
Force the called number (variable in VoiceXML context session.connection.local.uri). | 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). | 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/ | Allow to add his value/mark in the VoiceXML browser logs associated to this call/ | ||
- | ** 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). | 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 | + | If the variable |
- | ** VXML_RESULT | + | ** VOXIMAL_RESULT |
- | After execution, the VoiceXML result of < | + | After execution, the VoiceXML result of < |
- | ** VXML_ERROR | + | ** VOXIMAL_ERROR |
After execution, the VoiceXML application notify the error cause, if the VoiceXML session cannot be launched. | 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 ===== | ||
- | Example use with an URL parameter: | ||
- | < | ||
- | [incoming] | ||
- | exten => s, | ||
- | exten => s, | ||
- | exten => s, | ||
- | exten => s,n,Hangup | ||
- | </ | ||
- | Example to catch the Vxml() errors : | ||
- | < | ||
- | exten => _X., | ||
- | exten => _X., | ||
- | exten => _X., | ||
- | exten => _X., | ||
- | exten => _X., | ||
- | </ | ||
===== Asterisk Online Help ====== | ===== Asterisk Online Help ====== | ||
Online help can be accessed by typing the following command at the CLI prompt: | Online help can be accessed by typing the following command at the CLI prompt: | ||
- | *CLI> help vxml | + | *CLI> help voximal |
===== CLI Management Commands ====== | ===== CLI Management Commands ====== | ||
- | Now your VXI* VoiceXML browser | + | Now your Voximal |
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
- | Enable | + | Enable |
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
- | Enable | + | Enable |
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
- | This command disables | + | This command disables |
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
- | This command disables | + | This command disables |
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Print the files in cache (if debug mode is enabled) and/or the number of file in the cache. | Print the files in cache (if debug mode is enabled) and/or the number of file in the cache. | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Delete all the files in the cache. | Delete all the files in the cache. | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Delete all the files in the cache older than the maxage parameter set in the configuration. | Delete all the files in the cache older than the maxage parameter set in the configuration. | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Use this command to show the license information. | Use this command to show the license information. | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Reload the configuration. | Reload the configuration. | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Use this command to show the configuration summary of VoiceXML interpreter. | Use this command to show the configuration summary of VoiceXML interpreter. | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Show the accounts configured. | Show the accounts configured. | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Show the accounts details of the account ID specified. | Show the accounts details of the account ID specified. | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Provides a dump statistics on VoiceXML interpreter | Provides a dump statistics on VoiceXML interpreter | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Provides a dump dates on VoiceXML interpreter | Provides a dump dates on VoiceXML interpreter | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Provides a dump sessions on VoiceXML interpreter. | Provides a dump sessions on VoiceXML interpreter. | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Provides a full dump session on VoiceXML interpreter. | Provides a full dump session on VoiceXML interpreter. | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Originate an outgoing call, you can request to use a VoiceXML session. | Originate an outgoing call, you can request to use a VoiceXML session. | ||
Line 244: | Line 280: | ||
The following entries are the Asterisk CLI commands for the VoiceXML browser. | The following entries are the Asterisk CLI commands for the VoiceXML browser. | ||
- | ===== VoiceXML example ====== | + | ===== Examples |
Add extensions to the Asterisk dial plan / | Add extensions to the Asterisk dial plan / | ||
+ | |||
+ | Example use with an URL parameter: | ||
< | < | ||
- | exten => 888, | + | [incoming] |
- | exten => 888, | + | exten => 888, |
- | exten => 888,n,Vxml(file:///root/example.vxml) | + | exten => 888, |
+ | exten => 888,n,Voximal(http://localhost/vxml/index.vxml) | ||
exten => 888, | exten => 888, | ||
+ | </ | ||
+ | |||
+ | Example to catch the Vxml() errors : | ||
+ | < | ||
+ | exten => _X., | ||
+ | exten => _X., | ||
+ | exten => _X., | ||
+ | exten => _X., | ||
+ | exten => _X., | ||
</ | </ | ||
Line 285: | Line 333: | ||
</ | </ | ||
+ | ===== Load Balancer ===== | ||
+ | |||
+ | Example using the Dialplan and 4 different accounts (with differents ASR and TTS ressources). | ||
+ | |||
+ | < | ||
+ | exten => s, | ||
+ | exten => s, | ||
+ | exten => s, | ||
+ | exten => s, | ||
+ | exten => s, | ||
+ | exten => s, | ||
+ | exten => s, | ||
+ | exten => s, | ||
+ | exten => s, | ||
+ | exten => s, | ||
+ | exten => s, | ||
+ | </ | ||
===== Troubleshooting (for Support) ===== | ===== Troubleshooting (for Support) ===== | ||
Line 294: | Line 359: | ||
< | < | ||
- | /tmp/log.txt (default configuration) | + | /var/ |
</ | </ | ||
**Log Files** | **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/ |
- | If a failure occurs and you need to contact | + | If a failure occurs and you need to contact |
procedures: | procedures: | ||
- | Edit the configuration file client.cfg in /etc/openvxi/. | + | Edit the configuration file voximald.conf in / |
The levels are defined by these lines which are the# API/general log traces for each component: | The levels are defined by these lines which are the# API/general log traces for each component: | ||
Line 329: | Line 394: | ||
To enable a level, set the 1 value and 0 to disable. | To enable a level, set the 1 value and 0 to disable. | ||
- | To validate the modifications, | + | To validate the modifications, |
- | < | + | The interpreter |
- | # /etc/init.d/asterisk stop | + | |
- | # / | + | |
- | # / | + | |
- | # / | + | |
- | </ | + | |
- | The log file is generated in the temporary directory, and is named log.txt. | + | The log file is generated in / |
< | < | ||
- | # > /tmp/log.txt | + | # > /var/ |
</ | </ | ||
NOTE: | NOTE: | ||
- | - Never delete the /tmp/log.txt directly, otherwise you should restart the VoiceXML browser | + | - Never delete the log.txt directly, otherwise you should restart the Voximal |
- An Apache/PHP script exists generate the traces from a standard Internet browser (Internet Explorer, Mozilla/ | - An Apache/PHP script exists generate the traces from a standard Internet browser (Internet Explorer, Mozilla/ | ||
- 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/ | - 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/ | ||
Line 350: | Line 410: | ||
Full traces: | Full traces: | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Disable the interpreter traces: | Disable the interpreter traces: | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||
Line 361: | Line 421: | ||
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: | 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: | ||
< | < | ||
- | *CLI> | + | *CLI> |
</ | </ | ||