Soft key integration with phones

Overview - Soft keys on IP phones

MiaRec integrates with various phone models to provide the following features:

  • On-demand recording Users may use their phones to switch on/off recording during an active call.

  • Pause/resume recording Users may use their phones to pause recording for a short period of time. For example, when processing credit card transactions over the phone, a user may pause recording before a customer says the credit card information. Such feature allows to comply with PCI requirements.

The following images display example of integration with various phone models.

Cisco 7900 series softphone:

MiaRec phone services on Cisco phone

Polycom VVX400 phone:

MiaRec phone services on Polycom VVX phone

Cisco SPA504G phone:

MiaRec phone services on Cisco SPA504G phone

Yealink T46S phone:

Yealink pause/resume recording softkey

Mitel 6800i Series phone:

Mitel pause/resume recording softkey

Configure MiaRec phone services

This guide is for configuring phone services for Polycom VVX, Yealink, Mitel, Panasonic and Cisco/Linksys SPA phone models only. If you need to configure Cisco 7900 series phones, please, check the guide here.

MiaRec integrates with Polycom VVX, Yealink, Mitel, Panasonic and Cisco SPA series phones to provide the following features:

  • On-demand recording Users may use their phones to switch on/off recording for the current call.

  • Pause/resume recording Users may use their phones to pause recording for short period of time. For example, when processing credit card transactions over the phone, an agent may pause recording before a customer speaks the credit card information. Such features allows to comply with PCI requirements.

Configurations steps:

  1. Configure MiaRec phone services
  2. Configure "Login" and "PIN" attributes at the user profile
  3. Allow "Phone services" permissions at the role profile.
  4. Configure phone

Configure MiaRec phone services

Navigate in MiaRec web portal to Administration -> System -> Phone Services. Click Edit configuration button to open the settings page (see the following screenshot).

MiaRec Phone Services

Configure "Login" and "PIN" attributes at the user profile

Navigate in MiaRec web portal to Administration -> User Management -> Users and edit the corresponding user profiles. It is necessary to configure unique "Login" for each user. Users will need to provide their Login and PIN when they access the MiaRec services the first time from their phone.

MiaRec Phone Services

Allow "Phone services" permission at the role profile

Navigate in MiaRec web portal to Administration -> User Management -> Roles and edit the corresponding role profile.

MiaRec Phone Services

Configure phone

View active phone registration (sessions)

When user succesfully signs in to MiaRec phone services from his/her phone, the corresponding session is opened by MiaRec. An administrator may see all opened sessions using Web portal. Navigate to Administration -> System -> Phone services and click the link View active phone sessions:

MiaRec Phone Services

An administrator may terminate (delete) any active session from this screen. If the session is deleted, then the user will be required to signin again from his/her phone manually.

MiaRec Phone Services

Integration with Cisco SPA and 3PCC series phones

Cisco SPA series phones could be configured in a few ways:

  • Using phone's built-in web interface
  • Auto-provisioining of phone using HTTP, for example, in Broadworks or Metaswitch environment.

Supported models:

  • Cisco SPA 300, 500 Series
  • Cisco CP-8800 3PCC Series

Soft key MiaRec is displayed on Cisco SPA series phone when phone services are configured properly.

MiaRec Phone Service on Cisco SPA series phone

Click the MiaRec phone services button to see the Recording controls screen. The Record/No Record and Pause/Resume buttons are displayed on this screen:

MiaRec Phone Service on Cisco SPA series phone

Option 1. Configure phone using built-in web interface

Open phone's built-in web interface and navigate to Administration -> Advanced Settings -> Phone.

  1. Change "Programmable Softkey Enable" to yes

  2. Insert the following text into PSK 1 field (or any other field if PSK 1 is already used).

    fnc=xml;url=http://{MIAREC_WEB_SERVER}/api/phone_services/cisco_spa/calls/active_call?login=$UID1;nme=MiaRec
    

    Where {MIAREC_WEB_SERVER} is your MiaRec web server address and nme=MiaRec a soft key title. $UID1 will be substituted with the first line SIP Auth User ID. It should match to the correponding configuration of user profile in MiaRec web portal (menu Administration -> User Management -> Users, field Login).

  3. Add psk1|1 to Connected Key List field.

    Before:

    conf|3;xfer|4;toggle;bxfer;confLx;xferLx;park;phold;flash;
    

    After:

    psk1|1;conf|3;xfer|4;toggle;bxfer;confLx;xferLx;park;phold;flash;
    

    A number after | symbol specifies a position of button (1st in our example). psk1 corresponds to PSK 1 field configured above.

