Howto:Configure the innovaphone Voicemail: Difference between revisions

From innovaphone wiki
Jump to navigation Jump to search
(→‎URL Query String Variables: Added "$_defaultpin")
(→‎Quick Reference For innovaphone Voicemail: Added "Special-Purpose Script Variables, Firmware Version 13r1")
Line 427: Line 427:
* [[Howto:Quick Reference For innovaphone Voicemail|Quick Reference For innovaphone Voicemail]]
* [[Howto:Quick Reference For innovaphone Voicemail|Quick Reference For innovaphone Voicemail]]
The article outlines the menu structure and provides a few operational hints from a user's perspective.
The article outlines the menu structure and provides a few operational hints from a user's perspective.
==Special-Purpose Script Variables, Firmware Version 13r1==
From on 13r1 a few script variables with special meaning were introduced. Among others, this enables a script to read the static configuration underneath ''PBX/Config/Authentication/Email Verification''.
;$_pbx_auth_email_server:
Retrieves ''PBX/Config/Authentication/Email Verification/SMTP server''
;$_pbx_auth_email_host:
Retrieves ''PBX/Config/Authentication/Email Verification/Client host name''
;$_pbx_auth_email_addr:
Retrieves ''PBX/Config/Authentication/Email Verification/Email address''
;$_pbx_auth_email_usr:
Retrieves ''PBX/Config/Authentication/Email Verification/Username''
;$_pbx_auth_email_pwd:
Retrieves ''PBX/Config/Authentication/Email Verification/Password''
;$_pbx_auth_email_sender:
Retrieves ''PBX/Config/Authentication/Email Verification/Sender name''
;$_pbx_version_soap:
Retrieves the firmware version. E.g. "1300" for 13r1.


==Known Problems==
==Known Problems==

Revision as of 15:52, 18 April 2019

The innovaphone voicemail (VM) is implemented as a PBX object. An answering machine can be assigned to each PBX user. The VM is script-driven and controlled by means of DTMF touchtones. It features a built-in WebDAV client, enabling the VM to communicate to an external WebDAV server, which serves as the mass-storage for audio files, script files and user-directories. The VM script and pre-recorded audio files are subject to be provided by innovaphone. Message Waiting Indication (MWI) is supported.


Applies To

This information applies to

  • innovaphone PBX, V6 and Higher

Supporting The innovaphone Voicemail

Tracing

For a decent supportable trace

  • Activate the trace checkmark within the UI of the voicemail object
  • Append the parameter $_trace=251 to the configured script URL, alike so:

https://1.2.3.4/drive/CF0/de/vm.xml?$_trace=251

More Information

System Requirements

Voicemail license: The innovaphone voicemail requires licensing. The number of acquired voicemail licenses must be equal or greater than the number of PBX basic licenses.

WebDAV server, e.g.: Apache 2.x, IIS W2K, IIS W3K, or with V6 sr1 the compat flash drive (no external WebDAV server needed)

Innovaphone will provide you with an XML script, that represents the actual voicemail. In addition you will get a set of files with *.g711a, *.g711u, *.g722, *.opus-wb, *.opus-nb and *.g729 extensions. These files contain the audio snippets and the menu prompts, that the voicemail requires.

Installation, WebDAV

A few preconditions are assumed as basis for the following few installation and configuration steps:

  • The number of the VM object is 66.
  • The number of a sample user test is 49.
  • The IP address of the WebDAV server is 192.168.0.5.
  • The root directory, that contains the VM script and the pre-recorded audio files is c:\Inetpub\webdav\vm\en which corresponds to the URL http://192.168.0.5/webdav/vm/.
  • The file name of the voicemail XML script is vm.xml.

Creating the Voicemail Object

Proceed to Administration/PBX/Objects.

Distributing the Voicemail Script and Pre-Recorded Audio Files

