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

SESSIONSTARTED

Sent when the SIPRec session is answered. Note: This event is not sent if the session is started using the legacy method recordCall:true.

Parameters

Example

{
    "event": "SESSIONSTARTED",
    "sessionId": "67977c53-5451-4829-8d32-1e5cffcb66f6",
    "startTime": 1715190000000,
    "traceId": "trace-xyz",
    "sessionReferenceId": { "sessionprop": "idA" },
    "metaData": "<xml…>"
}

SESSIONCOMPLETED

Sent after all streaming/recording has finished and the call is torn down. Note: This event is not sent for sessions started using the legacy method recordCall:true.

Parameters

Example

{
    "event": "SESSIONCOMPLETED",
    "sessionId": "67977c53-5451-4829-8d32-1e5cffcb66f6",
    "traceId": "trace-xyz",
    "sessionReferenceId": { "sessionprop": "idA" }
}

STREAMSTARTED

Sent once the WebSocket connects and media streaming begins.

Parameters

Example

{
    "event": "STREAMSTARTED",
    "sessionId": "abc123",
    "streamId": "stream-789",
    "url": "ws://127.0.0.1:8765/",
    "channels": 2,
    "startTime": 1715190000500,
    "traceId": "trace-xyz",
    "sessionReferenceId": { "sessionprop": "idA" },
    "streamReferenceId": { "streamprop": "streamval" }
}

STREAMSTOPPED

Sent when streaming ends normally (e.g. after SIP BYE).

Parameters

Example

{
    "event": "STREAMSTOPPED",
    "sessionId": "abc123",
    "streamId": "stream-789",
    "url": "ws://127.0.0.1:8765/",
    "stopTime": 1715190005500,
    "traceId": "trace-xyz",
    "sessionReferenceId": { "sessionprop": "idA" },
    "streamReferenceId": { "streamprop": "streamval" }
}

STREAMFAILED

Sent if streaming cannot start or is interrupted.

Parameters

Example

{
    "event": "STREAMFAILED",
    "sessionId": "abc123",
    "streamId": "stream-789",
    "url": "ws://127.0.0.1:8766/",
    "reason": "Connection refused",
    "traceId": "trace-xyz",
    "sessionReferenceId": { "sessionprop": "idA" },
    "streamReferenceId": { "streamprop": "streamval" }
}

STOPFILERECORDINGFAILED

Sent if a STOPFILERECORDING command fails for a specific session or file recording.

Parameters

Example

{
    "event": "STOPFILERECORDINGFAILED",
    "sessionId": "015b5b80-c275-11ed-a32c-fddf7fd4273c",
    "recordingId": "015b5b81-c275-11ed-a32c-fddf7fd4273c",
    "domain": "sip.test.iotcomms.io",
    "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...fgrK1GUJpHbH0qbU_4MOgsBgFH6i-aBX2U7K-muoQUw",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/awscodestar-iotcomms-lambda-test-snsResponseQueue-1M4RNBRCQQX0U",
    "commandRegion": "eu-west-1",
    "error": "recordingId not found",
    "traceId": "trace-xyz",
    "sessionReferenceId": { "sessionprop": "idA" },
    "recordingReferenceId": { "streamprop": "recval" }
}

STOPSTREAMFAILED

Sent if a STOPSTREAM command fails for a specific session or stream.

Parameters

Example

{
    "event": "STOPSTREAMFAILED",
    "sessionId": "015b5b80-c275-11ed-a32c-fddf7fd4273c",
    "streamId": "015b5b81-c275-11ed-a32c-fddf7fd4273c",
    "domain": "sip.test.iotcomms.io",
    "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...fgrK1GUJpHbH0qbU_4MOgsBgFH6i-aBX2U7K-muoQUw",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/awscodestar-iotcomms-lambda-test-snsResponseQueue-1M4RNBRCQQX0U",
    "commandRegion": "eu-west-1",
    "error": "streamId not found",
    "traceId": "trace-xyz",
    "sessionReferenceId": { "sessionprop": "idA" },
    "streamReferenceId": { "streamprop": "streamval" }
}

RECORDINGSTARTED

This event is sent when a SIPRec recording has started. Note: Legacy recordings (via recordCall:true) do not include the fields traceId, sessionReferenceId, or recordingReferenceId.

Parameters

Example

{
    "event": "RECORDINGSTARTED",
    "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "traceId": "9b1deb4d-3b7d-4de8-838b-0f5f18f0a2a3",
    "sessionReferenceId": { "sessionprop": "idA" },
    "recordingReferenceId": { "recordingprop": "rec123" },
    "calledParty": "user123",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/...",
    "commandRegion": "eu-west-1",
    "domain": "sip.example.com",
    "metaData": "<recording>...",
    "recordingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "replyId": "fdkmlksfm38f8nfQekefmffmf..."
}

RECORDINGCANCELLED

Sent when recording is cancelled (via CANCELRECORDING) or by system.

Parameters

Example

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

RECORDINGREADY

Sent when recording completes and file is ready. Note: Legacy recordings (via recordCall:true) do not include the fields traceId, sessionReferenceId, or recordingReferenceId.

Parameters

Example

