Lyra AMD Answering Machine Detection

Owned by Nathaniel Halbrooks
Last updated: Mar 15, 2024 by Kelli Higdon
6 min read

 

This product is End-Of-Life. Please refer to the EOL page for more details: https://www.sangoma.com/support/end-of-product-life/

 

 

 

 

 

Introduction

The Lyra AMD software application from Sangoma provides the most accurate and resilient Answer Machine Detection (AMD) engine, enabling fast and reliable real-time call classification and drives the efficiency and quality of automated calling applications to unmatched levels.

Lyra AMD has been designed to work with Open Source Applications such as

  • Asterisk

  • FreeSWITCH
     

Lyra Specifications

 

Lyra Software Installation

The Lyra software installer is available from the Sangoma website. If you have not been provided with the necessary URI, contact Sangoma at the following e-mail address: techdesk@sangoma.com
You must download this installer to your system before proceeding with the installation. Before starting the installation, exit all other applications.

Windows Installation

  • Step 1. Download Lyra AMD software installer for windows from here.

  • Step 2. Once the download is complete, unzip the file to the Desktop.

  • Step 3. Open the extracted directory.

  • Step 4. Run the SangomaNetBorderPlatform.2.X.X.Setup.exe 

  • Step 5. Read the License Agreement and then click "I Agree" (unless you don't. Then you should probably exit).

  • Step 6. Where it says "Call Progress Analysis Service" click the check box that is appropriate for your area of the world. For North America you would check the "North American models". Then click "Next".

  • Step 7. Next you will be prompted on where you want to install NetBorder. Change this if you like, then click "Install".

  • Step 8. During the install process, Windows may ask you if you want to unblock certain ports. If it does it means that the firewall is not properly configured. It needs to allow traffic on the following ports UDP 5060 to 5069, UDP 10000 to 20000, and TCP 5060 to 5069.

  • Step 9. Once the installer is complete click the "Close" button.

  • Step 10. In the Windows Start menu click find the Sangoma NetBorder section and click on the "Start Session Controller" short cut.

  • Step 11. Go to the Windows Control Panel and double click on "Administrative Tools".

  • Step 12. Double click on Services.

  • Step 13. Scroll down to the Sangoma services and verify that the "Sangoma NetBorder Session Controller" and "Sangoma NetBorder Call Progress Analysis" services are both started. If they have not you will need to contact Sangoma's technical support staff.

  • Step 14. To start these services automatically when Windows starts right click each of them and click on Properties. Then change the Startup Type from Manual to Automatic.

  • Step 15. Reboot the windows system to verify that these services start on boot up.

  • Step 16. Once the windows system is back up, log in and go back to Services in the Administrative Tools (see step 16).

  • Step 17. Scroll back down to the Sangoma Section and verify that the "Sangoma NetBorder Session Controller" and "Sangoma NetBorder Call Progress Analysis" services started on their own. If not, this might be caused by issues with your version of Windows. Contact Sangoma technical support for more details.

  • Step 18. Open up My Computer and browser to the directory where you installed Sangoma. The default should be "C:\Program Files\Paraxip NetBorder\".

  • Step 19. Open the "config" directory.

  • Step 20. Right click the "call-analyzer-service.properties" file and click Open.

  • Step 21. Choose "Select the program from a list" and click OK.

  • Step 22. Choose "WordPad" from the available programs and click OK.

  • Step 23. Change the line that reads "#netborder.net.primaryIPAddress=x.x.x.x" to "netborder.net.primaryIPAddress=IPADRESS" where IPADDRESS is the IP address of the windows system. If you have two IP addresses change this to the one where sangoma will be accepting the connections from the Asterisk/Freeswitch system (usually the internal IP, default is 127.0.0.1).

  • Step 24. Go back to the NetBorder config directory and double click call-analyzer-engine.properties file (note windows may now be hiding the ".properties" at the end of the filename).

  • Step 25. Change the line that reads "#netborder.net.primaryIPAddress=x.x.x.x" to "netborder.net.primaryIPAddress=IPADRESS" where IPADDRESS is the IP address of the windows system just like you did in the call-analyzer-service.properties file (default is 127.0.0.1)

  • Step 26. Restart the  Sangoma services as explained in steps 14 to 16.

 

Linux Installation 

NetBorder Call Analyzer is distributed on supported Linux distributions using the rpm format. Superuser (root) privileges are required to install.

  • Step 1. Download Lyra AMD software installer for linux.

  • Step 2. Once the download is complete, run the command rpm -i netborder-call-analyzer-2.<version>.<arch>.rpm

  • Step 3. Once installation is complete, check the status of the call analyzer service by runing the following command: service netborder-call-analyzer status

  • Step 4. If the service is not started, start it by running command: service netborder-call-analyzer start

  • Step 5. If the service fails to start,  you will need to contact Sangoma's technical support staff.

  • Step 6. cd to the "config" directory ( cd /opt/Sangoma_NetBorderCallAnalyzer/config)

  • Step 7. Edit "call-analyzer-service.properties" file as following:

  • Step 8. Change the line that reads "#netborder.net.primaryIPAddress=x.x.x.x" to "netborder.net.primaryIPAddress=IPADRESS" where IPADDRESS is the IP address of the Linux system. If you have two IP addresses change this to the one where sangoma will be accepting the connections from the Asterisk/Freeswitch system (usually the internal IP, default is 127.0.0.1).

  • Step 9. Go back to the config directory and edit call-analyzer-engine.properties file as following:

  • Step 10. Change the line that reads "#netborder.net.primaryIPAddress=x.x.x.x" to "netborder.net.primaryIPAddress=IPADRESS" where IPADDRESS is the IP address of the Linux system just like you did in the call-analyzer-service.properties file (default is 127.0.0.1).

  • Step 11. Restart the  Sangoma services as explained in step 4.

 

Asterisk Support

 

Asterisk SIP stack needs to be patched in order to work with Sangoma Lyra AMD.

Patch files are provided for each Asterisk Version.

  • Asterisk 11

  • Asterisk 10

  • Asterisk 1.8

  • Asterisk 1.6

  • Asterisk 1.4 

The Asterisk sip stack does not change very often, thus the above patch should work for all Asterisk subversions.

In case of patch failure please contact Sangoma Support

Visit: support.sangoma.com


Installation

 

  1. Download Asterisk from
    http://downloads.asterisk.org/pub/telephony/asterisk/releases
    Choose the latest Asterisk release.
     

  2. Untar Asterisk intallation
    tar xfz asterisk-<version>.tgz
    cd asterisk-<version>.tgz
     

  3. Download Sangoma Lyra AMD Asterisk Patch

    Please download appropriate patch based on Asterisk major version number.
    Download it into the asterisk source directory, created in section 2.

    Astersik 11 ->  lyra-amd-asterisk-11.1.2-v1.patch
    Asterisk 10 ->  lyra-amd-asterisk-10.8.0-v1.patch
    Asterisk 1.8 ->  lyra-amd-asterisk-1.8.16-v1.patch
    Asterisk 1.6 -> lyra-amd-asterisk-1.6.2.24-v1.patch
    Asterisk 1.4 ->  lyra-amd-asterisk-1.4.27-v1.patch
     

  4. Apply the patch
    From inside asterisk source directory.

    patch –p 1 <    lyra-amd-asterisk-*.patch

    Confirm that output of this command does not have any FAIL output.
     

  5. Build and Install Asterisk
    As this point standard Asterisk build and installation instructions apply.

    eg:
    ./configure
    make
    make install

Configuring your Asterisk Dialer to perform AMD.

Step 1. Open asterisk sip.conf file for editing.
Step 3. Set the following:

outboundproxy=NETBORDERIP

Where NETBORDERIP is the ip address of the system where you are running your Sangoma Lyra software (default is 127.0.0.1:5062). If "outboundproxy" is already set for your carrier it may not be possible to use Sangoma Lyra with them, Contact sangoma support for more details.

This parameter can also be configured on a per trunk/carrier basis allowing you to perform AMD only when calls are designated to certain carriers.

Operations

How to capture the CPD-Result Event

When Asterisk patch code is installed, all dialed calls from asterisk will containd cpd=on in the INVITE request sent by Asterisk. This parameter is used by Lyra AMD software to trigger Answering machine detection when it receives INVITE SIP requests from Asterisk. The Asterisk patch code generates also a manager event with CPD-Result.
The CPD-Result event is expected to be captured via AMI interface provided by Asterisk.

Example

Event: CPD-Result
Privilege: system,all
ChannelDriver: SIP
Channel: SIP/53589-00000003
CallerIDName: 53589
Uniqueid: 1354559057 .3
Result: Voice

 

In the following example, the AMI port is 5038 and the Asterisk box is located at  vm-1-lyra-amd.localdomain.

root@localhost ~]# telnet localhost 5038
Trying 127.0.0.1...
Connected to vm-1-vm-1-lyra-amd.localdomain (127.0.0.1).
Escape character is '^]'.