The download section offers ZIP files and a Windows installation program. See #Download for how to find the download site.

  • ZIP files
    • Download the ZIP file for the language your are interested in (e.g. vm-de, vm-en, ...) from the apps package on the innovaphone download area, V6 Apps.
    • Un-ZIP the file. This step creates a language specific sub-directory that may be copied onto the CF-card.
  • Windows installation program
    • Download the installation program for the innovaphone voicemail from the innovaphone download area.
    • Start the installer program (innovaphone-voicemail-install.exe).
    • The installer will be asking for a target directory. Enter c:\Inetpub\webdav\vm\. Now, the installer will copy all of the localized voicemail files into language specific sub-directories. The english files will remain under the absolute path c:\Inetpub\webdav\vm\en\.

Configuration

Please note, that a user's VM number is the number of the VM object, that you assigned here, plus the user's number.

Example: If a user has the number 49 and the number of the VM object is 66, then the user's corresponding VM number will be 6649.

IP Phone Configuration

V6, SR1: Recommended Configuration

A user may wish to manually activate or deactivate a CFU diversion to his VM.

  • Browse to the IP phone of the user 49:test:
  • Proceed to Configuration/RegistrationX/Function Keys.
  • Select a free function key, choose Call Forwarding and click on new.
  • A new window will open. Enter AM-on under Idle State/Text.
  • Enter AM-off under Active State [1]/Text.
  • Enter 6649 into Active State [1]/Text/Always/Number.
  • Click on OK.

An additional function key is required to present the MWI and to quick-dial the VM:

  • Proceed to Configuration/RegistrationX/Function Keys.
  • Select a free function key, choose Message Waiting and click on new.
  • A new window will open. Enter AM under Idle State/Text.
  • Select the letter icon under Active State/Icon.
  • If you desire, then choose LED/blink.
  • Enter 6649 into Message Center Account/Number.
  • Click on OK.

V6, SR2: Recommended Configuration

The SR2 configuration adapts to mass-deployment requirements, in such that the set of required configuration parameters can be distributed identically among all affected phones.

A user may wish to manually activate or deactivate a CFU diversion to his VM.

  • Browse to the IP phone of the user 49:test:
  • Proceed to Configuration/RegistrationX/Function Keys.
  • Select a free function key, choose Call Forwarding and click on new.
  • A new window will open. Enter AM-on under Idle State/Text.
  • Enter AM-off under Active State [1]/Text.
  • Enter 66 into Active State [1]/Text/Always/Number.
  • Click on OK.

An additional function key is required to present the MWI and to quick-dial the VM:

  • Proceed to Configuration/RegistrationX/Function Keys.
  • Select a free function key, choose Message Waiting and click on new.
  • A new window will open. Enter AM under Idle State/Text.
  • Select the letter icon under Active State/Icon.
  • If you desire, then choose LED/blink.
  • Enter 66 into Message Center Account/Number.
  • Activate the Append Own Number checkmark.
  • Click on OK.

Deploying the MWI Function Key By An Update Script

From on V6,SR2 the MWI key configuration can be designed to be applicable for all phones. The following excerpt shows how the resulting configuration line would look alike for our example.

mod cmd PHONE USER-UI/0 fkey-edit /id 0 /fkey_id 0 /fkey_type mwi /label mwi-off /icon letter /mwi.label mwi-on /mwi.icon letter-black /mwi.led blink /mwi.e164 66 /mwi.ext on /op OK
  • /mwi.e164 66 defines the MC number 66
  • /mwi.ext on activates the Append Own Number checkmark

Webserver Aspects

WebDAV in Common: As stated above, WebDAV is required for the VM to work.

What is WebDAV? In its long form it reads "Web-based Distributed Authoring And Versioning" and is specified in RFC2518. Technically is WebDAV a set of protocol extensions to the HTTP protocol. These extensions allow for some file i/o operations,that aren't covered by HTTP:

  • Renaming, moving, copying a file file.
  • Properties: That is, information retrieval about a certain file. E.g. the file creation time.

Webserver Authentication

If HTTP Authentication is required, configure a triple of URL,User,Password underneath Configuration/General/HTTP-Client.