MiaRec Phone Service on Cisco SPA series phone

For more detail about Custom Phone Keys you can check the Cisco Small Business SPA300 Series, SPA500 Series, and WIP310 IP Phone Administration Guide

Option 2. Configure phone using Metaswitch SIP provisioining server

You need to create Endpoint Pack Extension for Metaswitch. You can find the detailed instructions in Metaswitch Community. See the document [Cisco] Creating a Cisco pack extension.

MiaRec Phone Services

File metadata.yaml (example):

ID: cisco_SPA5xx_accredited  
PackVersion: 17  
Version: 1  
Position: End  
TemplatePositions:  
- Template: config.ftl  
  Position: End  

File templates/schema.yaml (example):

group_names:
  CustomParameters:
    display_name:
      default: Custom Parameters

settings:
  - name: custom_MiaRecPhoneServices_Button
    group_name: CustomParameters
    display_name: 
      default: MiaRecPhoneServices_Button
    syntax:
      type: Boolean
    default_value: false

File templates/config.ftl (example):

<flat-profile>  
${logger.log("MiaRec Phone Services soft key")}  
  <Programmable_Softkey_Enable ua="na">Yes</Programmable_Softkey_Enable>  
  <Connected_Key_List ua="na">psk16|1;${profile.AdvConnKeyList}</Connected_Key_List>  
  <PSK_16 ua="na">fnc=xml;url=http://{MIAREC_WEB_SERVER}/api/phone_services/cisco_spa/calls/active_call?login=$UID1;nme=MiaRec</PSK_16>  
</flat-profile> 

Where {MIAREC_WEB_SERVER} is your MiaRec web server address and nme=MiaRec a soft key title. $UID1 will be substituted with the first line SIP Auth User ID. It should match to the correponding configuration of user profile in MiaRec web portal (menu Administration -> User Management -> Users, field Login).

Option 3. Configure phone using generic provisioining server (HTTP-based server)

If you are a service provider and provision phone using Broadworks, Metaswitch or home-grown HTTP based system, then you need to add the following customizations to your Cisco SPA phone configuration template. For more details check Cisco Small Business IP Telephony Devices Provisioning Guide

Example of Plain Text configuration:

Programmable_Softkey_Enable   "Yes" ;

Connected_Key_List                   "psk1|1;conf|3;xfer|4;toggle;bxfer;confLx;xferLx;park;phold;flash;" ;

PSK_1 "fnc=xml;url=http://{MIAREC_WEB_SERVER}/api/phone_services/cisco_spa/calls/active_call?login=$UID1;nme=MiaRec" ;

Where {MIAREC_WEB_SERVER} is your MiaRec web server address and nme=MiaRec a soft key title. $UID1 will be substituted with the first line SIP Auth User ID. It should match to the correponding configuration of user profile in MiaRec web portal (menu Administration -> User Management -> Users, field Login).

Troubleshooting

MiaRec System Log

Navigate in MiaRec web portal to Administration -> Maintenance -> System Log and check if there are any warnings/errors.

Use your web browser to simulate the hardware phone

Open in your web browser the same link as you configured in the Polycom configuration file, for example:

https://miarec.example.com/api/phone_services/cisco_spa/calls/active_call?login=123456

You should be able to see XML page like the following:

MiaRec Phone Services

Integration with Mitel/Aastra phones

MiaRec integrates with Mitel 6800 series phones (previously known as Aastra) to provide on-demand and pause/resume recording control using softkey.

The photos below show Mitel 6867i phone integrated with MiaRec XML application in action.

Mitel MiaRec softkey

Mitel 6871i / MiaRec softkey integration

Users can press Record / No Record softkey buttons during a call to selectively record some calls (on-demand recording).

The following photo demonstrates "Recording" state. User can press "No Record" to disable recording.

