52.4. CTIVR - Voice Recorder

52.4. CTIVR - Voice Recorder
	Chapter 52. CTIAS - CTI Advanced Services

Voice Recorder registers the call and sends the audio messages via email.

	Important
	Voice Recorder requires a separate licence in CPX and needs also SoftPBX licence to activate OPC (for enabling Voice Recording via OPC Panel) and SMTP licence to activate SMTP (for sending emails).

The Abilis supports two ways of voice recording:

Programmed recording: based on CTIVR rules;
On-demand recording: activated via WEB interface via OPC Panel or activated via DTMF code from the telephone keypad. PCphone and Abilisphone have the record button in the own interfaces.
Note
On-demand recording is possible to start only when a call is currently active.
Tip
Interesting chapters:
Section 60.7, “Recording”;
Section 73.23, “How to activate On-Demand recording”.

52.4.1. Activating the CTIVR resource

Add the resource to the Abilis system with the following command.

[09:08:14] ABILIS_CPX:a res:ctivr

COMMAND EXECUTED

The CTIVR resource may already exist in the system, but may not yet be active. Set it active with the command:

[09:10:00] ABILIS_CPX:s act res:ctivr

COMMAND EXECUTED

	Caution
	You must restart the Abilis to make the resource running (use the command warm start to reboot the Abilis) after adding or setting the CTIVR active.

Tip

If the CTIVR resource is activated and the CTIAS resource isn't, Abilis automatically adds the CTIAS resource:

[12:11:11] ABILIS_CPX:a res:ctivr

COMMAND EXECUTED (ADDED ALSO RES:CtiAs)

[12:15:48] ABILIS_CPX:s p ctivr act:yes

COMMAND EXECUTED

[12:15:56] ABILIS_CPX:d p ctivr

RES:CtiVr ---------------------------------------------------------------------
Run    DESCR:CTI_VR_service
       LOG:NO        ACT:YES    sesnum:5    TC-SESNUM:0        PREFER-TDM:NO
       wdir:C:\APP\VR\
       - Programmed recording -------------------------------------------------
       MODE:MONO                MAX-RECORDING-SIZE:15000
       DROP-ON:NOCHAN                                          BUSY-NOCHAN:YES
       RCPT:
       RCPT-LIST-CDI:#                      RCPT-LIST-CDO:#
       RCPT-LIST-CGI:#                      RCPT-LIST-CGO:#
       - On-demand recording --------------------------------------------------
       OD-MODE:MONO             OD-MAX-RECORDING-SIZE:15000    
       OD-CODE:*#               OD-CONF-TONE:YES

	Caution
	Execute the initialization command init res:ctivr to activate the changes made on the upper case parameters; use save conf and warm start commands to set active the changes made on the lowercase parameters.

52.4.2. CTIVR resource parameters

Use the command below to display the parameters of the resource; the d p ctivr ? command shows the meaning of parameters.

[14:08:12] ABILIS_CPX:d p ctivr

RES:CtiVr ---------------------------------------------------------------------
Run    DESCR:CTI_VR_service
       LOG:NO        ACT:YES    sesnum:5    TC-SESNUM:0        PREFER-TDM:NO
       wdir:C:\APP\VR\
       - Programmed recording -------------------------------------------------
       MODE:MONO                MAX-RECORDING-SIZE:15000
       DROP-ON:ERRORS           DROP-IN-ACTIVE:YES     BUSY-NOCHAN:YES
       RCPT:
       RCPT-LIST-CDI:#                      RCPT-LIST-CDO:#
       RCPT-LIST-CGI:#                      RCPT-LIST-CGO:#
       - On-demand recording --------------------------------------------------
       OD-MODE:MONO             OD-MAX-RECORDING-SIZE:15000    
       OD-CODE:*#               OD-CONF-TONE:YES

Meaning of the most important parameters:

LOG

State changes log and alarm generation [NO, D, S, A, L, T, ALL] [+E] (D: Debug Log; S: System Log; A: Alarm view; L: Local audible alarm; T: SNMP traps; +E: Extended Log of state changes, see ref. manual).

ACT

Runtime CTIVR activation/deactivation. [NO, YES].

sesnum

Number of sessions that the VR plugin can support at once [1..255].

TC-SESNUM

Number of on-the-fly simultaneous transcoding sessions allowed for VR plugin [0..255].

PREFER-TDM

Prefer TDM side recording over PACKET side recording in CSIDtoV and VtoCSID calls [NO, YES]:

YES: recording is performed on TDM side. This uses TWO HDLC or AC resources for each call. The recorded file is immediately ready for sending.