In our example http://192.168.0.5/webdav/ may be entered as URL. Every URL that head-matches this URL and requires authentication will be authenticated with the user,password provided here.

Apache Webserver 2.x

The Apache supports WebDAV from on version 2.0 natively.

However, WebDAV must be enabled to be run. Please find the respective documentation page at apache.org under http://httpd.apache.org/docs/2.0/mod/mod_dav.html .

Test Environment: Our test environment was a RedHat Linux 8.x. The configuration file for httpd resides under /etc/httpd/conf/httpd.conf . The voicemail is located underneath /var/www/webdav/vm/.

Open httpd.conf with a text editor.

  • Ensure the modules required for WebDAV are being loaded

LoadModule dav_module modules/mod_dav.so LoadModule dav_fs_module modules/mod_dav_fs.so

  • Ensure, that WebDAV is enabled and that an alias is being created for webdav

Dav On Alias /webdav "/var/www/webdav"

  • In our test environment we didn't restrict access to the webdav directory

Options Indexes MultiViews Allow from all

An important aspect is the fact, that we had to apply chmod -R 766 to the /var/www/webdav directory. chmod -R 666 didn't suffice.

Without doing so, i.e. granting the read-/write-/execute-access, we received Forbidden responses when e.g. trying to read the filenames within a directory.

A potential delay source can be reverse DNS lookups. A webserver is trying to retrieve a DNS name for every source address it receives requests from. The drawback is, that every HTTP request is being delayed by the amount of time it takes to complete the reverse DNS lookup.

Within httpd.conf we therefore wrote HostNameLookups Off, in order to avoid DNS requests for logging purposes.

Please note further that access restrictions with DNS names, instead of IP addresses, will bypass this setting, i.e. will make the HostNameLookups Off -setting ineffective.

Microsoft Internet Information Server (IIS), W2K

As a testbed an IIS 5.0 was utilized on a Windows 2000 server. By default WebDAV is already enabled within IIS 5.0. However, no data is published.

  • To publish data simply.

Create a new virtual directory webdav within the default website by means of the IIS Admin. Allow read, write and browse operations being executed on that directory and underneath. Use the Windows Explorer to modify the security settings of the directory (and underneath) and set it to full access for everyone (It is left up to the Windows experts how to restrict this further).

Microsoft Internet Information Server (IIS6), W2003

In contrast to Windows 2000 Server, Windows Server 2003 does not come with WebDAV being already enabled. In addition File extensions with *.g711a, *.g711u and *.g729 must be configured as a new Mime-Type. You must enable WebDAV from within the IIS Admin first. Files with the extension *.g711a, *.g711u and *.g729 will not be returned.

  • You must add *.g711a, *.g711u *.g729 as a Mime-Type, otherwise the audio files won't be accessible.

Pls. see: MS KB article Q326965 http://support.microsoft.com/kb/326965/en-us ,respectively http://support.microsoft.com/kb/326965/de-de for how to do this.

Browse to http://192.168.0.5/webdav/vm/ and try to download a g711a-file and a g729-file from within your browser. This step will prove, that the Mime-Types were successfully added.

Note: After the new Mime-Types were added an IIS6 restart seemed to be a MUST.

Microsoft Internet Information server (IIS7)

Two possibilities for authentication are available.

HTTPS With Basic Authentication

IIS7 does NOT support HTTP Basic Authentication without HTTPS/TLS. Therefore it is mandatory to run WebDAV towards the IIS7 on HTTPS and not on HTTP.

  • Within the Voicemail object a "https://.."-URL must be configured.
  • Under General/HTTP/Client a user/password tupel must be configured for the "https://.."-URL.
  • Within the IIS Admin it must be ensured that Basic Authentication is allowed.
  • Try calling the voicemail object. The request for the voicemail script is going to fail.
  • Watch out for a rejected certificate under General/Certificates and trust that certificate.
  • Try calling again the voicemail object. This time the request for the voicemail script should be succeeding.

HTTP With Digest Authentication

Tools clipart.png FIXME: "Information is vague. Practical confirmation needed. Detailing needed."