Mitel on-demand recording softkey

The following photo demonstrates "Not Recording" state. User can press "Record" to enable recording.

Mitel on-demand recording softkey

Additionally, MiaRec supports pause/resume recording for PCI Compliance. Users can press Pause and Resume softkey buttons to temporary mute recording, for example, when customer speaks credit card number.

Mitel pause/resume recording softkey

Configuration of Mitel phone

The MiaRec XML application can be configured in Mitel phone using:

  • Phone web interface
  • Generic provisioning server (recommended).
  • Metaswitch SIP Provisioning Server (recommended)

Option 1. Configuration of phone using web interface

Open web interface to Mitel phone and navigate to Softkeys and XML->Top Keys.

Choose one of available line keys and set:

  • Type to XML
  • Label to the preferred title, for example, MiaRec or Record
  • Value should point to MiaRec web server. Format is the following:

    https://miarec.example.com/api/aastra?login={LOGIN}&password={PASSWORD}
    

    Where:

    • {LOGIN} is a web access login configured on user's profile in MiaRec web portal
    • {PASSWORD} is either Phone Services PIN or web access password depending on phone services configuration in MiaRec.
    • miarec.example.com should replaced with your MiaRec server address

Mitel softkey configuration

HTTP vs HTTPS?

The URL for XML application supports both http:// and https://. For quick testing purposes you can use HTTP (non-encrypted) protocol for XML application, but for production, it is required to use HTTPS as it provides encryption. The user's login/password has to be sent to MiaRec server during authentication, so, encryption is required to protect this data from man-in-middle attacks.

Your MiaRec web server can be deployed with a self-signed certificate (not recommended for production) or with a SSL certificate signed by such providers like Verisign, DigiCert, GoDaddy, etc.

Mitel phone by default trusts only certificates that are signed by fullowing providers: Comodo (EssentialSSL and 4096-bit RSA), CyberTrust, DigiCert, Entrust, GoDaddy, GeoTrust, Mitel MBG, Symantec (Class 3 Secure Server CA - G4), Thawte, TrustZone and Verisign.

If your SSL certificate is signed by other provider, then it is necessary to download provider's CA certificate to the phone as a trusted SSL certificate. Check the Mitel SIP Phones Administration Guide for details (chapter HTTPS Client/Server Configuration).

Option 2. Configuration of phone using a generic provisioning server

Add the following lines to your phone's configuration file:

topsoftkeyX type: xml
topsoftkeyX label: MiaRec
topsoftkeyX value: https://miarec.example.com/api/aastra?login={LOGIN}&password={PASSWORD}

Where:

  • X is a number from 1 to 10 (depending on phone model).
  • {LOGIN} is a web access login configured on user's profile in MiaRec web portal
  • {PASSWORD} is either Phone Services PIN or web access password depending on phone services configuration in MiaRec.
  • miarec.example.com should replaced with your MiaRec server address

Option 3. Configuration of phone using Metaswitch SIP Provisioning Server

If you are a Metaswitch service provide using Metaswitch SIP Provisioning Server, then you can automate provisioning of MiaRec to all users using custom Endpoint Pack with the following settings:

topsoftkeyX type: xml
topsoftkeyX label: MiaRec
topsoftkeyX value: https://miarec.example.com/api/aastra?login=${userData.directoryNumber}&pat=${userData.commportalPAT}

Where:

  • X is a number from 1 to 10 (depending on phone model).
  • miarec.example.com should replaced with your MiaRec server address

The value ${userData.directoryNumber} will be replaced automatically with the extension of subscriber.

The value ${userData.commportalPAT} will be replaced with subscriber's Persistent Authentication Token (PAT).