NO: recording is performed on packet side. If codec is not G.711 the recording will be later transcoded to G.711 using SW transcoding for G.729A and Spirit, and using HW transcoding for G.723.1.

wdir

Directory where message files are located. It cannot be empty. Physical full path in DOS notation, i.e. starting with a drive letter in the range ['A'..'Z'] and ending with the '\' character. Max. 128 characters. Case is preserved. Spaces are allowed. Strings holding spaces must be written between quotation marks (E.g.: "C:\My dir\").

Meaning of the parameters for Programmed recording:

MODE: Use stereo or mono recording [STEREO, MONO].Use mono recording for both directions (mix) or stereo recording (one channel for each direction).
MAX-RECORDING-SIZE: Maximum size of a single message [100..65535 Kibyte]. When the size is reached the registration is stopped and call closed. By default, the max recording file size is 15 MB. This is the equivalent of a 32 minutes call. When the 31st minute ends, the recording is stopped. To bypass this limitation, you can stop the recording and immediately restart it. You'll receive a mail for each recording.
DROP-ON: Drops the call if it can't be recordered [NONE: For no reasons the call is dropped; NOCHAN: Call is dropped if there are not sessions available for recording. Disconneciton cause to be defined; ERRORS:Drops the call if it can't be recordered, e.g. because of disk error]. Values can be joined using "," operator.
DROP-IN-ACTIVE: Controls the call drop while already in ACTIVE state in case of ERRORS [NO, YES]. If error preventing the recording occurs while already in ACTIVE state, and DROP-ON permits the drop on those errors, this parameters controls if the drop can take place or not in ACTIVE state.
BUSY-NOCHAN: Return BUSY cause instead of NOCHAN [NO, YES].
RCPT: Default Voice Mail recipient(s). From 0 up to 128 ASCII printable characters. Spaces are not allowed. Case is preserved.
RCPT-LIST-CDI: IN2T list used to select Voice Mail recipient(s) on the base of input called numbers [#, ListName].
RCPT-LIST-CDO: IN2T list used to select Voice Mail recipient(s) on the base of output called numbers [#, ListName].
RCPT-LIST-CGI: IN2T list used to select Voice Mail recipient(s) on the base of input calling numbers [#, ListName].
RCPT-LIST-CGO: IN2T list used to select Voice Mail recipient(s) on the base of output calling numbers [#, ListName].

Meaning of the parameters for On-demand recording:

OD-MODE: Use stereo or mono recording [STEREO, MONO].
OD-MAX-RECORDING-SIZE: Maximum size of a single message [100..65535 Kibyte]. When the size is reached the registration is stopped and call closed. By default, the max recording file size is 15 MB. This is the equivalent of a 32 minutes call. When the 31st minute ends, the recording is stopped. To bypass this limitation, you can stop the recording and immediately restart it. You'll receive a mail for each recording.
OD-CODE: Dialed DTMF code activating on-demand recording. From 1 up to 2 characters in the range [DISABLED, '0'..'9', 'A'..'D', '*', '#'].
OD-CONF-TONE: Enable/disable the generation of a confirmation tone [NO, YES]. If it is set to "YES", the missing tone means activation failure.

The following command allows the administrator to change the configuration of the resource:

s p ctivr parameter:value...

	Caution
	Execute the initialization command init res:ctivr to activate the changes made on the upper case parameters; use save conf and warm start commands to set active the changes made on the lowercase parameters.

52.4.3. CTIVR rules

The CTIVR rules allow to record a call automatically based on various filters and send the audio messages via email.

The CTIVR rules are written in the "CTIVR table". In the rules are written the conditions which must be verified in the call before that the Voice recorder begin the recording. The priorities in the CTIVR table are numbered (PR: 0, PR: 1, ...). The route with PR:0 is the first checked by CTIVR, the PR:1 is the second, the last PR on the table is last verified CTIVR priority. If the call matches the condition of a CTIVR rule, then the call is registered, else will not be recorded.

The variables of the call that are evaluated for the selection of the CTIVR priority are:

Source:
- POI: input CTI port/group;
- SR: input cluster/group.
Destination:
- POO: output CTI port/group;
- DS: output cluster/group.
Addressing:
- CDI: input called address;
- CGI: input calling address;
- CDO: output called address;
- CGO: output calling address.
Users:
- USERI: calling user;
- USERO: called user.

	Important
	Particular attention is needed for the evaluation of the POI and POO parameters.

	Note
	Some parameters have the value `*`, which means that any are allowed.

The CTIVR rules can be managed with the following commands:

d ctivr: displays the CTIVR rules;
a ctivr pr:xx [par:value]; adds a new CTIVR rule;
c ctivr pr:xx: clears an existing CTIVR rule;
s ctivr pr:xx [par:value]: modifies the parameter of an existing CTIVR rule.

To activate Voice recording via CTIVR rules is required that the CTIVR and SMTP resources to be active. Refer to: Section 52.4.1, “Activating the CTIVR resource” and Section 31.1.1, “Activating the SMTP resource”.

Here is an example: Record the call incoming from the CTIP:149 to SIP:

[15:04:38] ABILIS_CPX:a ctivr pr:0 poi:149 poo:sip rcpt:test@antek.it

COMMAND EXECUTED 

[15:05:08] ABILIS_CPX:d ctivr

- Not Saved (SAVE CONF), Not Refreshed (INIT) ---------------------------------
---+-------+--------+------------------------+--------+------------------------
PR |[DESCR]
ACT|REC    |POI     |CDI                     |POO     |CDO
   |MODE   |SR      |CGI                     |DS      |CGO
   |USERI                                    |USERO
   |RCPT
   |RCPT-LIST-CDI                            |RCPT-LIST-CDO
   |RCPT-LIST-CGI                            |RCPT-LIST-CGO
---+-------+--------+------------------------+--------+------------------------
0   YES     149      *                        Sip      *
YES SYS     #        *                        #        *
    *                                         *
    test@antek.it
    SYS                                       SYS
    SYS                                       SYS
---+-------+--------+------------------------+--------+------------------------

	Caution
	Changes made on the CTIVR table aren't immediately active. To activate them, execute the initialization command init ctivr.

Meaning of the most important parameters:

ACT

Active/usable record flag [NO, YES].

REC

Specifies whether to record or not [NO, YES].

MODE

Use stereo or mono recording [SYS, STEREO, MONO].

POI

Input CTI port/group [#, *, **, 1..600, G0..G32, G*, PBX, Iax, Sip, Disa, Vo, Vm], where:

* = Any CTI port ISDN/POTS/VPOTS/CELL;

** = Any CTI port, including Iax, Sip, Disa, Vo.

SR

Input cluster/group [#, *, G*, G0..G32, cluster name or EC/RU/MR list name between single quote]. The cluster name must correspond to an existing CTI cluster. The list name must correspond to an existing EC/RU/MR list.

POO

Output CTI port/group [#, *, **, 1..600, G0..G32, G*, PBX, Iax, Sip, Disa, Vo, Vm, Mix], where:

* = Any CTI port ISDN/POTS/VPOTS/CELL;

** = Any CTI port, including Iax, Sip, Disa, Vo.

DS

Output cluster/group [#, *, G*, G1..G32, cluster name or EC/RU/MR list name between single quote]. The cluster name must correspond to an existing CTI cluster. The list name must correspond to an existing EC/RU/MR list.

CDI

Input called address [0..9, *, #, ?, 'list'], optionally preceded by TON [u, i, n, o, s, h, c] and/or NP [x, e, d, t, l, p] attributes, or [##, $]. (E.g.: 123, 123*, 12?, 12?*, *, #, ##, $, 'listname', 123'listname') See HELP ISDN ATTRIBUTES for details on attributes. See HELP ISDN VALUES for details on meaning of special values.

CDO

Output called address [0..9, *, #, ?, 'list'], optionally preceded by TON [u, i, n, o, s, h, c] and/or NP [x, e, d, t, l, p] attributes, or [##, $]. (E.g.: 123, 123*, 12?, 12?*, *, #, ##, $, 'listname', 123'listname') See HELP ISDN ATTRIBUTES for details on attributes. See HELP ISDN VALUES for details on meaning of special values.

CGI

Input calling address [0..9, *, #, ?, 'list'], optionally preceded by TON [u, i, n, o, s, h, c] and/or NP [x, e, d, t, l, p] and/or PI [a, r, m, q] and/or SI [y, v, w, z, j] attributes, or [##, $]. (E.g.: 123, 123*, 12?, 12?*, *, #, ##, $, 'listname', 123'listname') See HELP ISDN ATTRIBUTES for details on attributes. See HELP ISDN VALUES for details on meaning of special values.

CGO

USERI

CPX user from which incoming call arrives. "*" or "#" or from 1 up to 32 Alphanumeric extended characters. Spaces are not allowed. Case is preserved.

USERO

CPX user to which the call is sent. "*" or "#" or from 1 up to 32 Alphanumeric extended characters. Spaces are not allowed. Case is preserved.

RCPT

Default Voice Mail recipient(s). "SYS" or from 0 up to 128 ASCII printable characters. Spaces are not allowed. Case is preserved.

RCPT-LIST-CDI

IN2T list used to select Voice Mail recipient(s) on the base of input called numbers [#, SYS, 'ListName'].

RCPT-LIST-CDO

IN2T list used to select Voice Mail recipient(s) on the base of output called numbers [#, SYS, 'ListName'].

RCPT-LIST-CGI

IN2T list used to select Voice Mail recipient(s) on the base of input calling numbers [#, SYS, 'ListName'].

RCPT-LIST-CGO

IN2T list used to select Voice Mail recipient(s) on the base of output calling numbers [#, SYS, 'ListName'].

The following command allows the administrator to change the configuration of CTIVR rules:

s ctivr pr:xx parameter:value...

Here is an example: Change to record the call incoming from the CTIP:149 to SIP only for SIP user "test":

[15:56:26] ABILIS_CPX:s ctivr pr:0 usero:test

COMMAND EXECUTED 

[15:56:47] ABILIS_CPX:d ctivr

- Not Saved (SAVE CONF), Not Refreshed (INIT) ---------------------------------
---+-------+--------+------------------------+--------+------------------------
PR |[DESCR]
ACT|REC    |POI     |CDI                     |POO     |CDO
   |MODE   |SR      |CGI                     |DS      |CGO
   |USERI                                    |USERO
   |RCPT
   |RCPT-LIST-CDI                            |RCPT-LIST-CDO
   |RCPT-LIST-CGI                            |RCPT-LIST-CGO
---+-------+--------+------------------------+--------+------------------------
0   YES     149      *                        Sip      *
YES SYS     #        *                        #        *
    *                                         test
    test@antek.it
    SYS                                       SYS
    SYS                                       SYS
---+-------+--------+------------------------+--------+------------------------

	Caution
	Changes made on the CTIVR table aren't immediately active. To activate them, execute the initialization command init ctivr.

52.4.4. On-Demand recording

The On-Demand Call Recording feature lets employees decide when to record important calls. It’s particularly useful when you need to verify the details of a conversation – such as pricing and delivery dates – or when it’s essential that you capture accurate notes. Users with this feature can quickly start and stop a recording by clicking the record button in the OPC panel or by inserting a DTMF code from the telephone keypad. This code is possible to change with OD-CODE parameter of CTIVR resource. Once the recording is captured, the voice mail is sent via email. For PCphone and Abilisphone the record button will be enabled if you have an active call.

	Important
	Voice Recorder requires a separate licence in CPX and needs also SoftPBX licence to activate OPC (for enabling Voice Recording via OPC Panel) and SMTP licence to activate SMTP (for sending emails).

Tip

Interesting chapters:

Section 73.23, “How to activate On-Demand recording”;

Section 60.7, “Recording”.

To activate On-Demand recording for the user is required that the CTIVR, SMTP, OPC and HTTP resources to be active. Refer to: Section 52.4.1, “Activating the CTIVR resource”, Section 31.1.1, “Activating the SMTP resource”, Section 48.1.1, “Activating the OPC resource” and Section 37.1.1, “Activating the HTTP resource”.

The appropriate http-rights must be assigned for the user to allow the access the OPC paths: /sys/opc/.

Tip

Interesting chapters:

Section 56.2, “Add http rights”;

Section 61.1.6, “Example - How to give the http rights to a user through web interface”.

To activate On-Demand recording for user "test" enter the following command:

[14:33:18] ABILIS_CPX:s pref user:test on-demand-vr:yes on-demand-vr-rcpt:test@antek.it

COMMAND EXECUTED 

[14:34:00] ABILIS_CPX:d pref user:test

- Not Saved (SAVE CONF) -------------------------------------------------------
Parameter:          | Value:
--------------------+----------------------------------------------------------
USER:                 test
ID:                   8                                             <Read Only>
LAST-CHANGE:          12/01/2016 14:34:00 CET                       <Read Only>
PWD:                  ***
- CTIP not active --
- CLUS not active --
- IAX not active ---
--------------------
SIP-CLIP:             TRANSP
SIP-ACTION:           ADVANCED (No rules)
SIP-CF-RULE:          ALWAYS
SIP-CF-TOUT:          15
SIP-CF-DLY:           10
SIP-CF-FORK-TYPE:     STD
SIP-CF-CDO:           12
SIP-CF-CGO:           *
SIP-VM:               NO
SIP-VM-RULE:          ALWAYS
SIP-VM-TOUT:          15
SIP-PC-OFFER:         4
SIP-MAIL-FAIL:        NO
SIP-MAIL-FWD:         NO
SIP-MAIL-SEIZED:      NO
- VO not active ----
--------------------
VM-RCPT-LIST:         #
VM-RCPT:              
VM-OGM-MSG:           SYS
VM-END-MSG:           SYS
--------------------
MAIL-BODY:            SYS
MAIL-RCPT-LIST:       #
MAIL-DFT-RCPT:        
--------------------
CTI-CALLS-LOG:        YES
CTI-CALLS-LOG-IN:     200
CTI-CALLS-LOG-OUT:    200
--------------------
CTI-TRFA:             NO
--------------------
CALLTRY-TOUT:         SYS
CALLTRY-NRTY:         SYS
--------------------
TON-TO-PREFIX:        SYS
--------------------
ON-DEMAND-VR:         YES
ON-DEMAND-VR-RCPT:    test@antek.it
--------------------
OPC-MAIN-INTERFACE:   SIP
-------------------------------------------------------------------------------

	Tip
	Remember to save the configuration with the save conf command.

52.4.5. CTIVR diagnostic and statistics

52.4.5.1. CTIVR diagnostic

The following command is used to display the diagnostics of the CTIVR resource:

d d ctivr/d de ctivr: It shows the state of the resource sorted by session (sesnum parameter).

[15:15:48] ABILIS_CPX:d d ctivr

RES:CtiVr ---------------------------------------------------------------------
       CTI_VR_service                                                          
       STATE:ACTIVE    MAILER-STATE:WAITING     TC-STATE:WAITING
       ------------------------------------------------------------------------
       SES: State        CDI                        CDO
            PR           CGI                        CGO
            UserI                              UserO
       ------------------------------------------------------------------------
       0    RECORDING    49                         49
            ODR          111                        111
            test2                              21
       ------------------------------------------------------------------------
       1    READY        
       ------------------------------------------------------------------------
       2    READY        
       ------------------------------------------------------------------------
       3    READY        
       ------------------------------------------------------------------------
       4    READY        
       ------------------------------------------------------------------------

52.4.5.2. CTIVR statistics

The following command is used to display the statistics of the CTIVR resource:

d s ctivm: It shows the statistics of the CTIVR resource such as the total number of successfully sent mails (SENT), the total number of successfully transcoded CPM files (TRANSCODED).
d se ctivm: It shows the statistics in extended format of the CTIVR resource such as the total number of successfully sent mails (SENT), the total number of successfully transcoded CPM files (TRANSCODED) and the total number of successfully recorded calls (RECORDED).

[15:18:09] ABILIS_CPX:d s ctivr 

RES:CtiVr ---------------------------------------------------------------------
       CTI_VR_service                                                          
       --- Cleared 0 days 15:01:44 ago, on 12/01/2016 at 00:16:29 -------------
       -----------|---INPUT---|--OUTPUT---|-----------|---INPUT---|--OUTPUT---|
       SENT       |           |          1|TRANSCODED |           |          1|
       ------------------------------------------------------------------------

[15:18:13] ABILIS_CPX:d se ctivr

RES:CtiVr ---------------------------------------------------------------------
       CTI_VR_service                                                          
       --- Cleared 0 days 15:01:53 ago, on 12/01/2016 at 00:16:30 -------------
       -----------|---INPUT---|--OUTPUT---|-----------|---INPUT---|--OUTPUT---|
       SENT       |           |          1|TRANSCODED |           |          1|
       ------------------------------------------------------------------------
       SES:0    
       -----------|---INPUT---|--OUTPUT---|-----------|---INPUT---|--OUTPUT---|
       RECORDED   |          1|           |
       ------------------------------------------------------------------------
       SES:1    
       -----------|---INPUT---|--OUTPUT---|-----------|---INPUT---|--OUTPUT---|
       RECORDED   |          0|           |
       ------------------------------------------------------------------------
       SES:2    
       -----------|---INPUT---|--OUTPUT---|-----------|---INPUT---|--OUTPUT---|
       RECORDED   |          0|           |
       ------------------------------------------------------------------------
       SES:3    
       -----------|---INPUT---|--OUTPUT---|-----------|---INPUT---|--OUTPUT---|
       RECORDED   |          0|           |
       ------------------------------------------------------------------------
       SES:4    
       -----------|---INPUT---|--OUTPUT---|-----------|---INPUT---|--OUTPUT---|
       RECORDED   |          0|           |

	Note
	On-demand recording is possible to start only when a call is currently active.


52.3. CTIMIX - Conference		Chapter 53. CTISMS - CTI SMS resource