A user account must be configured within the Active Directory to allow it's password be cached. This is simply because the digest authentication needs to derive a challenge value from a password. That user account/password tupel must in turn be utilized for the innovaphone HTTP client.

We have had reports that digest authentication does not work with some IIS7 servers. Evaluation has shown that these servers do require MD5-sess instead of MD5 as endpoint authentication type.

Microsoft states For security reasons, Windows-based digest authentication only supports MD5-sess encryption over domain controllers that are running under Windows Server 2003. [1]. This suggests that authenticated HTTP access from an innovaphone box to an IIS7 using a domain account may not work at all as long as we do not support MD5-sess (which we don't do as of this writing (January 2012)). A possible fix may be to use a local server account (although this has not been tested).

Microsoft Internet Information server (IIS7.5)

Despite an allegedly configured server role WebDAV Publishing a WebDAV-connect wasn't possible until adding a WebDAV Authoring Rule by means of the IIS Admin.

  • Access for Entire Content
  • Grant Conten Access For All Users
  • Rights Read, Source, Write

Before administrating this step a PROPFIND was always honored by a 405/Method Not Allowed.


innovaphone own WebDav Server (Compact flash card slot)

Please see Installation, CompactFlash Card below.

Testing WebDAV Access

From within the Windows Explorer go to Tools/Map Network Drive.

Now you may test whether you can read files, write files, delete files, create directories.

User-Related Files And Directories

Our sample user has the number 49 and the name test. When this user calls his box 6649 for the first time, the VM will create a directory for him and underneath a pair of additional directories. The new directories for the user test are:

  • …/webdav/vm/test/. New voicemails will be copied here.
  • …/webdav/vm/test/personal. The personal greeting message resides here.
  • …/webdav/vm/test/store. When a message is stored, it is copied into this location.

If the directory creation fails, the call to the VM will be forcedly disconnected.

PIN Administration

Initially, there is a default PIN active. When being asked for a PIN, enter 8765.

The PIN can be changed by means of menu option 4.

The PIN can be reset administratively to the default by just deleting .../personal/pin.txt within a user's directory.

You should change the default PIN to a different value before installing the Voice Mail. This is done with a text editor in the vm.xml script. Change the value 8765 in function CheckPin and function EnterPin.

URL Query String Variables

URL Query String Variables are generally passed on to a script.

The following variables control the script's behaviour and may be applied within the configured script-URL alike: http://192.168.0.5/webdav/vm/vm.xml?$_nopin=true.

Multiple variables can be combined by an ampersand (&) alike: http://192.168.0.5/webdav/vm/vm.xml?$_nopin=true&$_pbxcoder=g711a.

  • $_nopin. Controls, whether a PIN must be entered.
    • true: Voicemail owner doesn't need to enter a PIN when calling from his extension.
    • false (default): A PIN must be entered

(Note: A PIN must always be entered when calling from "foreign" extensions)

  • $_initdelay: Controls, whether an initial silence prompt is going to be played to a caller. From on script version [vm.xml 60096].
    • 0(default): No silence prompt will be played.
    • a value greater than 0: A silence prompt of N seconds is going to be played. For hosting scenarios the recommended value is '1'.
  • $_pbxcoder. Allows to restrain the offered coder list, when executing <pbx-prompt> for files with "*.$coder" extensions.
    • The internal default is: $_pbxcoder=g729,g711a,g711u,g722,opus-wb,opus-nb
  • $_pbxfwd
    • true: diversions will be executed on <pbx-fwd>
    • false (default): diversions won't be executed on <pbx-fwd>
  • $_pbxmwidir. Allows to configure a parent directory for all user sub-directories and for all MWI operations. As default there is no such directory active.
  • $_pbxremhold
    • true (default): Rules whether caller will be sent a REMOTE-HOLD while executing <pbx-fwd>.
    • false: No REMOTE-HOLD is sent
  • $_noctl (from on v8hotfix8)
    • true: Control-calls (calls without media) will be rejected
    • false (default): no rejection
  • $_divconn (from on v9hotfix17)
    • true: Auto-Connect for calls being recognized as diverted or transferred calls
      • Note: Until V11r1sr2 the former default was true
    • false(default): No automated connection for diverted/transferred calls.

Note: It is recommended to configure $_divconn=false in scenarios with remote media streaming(via an active registration at the VM object).

  • $_trace, decimal number: Controls verbosity of tracing outputs. The following values can be added. Everything can be traced by simply entering 255 (i.e. $_trace=255).
    • 1: errors, 2: interpreter, 4: parsing, 8: code, 16: store operations, 32: http operations (during <exec>), 64: <debug> statements, 128: webmedia
  • $_leg2tweak (from on v9hotfix21) controls <pbx-getcallinfo out-leg2=".."/>
    • true(default): set leg2 to <ext-nr> from <vm-nr>+<ext-nr>
    • false: set leg2 according to received divertingInfoLeg2 facility
  • $_trailhash (from on v9hotfix21) controls <pbx-getcallinfo out-cdpn=".."/>
    • true: pass trailing (en-bloc) '#' into cdpn
    • false(default): don't pass trailing (en-bloc) '#' into cdpn
  • $_pbxfwdrel controls <pbx-fwd> (from on v10sr5)
    • conn: release all interpreter resources after a successful connect. No further scripting affects the call.
    • imm: release all interpreter resources immediately on the execution of the <pbx-fwd> statement. No further scripting affects the call.
    • false(default): No tweaks apply. The script interpreter remains active.
  • $app activates settings, necessary for the App Platform's Voicemail App (v13r1 and later only)
    • on: Activate internal settings for the Voicemail App (only use this setting if the voicemail runs on the new App Platform)
    • off(default): No tweaks apply.
  • $_defaultpin configures a default pin (from on vm.xml, 60137)
    • E.g. to configure the default pin 123456
 http://a.b.c.d/vm.xml?$_defaultpin=123456

Installation, CompactFlash Card

Instead of using a WebDAV server you may want to use the local CompactFlash card as mass storage device. This section outlines how this can be accomplished.

Installing the Voicemail on a CompactFlash Card

Please see the article Howto:Installing the voicemail on a compact flash card.

The aforementioned configuration scenario, within the above chapter: Installation, WebDav, does also apply for an installation on a CompactFlash card. Please, refer to that chapter if you look for informations on how to generally configure a basic voicemail scenario, including the affected ip phone configuration.

Advanced Configuration

Maximum Message Length

By default, voicemail messages are limited to 50 seconds each. To change the maximum length (e.g. to 5 minutes), you have to change the following code line

<pbx-record url="$vm" sec="50"/>

to

<pbx-record url="$vm" sec="300"/>

Change Filename of the Recorded Messages of Voicemail

By default the vm.xml records the voice messages in the CF at UserBox with an Unique Name, type of GUID + Extension and this is also what is send to the user email when we set that option. Example : 2110d5f4e909d311baab0090332901b6-202.wav

We can change this filename format by editing the vm.xml approx. line 63:

replace

<store-getnew root="$sub" out-url="$vm"/>
<lib-strcat string="$vm" string2="-" out-string="$vm" />
<lib-strcat string="$vm" string2="$cgpn" out-string="$vm" />
<lib-strcat string="$vm" string2=".g711a" out-string="$vm" />

with

<store-getstat root="" name="NULL" out-wday="$wday" out-mday="$mday" out-mon="$mon" out-year="$year" out-hour="$hour" out-min="$min"/>
<store-get root="$sub" name="Date_" out-url="$vm"/>	
<lib-strcat string="$vm" string2="$year" out-string="$vm" />
<lib-strcat string="$vm" string2="_" out-string="$vm" />
<lib-strcat string="$vm" string2="$mon" out-string="$vm" />
<lib-strcat string="$vm" string2="_" out-string="$vm" />
<lib-strcat string="$vm" string2="$mday" out-string="$vm" />
<lib-strcat string="$vm" string2="_time_" out-string="$vm" />
<lib-strcat string="$vm" string2="$hour" out-string="$vm" />
<lib-strcat string="$vm" string2="_" out-string="$vm" />
<lib-strcat string="$vm" string2="$min" out-string="$vm" />	
<lib-strcat string="$vm" string2="_number-" out-string="$vm" />
<lib-strcat string="$vm" string2="$cgpn" out-string="$vm" />
<lib-strcat string="$vm" string2=".g711a" out-string="$vm" />

Doing this will obtain a filename with Date, Hour, Number and CGPN.

Leave Message to the VoiceMail Box of the original called User

By default the VoiceMail stores the voice message to the Mailbox of the Object performing diversion to the VoiceMail. E.g. if "User A" creates a call forward to the VoiceMail, the Mailbox is used to store the message is from "User A". In case "User A" creates a call forward to a Waiting Queue or Call Broadcast, and than from Call Broadcast Group to the VoiceMail, the message will be stored in the Mailbox of the Call Broadcast Group.

To change this behaviour and to store the Message always to the Mailbox of the originally called User, change the vm.xml as following:

search the line:

<pbx-getcallinfo out-cgpn="$cgpn" out-cdpn="$cdpn" out-leg2="$leg2"/>

and replace them with the following

<pbx-getcallinfo out-cgpn="$cgpn" out-cdpn="$cdpn" out-leg2="$leg2" out-leg2-orig="$leg3"/>

add the following code after the line

<switch var="$leg3">

 <case not-equal="">
   <assign out="$leg2" value="$leg3"/>
   <assign out="$_pbxcdpn" value="$leg3"/>
 </case>

</switch>

Sending of additional MWIs

The article deals with the question how a single voicemail box can be shared among a few users.

Custom Personal Announcement

Explains where to copy an externally generated personal announcement file.

A Simple Recording Solution On-Top of The innovaphone Voicemail

This article explains how a simple recording solution could be set up on-top of an innovaphone Voicemail.

Send Email MWI Notification From The innovaphone Voicemail

This functionality is available from on SR2 and allows to send MWI notifications by email.

Disable Mailbox Administration from extern

It is possible to log in into the voicemail administration with a 9 as DTMF key while leaving a message. After entering the correct PIN, you can access the voicemail administration.

This may create problems, if you use an unsecure PIN, no PIN or the default PIN.

To disable this function you have to change the following code line inside the function AnsweringMachine in your vm.xml.

<function define="AnsweringMachine">

 <pbx-record url="$vm" sec="50" />

</function>

to

<function define="AnsweringMachine">

 <pbx-record url="$vm" sec="50" barge-in="false" />

</function>

Quick Reference For innovaphone Voicemail

The article outlines the menu structure and provides a few operational hints from a user's perspective.

Special-Purpose Script Variables, Firmware Version 13r1

From on 13r1 a few script variables with special meaning were introduced. Among others, this enables a script to read the static configuration underneath PBX/Config/Authentication/Email Verification.

$_pbx_auth_email_server

Retrieves PBX/Config/Authentication/Email Verification/SMTP server

$_pbx_auth_email_host

Retrieves PBX/Config/Authentication/Email Verification/Client host name

$_pbx_auth_email_addr

Retrieves PBX/Config/Authentication/Email Verification/Email address

$_pbx_auth_email_usr

Retrieves PBX/Config/Authentication/Email Verification/Username

$_pbx_auth_email_pwd

Retrieves PBX/Config/Authentication/Email Verification/Password

$_pbx_auth_email_sender

Retrieves PBX/Config/Authentication/Email Verification/Sender name

$_pbx_version_soap

Retrieves the firmware version. E.g. "1300" for 13r1.

Known Problems

The VM makes use of V6’s media negotiation capabilities. This is why V5 endpoints are not supported.

Related Articles

Voicemail Installation

Voicemail on Compact Flash

Voicemail Customising

Voicemail Scripting

Download

The voicemail product can currently be found on the apps section of the innovaphone download site. This product is suitable for PBX firmware versions 6 and up.