On-Demand SIPREC using REST

The device supports on-demand SIPREC sessions that are triggered through the device's REST API (in HTTP POST requests) at the REST URL <device's IP address>/api/v1/sip/sipRecording. This method can trigger the device to start or stop recording a call (beginning of the call or during the call).

The incoming REST message for triggering SIPREC includes the following fields:

■

command: (Mandatory) This field tells the device to start ("start") or stop ("stop") recording.

■

callKey: (Mandatory) This field contains a "Call Key" value that the device uses to determine which call to record. This is required because REST messages are sent out of call context (i.e., not in SIP messages).

To associate a "Call Key" value with incoming calls belonging to a specific IP Group for which you want to record (according to the rules in the SIP Recording Rules table), you need to use SIP message manipulation to obtain this value from some element in the incoming SIP INVITE message (for example, from a specific header). The "Call Key" is specified in message manipulation using the syntax variable Param.Call.HashKey or Param.Peer-Call.HashKey in the 'Action Subject' parameter. If the device receives a REST request whose "CallKey" field contains the same value as the "Call Key" value obtained by message manipulation, then the device records this call.

The usage of the syntax variable Param.Call.HashKey and Param.Peer-Call.HashKey in message manipulation rules depends on the following:

●

If the rule is assigned using the 'Inbound Message Manipulation Set' parameter for the source IP Group:

◆

Param.Call.HashKey represents the incoming call leg.

◆

Param.Peer-Call.HashKey represents the outgoing call leg.

●

If the rule is assigned using the 'Outbound Message Manipulation Set' parameter for the destination IP Group:

◆

Param.Call.HashKey represents the outgoing call leg.

◆

Param.Peer-Call.HashKey represents the incoming call leg.

Such rules are used internally only by the device (to store the "Call Key" value) and don't modify the outgoing INVITE message.

■

role: (Optional) This field is used by the device as an additional condition in the SIP Recording Rules table ('Recording Server Role' parameter) for finding a matching rule. If the value of this field is the same as that configured in the SIP Recording Rules table, the device uses the rule The field can contain up to 20 characters.

■

callRecordingDestUsername: (Optional) This field defines the SIP user part of the Request-URI in the INVITE message (To header) that the device sends to the SRS. The field can contain up to 60 characters. If this field is present, its value overrides the 'Recording Server (SRS) Destination Username' parameter settings, as described in Configuring SIP User Part for SRS.

■

headers: (Optional and applicable only to Command: "start") This is an array of objects that defines up to 10 additional headers (name field) and their values (value field) to include in the SIP INVITE message that the device sends to the SRS.

When the REST request contains the "Command: stop":

●

If it also contains only the "callKey" field, the device stops the recording of all REST-triggered SIPREC sessions that have the same call key value and that don’t have a role defined for them.

●

If it also contains the "callKey" and "role: <a value>" fields, the device stops the recording of all REST-triggered SIPREC sessions that have the same call key value and whose rule in the SIP Recording Rules table was matched by the same role value ('Recording Server Role' parameter).

●

If it also contains only the "callKey" and "callRecordingDestUsername" fields, the device stops the recording of all REST-triggered SIPREC sessions that have the same call key value, had an empty "role" field, and used the same destination username as specified by "callRecordingDestUsername".

●

If it also contains the "callKey" and "role: <a value>", and "callRecordingDestUsername", ” the device stops the recording of all REST-triggered SIPREC sessions that have the same call key value, had the same "role" value, and same destination username as specified by "callRecordingDestUsername".

The following are examples of REST requests for triggering SIPREC:

■

REST request to start recording, containing only mandatory fields:

{
"command": "start"
"callKey": "aaa",
}

■

REST request to start recording, containing all fields:

{
"command": "start",
"callKey": "aaa",
"role": "agent_assist",
"callRecordingDestUsername": "username_abc",
"headers": [
    {
        "name": "x1-header", 
        "value": "x1-header_value"},
    {
        "name": "x2-header", 
        "value": "x2-header_value"
     }
  ]
}

➢

To configure SIPREC triggered by REST:

Open the SIP Recording Rules table (see Configuring SIP Recording Rules), and then add a rule that is also configured with the following parameters:

●

'Trigger' = REST

●

(Optional) 'Recording Server Role' = <same value as will be in the "role" field of REST requests>

Configure SIP message manipulation rule to obtain the "Call Key" value, using the syntax Param.Call.HashKey or Param.Peer-Call.HashKey. For example, the following rule in the Message Manipulations table obtains the call key value from the SIP header "X-ConversationId":

Assign the Message Manipulation rule (Set ID) to the IP Group (see beginning of this section regrading inbound and outbound manipulation).