Requirements for CommPortal-based authentication

  • CommPortal-based user authentication should be enabled in MiaRec (see menu Administration -> User Authentication -> Metaswitch CommPortal Authentication
  • Phone services authentication type on Tenant's profile should be set to Authenticate users using the web access password (see menu Administration -> User Management -> Tenants -> Tenant Profile -> Phone Services
  • Authentication type on User's profile should be set to CommPortal (see menu Administration -> User Management -> Users -> User Profile).

How MiaRec integrates with Metaswith CFS / CommPortal

Below diagram shows how MiaRec phone services are integrated with Metaswitch platform.

  1. The phone loads a custom made EndPoint Pack from Metaswitch SIP Provisioning server. This endpoint pack includes configuration of softkeys as well as HTTPS trust certificate (if necessary). The CommPortal Persistent Authentication Token (PAT) is generated for user and injected into the configuration file.

  2. User makes/receives call from Metaswitch CFS

  3. Upon pressing the pre-configured softkey, the phone loads XML application from MiaRec web server. The MiaRec server receives user's login and CommPortal Persistent Authentication Token (PAT) in the request, and passes those values to Metaswitch CommPortal for validation. After user credentials verification, the recording control buttons are displayed on phone's screen.

MiaRec Phone Services

Troubleshooting

MiaRec System Log

Navigate in MiaRec web portal to Administration -> Maintenance -> System Log and check if there are any warnings/errors.

Use your web browser to simulate a hardware phone

Open in your web browser the same link as you configured in the Mitel configuration file, for example:

https://miarec.example.com/api/aastra?login=123456&password=secret

You should be able to see XML formatted page like:

<?xml version="1.0" encoding="utf-8"?>
  <AastraIPPhoneFormattedTextScreen
    destroyOnExit="yes"
    LockIn="no"
    Beep="no"
  >

  <TopTitle>Recording controls</TopTitle>
  <Line>
     From: 551200159 
  </Line>
  <Line>
     To: 300 
  </Line>
  <Line>
     NOT RECORDING
  </Line>

  <SoftKey index="1">
      <Label>Record</Label>
      <URI>https://miarec.example/api/aastra/calls/...</URI>
  </SoftKey>

  <SoftKey index="2">
        <Label>Pause</Label>
        <URI>https://miarec.example/api/aastra/calls/...</URI>
  </SoftKey>

Integration with Polycom VVX series phones

Supported models:

  • Polycom VVX 300, 400, 500, 600, 1500

Edit Polycom XML configuration files on your provisioning server

You need to add the following settings to the XML configuration file:

<feature>
    <feature.enhancedFeatureKeys feature.enhancedFeatureKeys.enabled="1">
    </feature.enhancedFeatureKeys>
</feature>

<softkey
  softkey.1.label="MiaRec"
  softkey.1.action="https://{MIAREC_WEB_SERVER}/api/phone_services/polycom/calls/active_call?login={LOGIN}"
  softkey.1.enable="1"
  softkey.1.insert="0"
  softkey.1.precede="1"
  softkey.1.use.active="1"
  softkey.1.use.alerting="0"
  softkey.1.use.dialtone="0"
  softkey.1.use.hold="0"
  softkey.1.use.idle="0"
  softkey.1.use.proceeding="0"
  softkey.1.use.setup="0"
>
</softkey>

Where {MIAREC_WEB_SERVER} is your MiaRec web server address and {LOGIN} is an login of the particular user. Each user should have unique login. The login should match to the correponding configuration of user profile in MiaRec web portal (menu Administration -> User Management -> Users).

Below diagram shows how MiaRec phone services are integrated with Metaswitch platform:

MiaRec Phone Services

Troubleshooting

MiaRec System Log

Navigate in MiaRec web portal to Administration -> Maintenance -> System Log and check if there are any warnings/errors.

Use your web browser to simulate the hardware phone

Open in your web browser the same link as you configured in the Polycom configuration file, for example:

https://miarec.example.com/api/phone_services/polycom/calls/active_call?login=123456

You should be able to login to phone services and see the recording controls.

MiaRec Phone Services

Check Polycom phone logs

By default Polycom phone automatically uploads own log file to the provisioning system using FTP. Check that log file for any errors.

Known limitations

Polycom phones do not support wildcard SSL certificates, i.e. if your MiaRec web server uses SSL certificate for domain *.example.com, then XML application will fail to load to Polycom phone with error "SSL/TLS handshake failed".

Solution: use a single-domain SSL certificate for MiaRec web portal, for example, you can use free SSL certificate from Let's Encrypt.

Integration with Yealink phones

MiaRec integrates with Yealink phones to provide on-demand and pause/resume recording control using softkey.

The photos below show example of Yealink T46S and T48S with MiaRec XML application in action

Yealink T46S / MiaRec softkey integration

Users can press Record / No Record softkey buttons during a call to selectively record some calls (on-demand recording).

The following photo demonstrates "Recording" state. User can press "No Record" to disable recording.

Yealink on-demand recording softkey

The following photo demonstrates "Not Recording" state. User can press "Record" to enable recording.

Yealink on-demand recording softkey

Additionally, MiaRec supports pause/resume recording for PCI Compliance. Users can press Pause and Resume softkey buttons to temporary mute recording, for example, when customer speaks credit card number.

Yealink pause/resume recording softkey

Yealink T48S / MiaRec softkey integration

Yealink on-demand recording softkey

Yealink on-demand recording softkey

Yealink pause/resume recording softkey

Configuration of Yealink phone

The MiaRec XML application can be configured in Yealink phone using:

  • Phone web interface
  • Provisioning server (recommended)

Option 1. Configuration of phone using web interface

Open web interface to Yealink phone and navigate to DssKey -> Line Key1-9.

Choose one of available line keys and set:

  • Type to XML Browser
  • Label to preferred title, for example, MiaRec or Record
  • Value should point to MiaRec web server. Format is the following:

    https://server.example.com/api/yealink?login={LOGIN}&password={PASSWORD}
    

    Where:

    • {LOGIN} is a web access login configured on user's profile in MiaRec web portal
    • {PASSWORD} is either Phone Services PIN or web access password depending on phone services configuration in MiaRec.
    • miarec.example.com should replaced with your MiaRec server address

Yealink softkey configuration

Option 2. Configuration of phone using provisioning server

Add the following lines to your phone's configuration file:

linekey.X.type = 27
linekey.X.label = "MiaRec"
linekey.X.value = https://miarec.example.com/api/yealink?login={LOGIN}&password={PASSWORD}

Where:

  • X is a number from 1 to 10 (depending on phone model).
  • {LOGIN} is a web access login configured on user's profile in MiaRec web portal
  • {PASSWORD} is either Phone Services PIN or web access password depending on phone services configuration in MiaRec.
  • miarec.example.com should replaced with your MiaRec server address

Option 3. Configuration of phone using Metaswitch SIP Provisioning Server

If you are a Metaswitch service provide using Metaswitch SIP Provisioning Server, then you can automate provisioning of MiaRec to all users using custom Endpoint Pack with the following settings:

linekey.X.type = 27
linekey.X.label = "MiaRec"
linekey.X.value = https://miarec.example.com/api/yealink?login=${userData.directoryNumber}&pat=${userData.commportalPAT}

Where:

  • X is a number from 1 to 10 (depending on phone model).
  • miarec.example.com should replaced with your MiaRec server address

The value ${userData.directoryNumber} will be replaced automatically with the extension of subscriber. The value ${userData.commportalPAT} will be replaced with subscriber's Persistent Authentication Token (PAT).

Below diagram shows how MiaRec phone services are integrated with Metaswitch platform:

MiaRec Phone Services

Troubleshooting

MiaRec System Log

Navigate in MiaRec web portal to Administration -> Maintenance -> System Log and check if there are any warnings/errors.

Use your web browser to simulate a hardware phone

Open in your web browser the same link as you configured in the Yealink configuration file, for example:

https://miarec.example.com/api/yealink?login=123456&password=secret

You should be able to login to see XML formatted page for Yealink phone like.

<?xml version="1.0" encoding="utf-8"?>
  <YealinkIPPhoneTextScreen
    destroyOnExit="yes"
    LockIn="no"
    Beep="no"
  >

  <Title>Recording controls</Title>
  <Text>
     From: 551200159 
     To: 300 

     NOT RECORDING
  </Text>

  <SoftKey index="1">
      <Label>Record</Label>
      <URI>https://miarec.example/api/yealink/calls/...</URI>
  </SoftKey>

  <SoftKey index="2">
        <Label>Pause</Label>
        <URI>https://miarec.example/api/yealink/calls/...</URI>
  </SoftKey>

Softkey integration with Cisco 7900, 7800 and 8800 series phones

Overview

MiaRec integrates with Cisco phone services to provide the following features:

  • On-demand recording Agents may use their Cisco phones to switch on/off recording for the current call.

  • Pause/resume recording Agents may use their Cisco phones to pause recording for short period of time. For example, when processing credit card transactions over the phone, an agent may pause recording before a customer says critical credit card information. Such features allows to comply with PCI requirements.

Control MiaRec recording from Cisco softphone

MiaRec phone services on Cisco phone

Control MiaRec recording from Cisco hardware phone

Requirements:

  • Cisco phone with XML phone services support

Create MiaRec IP Phone Service

Open Cisco Unified Communications Manager administration web portal.

  1. Select the Device - Device Settings - Phone Services menu item.

  2. Click on Add New

  3. Type in the Service Name: MiaRec (you may use different name here)

  4. Type in the Service Description: MiaRec Phone Service

  5. Type in the Service URL:

    http://0.0.0.0/cisco_phone_service/active_call?name=#DEVICENAME#
    

    Replace 0.0.0.0 with your MiaRec server ip-address. This URL should point to MiaRec web portal. If the web portal is running on port different from the default 80, then include port into URL, like http://1.2.3.4:8080/cisco_phone_service.... It is recommended to use direct ip-address instead of domain name because name resolution may not work from within Cisco IP phone.

    Alternatively, you can use the following URLs, which allow to control recording in one-click:

    URL Description
    http://0.0.0.0/cisco_phone_service/call/active_call/ondemand/keep?name=#DEVICENAME# Enable recording in one-click
    http://0.0.0.0/cisco_phone_service/call/active_call/ondemand/discard?name=#DEVICENAME# Disable recording in one-click
    http://0.0.0.0/cisco_phone_service/call/active_call/muting/mute?name=#DEVICENAME# Pause recording in one-click
    http://0.0.0.0/cisco_phone_service/call/active_call/muting/unmute?name=#DEVICENAME# Resume recording in one-click
  6. Check Enable option.

  7. Save it.

See below screenshot for details.

Create MiaRec IP Phone Service

Subscribe each phone to MiaRec phone service

Open Cisco Unified Communications Manager administration web portal.

  1. Select the Device - Phone menu item.

  2. Select the desired phone/device.

  3. Select Subscribe/Unsubscribe Services from the "Related links" dropdown list.

    Subscribe Cisco IP phone to MiaRec phone service

  4. In the new pop up window select MiaRec from the list box.

  5. Click the Next button.

    Subscribe Cisco IP phone to MiaRec phone service

  6. Click the Subscribe button.

    Subscribe Cisco IP phone to MiaRec phone service

  7. Verify that the phone subscribed to MiaRec phone service successfully and click the Save button. Then close this pop up window.

    Subscribe Cisco IP phone to MiaRec phone service

Now, after you save phone configuration and restart the phone, the MiaRec phone services should be available upon clicking the Services button on the phone.

[Optional] Use phone's line button for quick access to MiaRec phone services.

  1. Click the Modify Button Items in the Phone Configuration window

    Subscribe Cisco IP phone to MiaRec phone service

  2. Select the Add a new SURL from the list Unassigned Associated Items and click < button.

    Subscribe Cisco IP phone to MiaRec phone service

  3. If you receive the error Must Remove An Item From Associated List Before This Operation is Allowed., then select one of unnecessary items in the list Associated Items and click V button.

    Subscribe Cisco IP phone to MiaRec phone service

    Subscribe Cisco IP phone to MiaRec phone service

  4. Select the Add a new SURL in the list Associated Items and click button ^ as many times as necessary to move it to the correct position. For example, if the phone has only 4 line buttons, then position should be from 1 to 4, otherwise the button will not be visible.

    Subscribe Cisco IP phone to MiaRec phone service

  5. Click the Save button and close this pop up window.

  6. Click the newly created Add a new SURL link.

    Subscribe Cisco IP phone to MiaRec phone service

  7. Select MiaRec from the list box and click Save button two times.

    Subscribe Cisco IP phone to MiaRec phone service

  8. Verify that MiaRec is shown on the line button. Save the phone configuration and click Apply Config (depending on phone firmware it may be necessary to restart the phone to apply changes).

    Subscribe Cisco IP phone to MiaRec phone service