Asterisk Call Manager/1.2
Action: login
Username: mark
Secret: mysecret
Response: Success
Message: Authentication accepted

Event: FullyBooted
Privilege: system,all
Status: Fully Booted

Event: Newchannel
Privilege: call,all
Channel: SIP/931415926-00000002
ChannelState: 0
ChannelStateDesc: Down
CallerIDNum: 931415926
CallerIDName: 931415926
AccountCode:
Exten: 53589
Context: sip-phone
Uniqueid: 1354559057 .2

Event: Newstate
Privilege: call,all
Channel: SIP/931415926-00000002
ChannelState: 4
ChannelStateDesc: Ring
CallerIDNum: 931415926
CallerIDName: 931415926
ConnectedLineNum:
ConnectedLineName:
Uniqueid: 1354559057 .2

Event: Newchannel
Privilege: call,all
Channel: SIP/53589-00000003
ChannelState: 0
ChannelStateDesc: Down
CallerIDNum: 53589
CallerIDName: 53589
AccountCode:
Exten:
Context: sip-phone
Uniqueid: 1354559057 .3

Event: Dial
Privilege: call,all
SubEvent: Begin
Channel: SIP/931415926-00000002
Destination: SIP/53589-00000003
CallerIDNum: 931415926
CallerIDName: 931415926
ConnectedLineNum: <unknown>
ConnectedLineName: <unknown>
UniqueID: 1354559057 .2
DestUniqueID: 1354559057 .3
Dialstring: 53589

