SIPREC Sessions

The /sip/sipRecording URL starts, stops, pauses, and resumes a SIPREC session.

URL

/api/v1/sip/sipRecording?command=<start|stop|pause|resume>&callKey=<value>

HTTP Method

POST

Request JSON Attributes

Attribute

Type

Value

Description

start

String

Starts a SIPREC session.

Note: The parameter is mandatory (either start or stop).

stop

String

Stops the SIPREC session.

Note:

■

The parameter is mandatory (either start or stop).

■

When the REST request contains the 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 no role defined.

✔

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> fields, 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.

pause

String

Pauses a SIPREC session.

Note: The pause command supports the same options as the stop command (see above).

resume

String

Resumes a paused SIPREC session.

Note: The resume command supports the same options as the stop command (see above).

callKey

String

Defines which call to record. This is required because REST messages are sent out of call context (i.e., not in SIP messages).

Note: The parameter is mandatory.

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, 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.

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

role

String

(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

String

(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.

headers

Array of Objects

(Optional) Defines up to 10 additional SIP headers (name field) and their values (value field) to include in the SIP INVITE message that the device sends to the SRS.

Note: Applicable only to the start command.

●

For more information on configuring REST-triggered SIPREC, refer to the 'On-Demand SIPREC using REST' section in the device's User's Manual.

●

The device opens one SIPREC session per target username.

Example

■

Request to start recording - containing only mandatory fields:

POST /api/v1/sip/sipRecording HTTP/1.1
Host: 10.4.219.229
Content-Type: application/json
{
    "command": "start"
    "callKey": "aaa",
}

■

Request to start recording - containing all fields:

POST /api/v1/sip/sipRecording HTTP/1.1
Host: 10.4.219.229
Content-Type: application/json
{
    "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"
     }
     ]
}