Call Recording

This API provides functionality to get events related to SIPRec sessions and fetch and delete recording files.

Base url: https://api.prod-eu-north-1.iotcomms.io/callrecording

This event is sent when a SIPRec recording has started.

Parameters

Example

{
    "event": "RECORDINGSTARTED",
    "calledParty": "user123",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "domain": "sip.example.com",
    "metaData": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><recording xmlns=\"urn:ietf:params:xml:ns:recording:1\">...",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This event is sent when the CANCELRECORDING command is completed or if the system decided to cancel the recording.

Parameters

Example

{
    "event": "RECORDINGCANCELLED",
    "calledParty": "user123",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "domain": "sip.example.com",
    "reason": "cancelCommand",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This event is sent when a SIPRec recording is completed and a file is ready to be copied to the final storage destination.

Parameters

Example

{
    "event": "RECORDINGREADY",
    "calledParty": "user123",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "domain": "sip.example.com",
    "meta": "\"recordingsPartsInfo\": { \"callerStreams\": [{\"start\": 1557932777534, \"ssrc\": 2408484501}], \"calleeStreams\": [{\"start\": 1557932777523, \"ssrc\": 197496009}] }",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "conferenceSegments": [
        {
            "startTime": 1728890680444,
            "endTime": 1728890687255
        }
    ]
    "relatedRecordings": [
        {
            "recordingId": "cbefcbd0-8b1c-11ef-982b-1b7455556a32",
            "startTime": 1729014126886,
            "state": "stopped",
            "recordingRole": "sibling",
            "conferenceSegments": [
                {
                    "startTime": 1728890680444,
                    "endTime": 1728890687255
                }
            ]
        },
        {
            "recordingId": "c9fa3d60-8b1c-11ef-982b-1b7455556a32",
            "startTime": 1729014123722,
            "state": "stopped",
            "recordingRole": "parent",
            "conferenceSegments": [
                {
                    "startTime": 1728890680444,
                    "endTime": 1728890687255
                }
            ]
        }
    ],
    "replyId": "fdkmlksfm38f8nfQekefmffmf...",
    "warning": "rtpTimeout"
}

This event is sent in case a recording that is started fails to produce a recording file.

Parameters

Example

{
    "event": "RECORDINGFAILED",
    "calledParty": "user123",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "domain": "sip.example.com",
    "reason": "Detailed error message explaining the failure",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This event is sent when the recording file is successfully copied to the final storage destination.

Parameters

Example

{
    "event": "RECORDINGSTORED",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "destinationBucket": "recordingbucket.company.com",
    "fileName": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e.mp3",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This event is sent when the STORERECORDING command fails.

Parameters

Example

{
    "event": "STORERECORDINGFAILED",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "domain": "sip.example.com",
    "reason": "Detailed error message explaining the failure",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This event is sent when the recording files have been successfully merged and the merged recording file is stored to the final storage destination.

Parameters

Example

{
    "event": "RECORDINGSMERGED",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "destinationBucket": "recordingbucket.company.com",
    "domain": "sip.example.com",
    "fileName": "mergedrecording.mp3",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This event is sent when the MERGERECORDINGS command fails.

Parameters

Example

{
    "event": "MERGERECORDINGSFAILED",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "domain": "sip.example.com",
    "reason": "Detailed error message explaining the failure",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This event is sent when the recording file is successfully deleted from the temporary storage location.

Parameters

Example

{
    "event": "RECORDINGDELETED",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This event is sent when the DELETERECORDING command fails.

Parameters

Example

{
    "event": "DELETERECORDINGFAILED",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "domain": "sip.example.com",
    "reason": "Detailed error message explaining the failure",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

Queue ARN: SQS URL provided in notification event parameter commandQueue

This is a queue that listens for response commands related to SNS events. The URL for the queue is passed in the commandQueue parameter of the event.

This command is sent to the SQS response queue indicated in the RECORDINGSTARTED event to stop the ongoing recording. A recording file with the recorded content up until the command has been received will be generated and once this is complete a RECORDINGREADY event will be sent.

Parameters

Example

{
    "method": "STOPRECORDING",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This command is sent to the SQS response queue indicated in the RECORDINGSTARTED event to cancel the ongoing recording. Any produced temporary recording files will be permanently deleted. When the files have been deleted a RECORDINGCANCELLED event will be sent.

Parameters

Example

{
    "method": "CANCELRECORDING",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This command is sent to the SQS response queue indicated in the RECORDINGREADY event to merge multiple recordings into a single audio file and store it in permanent storage.

Parameters

Example 1: MERGERECORDINGS

{
    "method": "MERGERECORDINGS",
    "destinationBucket": "recordingstorage.company.com",
    "destinationRegion": "us-west-2",
    "toMerge": [
        {
            "recordingId": "5e32bf50-89fd-11ef-966f-03e88116d7e5",
            "startTime": 1728890677283,
            "conferenceSegments": [
                {
                    "startTime": 1728890680444,
                    "endTime": 1728890687255
                }
            ]
        },
        {
            "recordingId": "601fe950-89fd-11ef-966f-03e88116d7e5",
            "startTime": 1728890680444,
            "conferenceSegments": [
                {
                    "startTime": 1728890680444,
                    "endTime": 1728890687255
                }
            ]

        },
        {
            "recordingId": "642ebad0-89fd-11ef-966f-03e88116d7e5",
            "startTime": 1728890687255,
            "conferenceSegments": [
                {
                    "startTime": 1728890680444,
                    "endTime": 1728890687255
                }
            ]
        }
    ],
    "fileName": "mergedrecording.mp3",
    "encryptionKey": "arn:aws:kms:region:account-id:key/key-id",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This command is sent to the SQS response queue indicated in the RECORDINGREADY event to copy the recording from temporary to permanent storage.

Parameters

Example 1: modificationParams

{
    "absoluteTimes": boolean,
    "mask": {
        "caller": [{"from": number, "to": number}],
        "callee": [{"from": number, "to": number}]
    },
    "trim": {"from": number, "to": number}
}

Where:

• absoluteTimes indicates if the times are relative to the recording start in seconds or absolute timestamps in milliseconds since Jan 1st, 1970.

• mask object is optional to specify if sections of the audio channel related to the caller or callee should be masked. An array with timestamps defining intervals to be masked is provided. The audio for these intervals will be replaced by a beep tone.

• trim object is optional to specify a subset of the original recording as an interval to be saved.

Example 2: Full Command

{
    "method": "STORERECORDING",
    "destinationBucket": "recordingstorage.company.com",
    "destinationRegion": "us-west-2",
    "encryptionKey": "arnstring",
    "fileName": "myrecording.mp3",
    "modificationParams": {
        "absoluteTimes": true,
        "mask": {
            "caller": [
                {
                    "from": 1561988732565,
                    "to": 1561988733565
                },
                {
                    "from": 1561988735565,
                    "to": 1561988735965
                },
                {
                    "from": 1561988737565,
                    "to": 1561988738565
                }
            ],
            "callee": [
                {
                    "from": 1561988733565,
                    "to": 1561988734565
                }
            ]
        },
        "trim": {
            "from": 1561988732565,
            "to": 1561988738565
        }
    },
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This command is sent to the SQS response queue indicated in the RECORDINGREADY or RECORDINGSTORED event to copy the recording from temporary to permanent storage.

Parameters

Example

{
    "method": "DELETERECORDING",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

This SNS topic is used to listen for alarms generated by the SIPRec service.

This alarm is generated if the STORERECORDING command fails.

Parameters

Example

{
    "type": "storeRecordingError",
    "error": "recordingId does not match eventId"
}

This alarm is generated if the DELETERECORDING command fails.

Parameters

Example

{
    "type": "deleteRecordingError",
    "error": "recordingId does not match eventId"
}

This alarm is generated if a recording failed with an error.

Parameters

Example

{
    "event": "recordingFailed",
    "type": "recordingFailed",
    "recordingId": "aa2763a0-f00d-11e9-b265-41d830bfc3ea",
    "domain": "sip.example.com",
    "error": "Recording completed with error\": { \"reason\":\"Error No RTP media received\", \"type\":\"stoppedWithoutMedia\"}"
}

Failure to store the recording in the temporary storage

Parameters

Example

{
    "event": "tempStorageError",
    "type": "tempStorageError",
    "recordingId": "aa2763a0-f00d-11e9-b265-41d830bfc3ea",
    "domain": "sip.example.com"
}

This alarm is generated if the STOPRECORDING command fails.

Parameters

Example

{
    "type": "stopRecordingError",
    "error": "recordingId does not match eventId"
}

This alarm is generated if the CANCELRECORDING command fails.

Parameters

Example

{
    "type": "cancelRecordingError",
    "error": "recordingId does not match eventId"
}

This alarm is generated if a publishing a notification fails.

Parameters

Example

{
    "type": "eventNotificationError",
    "error": "recordingId does not match eventId"
}

This alarm is generated when a recording file is deleted from the temporary storage due to expiration. This means that it is automatically deleted and the DELETERECORDING command has not been sent in time.

Parameters

Example

{
    "event": "tempRecordingDeleted",
    "type": "tempRecordingDeleted",
    "recordingId": "aa2763a0-f00d-11e9-b265-41d830bfc3ea",
    "domain": "sip.example.com",
    "service": "siprec",
    "error": "Recording id 9b1ace70-d0a4-11e9-841f-d3ec0b98f0e9 expired."
}

This alarm is generated if the system fails to call the newCall API endpoint.

Parameters

Example

{
    "event": "apiRequestError",
    "type": "apiRequestError",
    "domain": "company.com",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "error": "Error calling newCall API",
    "method": "POST",
    "requestUri": "https://example.com/newCall",
    "statusCode": 500,
    "statusMessage": "Internal Server Error"
}