Event: CPD-Result
Privilege: system,all
ChannelDriver: SIP
Channel: SIP/53589-00000003
CallerIDName: 53589
Uniqueid: 1354559057 .3
Result: Voice

Event: Newstate
Privilege: call,all
Channel: SIP/53589-00000003
ChannelState: 6
ChannelStateDesc: Up
CallerIDNum: 53589
CallerIDName: 53589
ConnectedLineNum: 931415926
ConnectedLineName: 931415926
Uniqueid: 1354559057 .3

Event: Newstate
Privilege: call,all
Channel: SIP/931415926-00000002
ChannelState: 6
ChannelStateDesc: Up
CallerIDNum: 931415926
CallerIDName: 931415926
ConnectedLineNum: 53589
ConnectedLineName: 53589
Uniqueid: 1354559057 .2

Event: NewAccountCode
Privilege: call,all
Channel: SIP/53589-00000003
Uniqueid: 1354559057 .3
AccountCode:
OldAccountCode:

Event: Bridge
Privilege: call,all
Bridgestate: Link
Bridgetype: core
Channel1: SIP/931415926-00000002
Channel2: SIP/53589-00000003
Uniqueid1: 1354559057 .2
Uniqueid2: 1354559057 .3
CallerID1: 931415926
CallerID2: 53589
Event: HangupRequest
Privilege: call,all
Channel: SIP/53589-00000003
Uniqueid: 1354559057 .3

Event: Bridge
Privilege: call,all
Bridgestate: Unlink
Bridgetype: core
Channel1: SIP/931415926-00000002
Channel2: SIP/53589-00000003
Uniqueid1: 1354559057 .2
Uniqueid2: 1354559057 .3
CallerID1: 931415926
CallerID2: 53589

Event: Hangup
Privilege: call,all
Channel: SIP/53589-00000003
Uniqueid: 1354559057 .3
CallerIDNum: 53589
CallerIDName: 53589
ConnectedLineNum: 931415926
ConnectedLineName: 931415926
Cause: 16
Cause-txt: Normal Clearing

Event: Dial
Privilege: call,all
SubEvent: End
Channel: SIP/931415926-00000002
UniqueID: 1354559057 .2
DialStatus: ANSWER

Event: SoftHangupRequest
Privilege: call,all
Channel: SIP/931415926-00000002
Uniqueid: 1354559057 .2
Cause: 16

Event: Hangup
Privilege: call,all
Channel: SIP/931415926-00000002
Uniqueid: 1354559057 .2
CallerIDNum: 931415926
CallerIDName: 931415926
ConnectedLineNum: 53589
ConnectedLineName: 53589
Cause: 16
Cause-txt: Normal Clearing

If everything worked correctly, you should now be able to handle CPD-Result events in your campaigns. The CPD-Result event is expected to be captured via AMI interface provided by Asterisk, once captured, you'll just have to take the proper actions on your dialer side depending of the event value.

FreeSWITCH Support

FreeSWITCH SIP stack needs to be patched in order to work with Sangoma Lyra AMD.

The following repo is used for Sangoma Lyra with FreeSWITCH: 
-> https://github.com/sangoma/freeswitch.git

the branch you must use is lyra_amd

 

Installation

  1. Download FreeSWITCH with Lyra support  
    # git clone https://github.com/sangoma/freeswitch.git
    # cd freeswitch/
    # git checkout -b lyra_amd origin/lyra_amd

    * you must have git installed on your system for the above step

  2. Prepare the build system using "bootstrap.sh"
    # ./bootstrap.sh

  3. Configure the build system using "configure"

    # ./configure --prefix=<location to install FreeSWITCH to>NOTE: "--prefix" is an optional parameter, if a install location is not specified FreeSWITCH will install to /usr/local/freeswitch

  4. Compile all source code using "make"
    # make

  5. Install the compiled binaries using "make install"
    # make install

 

Operations

In your sofia profile (i.e. internal.xml), you set the variable "sip_watch_headers=CPD-Result", like this:

 <action application="bridge" data="{sip_watch_headers=CPD-Result,sip_invite_params=cpd=on}sofia/<profile>/..." />

  •  The sip_watch_headers variable takes care of notifying with an ESL event when a SIP message for the call contains the header CPD-Result

  • The sip_invite_params variable takes care of specifying the cpd=on parameter in the outgoing INVITE

Asterisk Integration Call Flow

 

Return to Documentation Home I Return to Sangoma Support