{
    "event": "RECORDINGREADY",
    "calledParty": "user123",
    "commandQueue": "...",
    "commandRegion": "eu-west-1",
    "domain": "sip.example.com",
    "meta": "...",
    "recordingId": "0de2bc60-14da-11e9-a3d8-2f24dd9af78e",
    "conferenceSegments": [ { "startTime": 1728890680444, "endTime": 1728890687255 } ],
    "relatedRecordings": [ /* ... */ ],
    "replyId": "fdkmlksfm38f8nfQekefmffmf...",
    "warning": "rtpTimeout"
}

RECORDINGFAILED

Sent when a recording fails to produce a file.

Parameters

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.

NOTE: This is a deprecated command to only be used with SIPRec session started with legacy method recordCall:true, instead use the STOPSESSION command for sessions with file recordings and AI Connect streams.

Parameters

Example

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

This command is sent to the SQS response queue indicated in the SESSIONSTARTED event to stop the ongoing SIPRec session and associated file recordings and AI Connect streams. Ongoing recordings and streams will be terminated and trigger RECORDINGREADY and SESSIONSTOPPED events before the session is completed with a SESSIONCOMPLETED event and the SIPRec session is terminated.

Parameters

Example

{
    "method": "STOPSESSION",
    "sessionId": "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 SESSIONSTARTED event to start a file-based recording for a specific SIPRec session. When the file recording is established, a RECORDINGSTARTED event will be emitted. If the recording fails, a RECORDINGFAILED event will be sent.

Parameters

fileTarget fields

Example

{
    "method": "STARTFILERECORDING",
    "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...IcNtVkQ8RvTzKY1Z...",
    "sessionId": "83c7a360-cf9c-11ed-8779-876722fa3073",
    "fileTarget": {
        "recordingReferenceId": {
            "customerId": "acme-42",
            "case": "pilot-A"
        }
    }
}

This command is sent to the SQS response queue indicated in the SESSIONSTARTED event to start a WebSocket audio stream for a specific SIPRec session. When the stream is established a STREAMSTARTED event will be emitted; failures produce a STREAMFAILED event; when stopped a STREAMSTOPPED event will be sent.

Parameters

streamTarget fields

Example

{
    "method": "STARTSTREAM",
    "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...IcNtVkQ8RvTzKY1Z...",
    "sessionId": "83c7a360-cf9c-11ed-8779-876722fa3073",
    "streamTarget": {
        "url": "wss://stream.example.net/audio",
        "channels": [0, 1],
        "chunkDuration": 250,
        "headers": {
            "X-Correlation-Id": "call-83c7a360"
        },
        "trustSelfSigned": false,
        "streamReferenceId": {
            "customerId": "acme-42",
            "case": "pilot-A"
        }
    }
}

This command is sent to the SQS response queue indicated in the SESSIONSTARTED event to stop an active file recording for a specific SIPRec session. When the recording has been stopped, a RECORDINGREADY event will be emitted.

Parameters

Example

{
    "method": "STOPFILERECORDING",
    "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...IcNtVkQ8RvTzKY1Z...",
    "sessionId": "83c7a360-cf9c-11ed-8779-876722fa3073",
    "recordingId": "83c7a361-cf9c-11ed-8779-876722fa3073"
}

This command is sent to the SQS response queue indicated in the SESSIONSTARTED event to stop an active WebSocket audio stream for a specific SIPRec session. When the stream has been stopped, a STREAMSTOPPED event will be emitted.

Parameters

Example

{
    "method": "STOPSTREAM",
    "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...IcNtVkQ8RvTzKY1Z...",
    "sessionId": "83c7a360-cf9c-11ed-8779-876722fa3073",
    "streamId": "83c7a361-cf9c-11ed-8779-876722fa3073"
}

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\"}"
}

This event is generated if a STOPFILERECORDING command failed with an error.

Parameters

Example

{
    "event": "STOPFILERECORDINGFAILED",
    "sessionId": "015b5b80-c275-11ed-a32c-fddf7fd4273c",
    "recordingId": "015b5b81-c275-11ed-a32c-fddf7fd4273c",
    "domain": "sip.test.iotcomms.io",
    "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.fgrK1GUJpHbH0qbU_4MOgsBgFH6i-aBX2U7K-muoQUw",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/awscodestar-iotcomms-lambda-test-snsResponseQueue-1M4RNBRCQQX0U",
    "commandRegion": "eu-west-1",
    "error": "recordingId not found"
}

This event is generated if a STOPSTREAM command failed with an error.

Parameters

Example

{
    "event": "STOPSTREAMFAILED",
    "sessionId": "015b5b80-c275-11ed-a32c-fddf7fd4273c",
    "streamId": "015b5b81-c275-11ed-a32c-fddf7fd4273c",
    "domain": "sip.test.iotcomms.io",
    "replyId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.fgrK1GUJpHbH0qbU_4MOgsBgFH6i-aBX2U7K-muoQUw",
    "commandQueue": "https://sqs.eu-west-1.amazonaws.com/292435300779/awscodestar-iotcomms-lambda-test-snsResponseQueue-1M4RNBRCQQX0U",
    "commandRegion": "eu-west-1",
    "error": "streamId not found"
}

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 STOPSESSION command fails.

Parameters

Example

{
    "type": "stopSessionError",
    "error": "recordingId does not match eventId",
    "sessionId": "9b1ace70-d0a4-11e9-841f-d3ec0b98f0e9"
}

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"
}