Conversation recording

How conversation recording works

When a situation arises where conversation recording should be started—either automatically or manually—the Unblu server creates a unique entry point and launches an instance of the Unblu Rendering Service. It then waits for the recording Rendering Service to connect to the entry point.

The recording Rendering Service acts like a passive, hidden participant in the conversation. It automatically connects to any collaboration layers and calls to be recorded. The headless browser that the Rendering Service runs receives audio and video content from these calls and collaboration layers.

The Rendering Service sends the data that its headless browser receives back to the Unblu Collaboration Server. In on-premises installations, the Collaboration Server streams this data to your object storage service of choice. If you use the Unblu Cloud, you can’t choose the object storage service used.

Conversation recording files

Conversation recordings are fragmented MP4 (fMP4) files created using the H.264 codec.

The files don’t contain any metadata beyond that of any media file. The metadata related to a recording—who the participants in the conversation were, for example—are stored in Unblu. This allows you to determine the metadata of a conversation recording from the conversation details.

Unblu doesn’t encrypt the fMP4 files before storage. It’s your organization’s responsibility to ensure that its object storage is encrypted.

Configuring conversation recording

Conversation recording is a separately licensed feature of Unblu, so before you configure the feature, you must first obtain a license that covers it. Once you have that, proceed as follows:

Enable conversation recording for your account by setting the account-level configuration property com.unblu.messenger.recordingEnabled to true.
Conversation recordings aren’t stored in the Unblu server’s database, so the next step is to configure the object storage service where you want to store the recordings. Review the article Setting up a dedicated document storage for information on the relevant configuration properties.
Finally, set com.unblu.identifier.recordingEntryPointBaseUrl to the base URL that the recording Rendering Service should use to resolve to the Unblu server.

If you want to use a different API key in conversation recording URLs, add it in the configuration property com.unblu.conversation.recording.recordingApiKeyId.

Except for the first configuration property, these properties are set in the IMMUTABLE scope.

With conversation recording enabled in your Unblu account, you can define how the feature should work in conversations based on different conversation templates.

Conversation template scope configuration

To enable conversation recording in a conversation template, set the template’s configuration property com.unblu.conversation.recording.recordingEnabled to true.

Starting conversation recording

You can configure various aspects of how conversation recording is initialized.

By default, conversation recording starts automatically once something to record is launched in a conversation. You can change this behavior and let agents start conversation recordings manually with com.unblu.conversation.recording.recordingTriggeringMode.
If agents are allowed to start conversation recordings manually, use com.unblu.conversation.recording.allowManualRecording to specify which agents in a conversation may do so.
You can specify the type or types of interaction that trigger automatic conversation recording in com.unblu.conversation.recording.recordingTriggeringSources. The possible values are:
- CALL for audio and video calls
- COLLABORATION_LAYER for any collaboration layer (document co-browsing, embedded co-browsing, universal co-browsing, and screen sharing)
The setting determines when recording should start and end. Recording ends when all types of interaction that could have triggered the recording end. The following example illustrates this point: Suppose that conversation recording started because an agent launched an embedded co-browsing session. They then initiated a audio call with the visitor. During the audio call, the embedded co-browsing session is no longer needed, so the agent stops it. Recording only continues if CALL is included in the sources that trigger recording.
The configuration property com.unblu.conversation.recording.recordingMaxRetries specifies how many times the Unblu server should try to start a conversation recording.

Each attempt to start a recording starts a recording Rendering Service and waits for it to connect to the conversation’s entry point. It waits for a response for the time specified in the configuration property com.unblu.conversation.recording.initializationTimeout.

If the Unblu server doesn’t receive a response from the Rendering Service to any of its attempts to start a recording, it switches to failover mode.
Starting a conversation recording can lead to a slight delay in providing access to a call or a collaboration layer. This is because the Rendering Service must first launch and then inform the Unblu server that it has launched and is recording.

To avoid this delay, set com.unblu.conversation.recording.recordingStartMode to ASYNCHRONOUS. This lets the conversation participants start their call or collaboration session immediately. However, it may result in the recording missing the first seconds of the interaction.

If you keep the default start mode setting, SYNCHRONOUS, calls and collaboration layers won’t start until Unblu is ready to record the conversation.

Conversation recordings started manually are always asynchronous.

For information on how Unblu behaves if it fails to start recording, read the section on conversation recording failover below.

You can display a banner to inform participants when Unblu is recording a conversation.

Specify the participant roles that should see the announcement banner in com.unblu.conversation.recording.enableRecordingBanner.
Adapt the following text properties to change the contents of the banner:
You can add a button to the announcement banner that lets participants close it by including their participation role in the configuration property com.unblu.conversation.recording.allowCloseRecordingBanner.

Conversation recording behavior

A number of configuration properties influence the recording itself:

Specify the height and width, in pixels, of the recording with the configuration properties com.unblu.conversation.recording.recordingHeight and com.unblu.conversation.recording.recordingWidth respectively. The values you set here have an impact on the file size of your conversation recordings.
By default, participants aren’t informed when a recording starts or ends. You can, however, choose who should see system messages regarding conversation recording by adapting the configuration properties com.unblu.conversation.message.allowSeeSystemMessagesForRecordingLifecycle and com.unblu.conversation.recording.allowSeeRecordingAvailableMessages to your needs.

com.unblu.conversation.recording.recordedContent determines which content is included in the recording:

Set CALL to true to include audio and video calls
Set COLLABORATION_LAYER to true to record collaboration layers

Set CHAT to true to include the text chat in the recording

The chat view in the conversation recording includes all system messages as well as any messages exchanged directly between agents that participated in the conversation. You should take this into consideration when deciding how to set com.unblu.conversation.recording.allowSeeRecordingAvailableMessages (see below).

If you choose not to record the interaction that triggers recording, the recording is blank until a source that should be recorded is launched.

By default, Unblu records both the audio and video feeds of a conversation. If you only want to record the conversation’s audio feed, set com.unblu.conversation.recording.recordingMode to AUDIO_ONLY.

Conversation recording failover

Conversation recording may fail to start, or a recording may be interrupted. For conversation recordings started automatically, com.unblu.conversation.recording.recordingFailoverMode defines how Unblu should react in these circumstances:

RETRY failover mode starts a new recording if an error occurs. Any calls or collaboration layers currently in use continue to work while Unblu tries to start a new recording. It does, however, create a gap between the recordings where the interaction isn’t recorded.
ABORT failover mode stops the recording and closes any calls or collaboration layers that were being recorded when the error occurred.

The default failover mode is RETRY.

Failover mode also comes into play when an error occurs while starting a recording. Once Unblu has reached the maximum number of retries to launch a Rendering Service for conversation recording, failover mode determines how the Unblu server deals with the issue.

If failover mode is set to RETRY, Unblu keeps trying to start recording. However, its behavior while doing so depends on the start mode.

In SYNCHRONOUS start mode, Unblu continues its attempts to start the recording until it reaches the maximum number of retries (com.unblu.conversation.recording.recordingMaxRetries). After that, it launches the interaction while still trying to start the recording.
In ASYNCHRONOUS start mode, Unblu immediately launches the interaction that triggered recording and participants can use it immediately. It keeps trying to start the recording.

If failover mode was triggered because the object store was unreachable, Unblu won’t make any further attempts to start the recording.

If failover mode is set to ABORT, Unblu terminates the interaction that triggered the recording, regardless of whether start mode is set to SYNCHRONOUS or ASYNCHRONOUS. This also applies if failover mode was triggered because the object store was unreachable.

When trying to recover from a recording failure, each recovery attempt involves starting a new recording Rendering Service, which requires significant resources. If the failure wasn’t caused by an issue with the recording Rendering Service, these recovery attempts would continue to consume resources. To avoid overwhelming the cluster, Unblu therefore uses an exponential backoff retry policy. The configuration property com.unblu.conversation.recording.recordingMaxRetryDelay specifies the maximum exponential backoff delay in seconds for retrying a failed conversation recording.

Conversation recording web API endpoints and webhooks

There are a number of web API endpoints and webhooks related to conversation recording.

Web API endpoints

There are three web API endpoints for conversation recordings:

/conversations/<conversationId>/startRecording lets you manually start a conversation recording. The call is only successful if all the following prerequisites are met:
- You’ve configured a compatible object storage service.
- Manual conversation recording is enabled.
- There’s an active collaboration layer or call in the conversation.
- There’s no active conversation recording, that is, a conversation recording whose state is STARTED.
/conversations/<conversationId>/stopRecording stops an ongoing manual conversation recording. Calls to the endpoint for conversation recordings started automatically fail.
/conversations/<conversationId>/getRecordingState returns the current state of the recording for the conversation in question.

For more information on each endpoint, refer to the web API reference.

For information on accessing conversation recordings through the web API, refer to the section below.

Webhooks

There are three webhooks for conversation recordings:

conversation.recording_started is sent when a conversation recording starts.
conversation.recording_failed is sent if Unblu fails to start a conversation recording.
conversation.recording_available is sent once a conversation recording is available to be downloaded.

All three webhooks are triggered for both automatic and manual conversation recordings.

Accessing conversation recordings

Conversation recordings are always related to a particular conversation, so authorized users can access conversation recordings via the conversation they’re related to.

A single conversation may have multiple conversation recordings. For example, a visitor may first request an embedded co-browsing session, which is recorded. After the embedded co-browsing session has ended, the agent and visitor want to speak together, so the agent initiates an audio call, which triggers a second conversation recording. Both recordings are related to the same conversation.

All a conversation’s recordings are listed in the fly-in page displayed when you select a conversation in the conversation history. Each recording is linked in the fly-in page. Clicking it opens the recording in a new tab.

A conversation recording in the conversation fly-in page

Conversation recordings are also embedded in the history of the conversation itself. If you open a conversation in the conversation history, you can see the point in the conversation at which a recording started and ended along with any chat messages that were exchanged while the recording took place. Here, recordings are displayed in their own recording available message type.

A conversation recording displayed in the conversation itself

The configuration property com.unblu.conversation.recording.recordingFilenamePattern lets you specify a pattern for the names of the files created when recording is over. The filename appears in both the conversation and the conversation details fly-in page.

Recordings of both audio and video as well as audio-only feeds are stored as MP4 files.

Conversation recordings remain available until the conversation they were made in is deleted. There is no way to delete conversation recordings while the conversation they’re related to exists.

Accessing conversation recordings through the web API

You can access conversation recordings with the web API endpoint /conversationhistory/getConversationRecordings. The endpoint works for both on-premises installations and Unblu Cloud customers. For more information, refer to the description of the endpoint in the web API reference.

Visitor access to conversation recordings

Visitors have access to the recordings in a conversation, too, provided their role is listed in com.unblu.conversation.recording.allowSeeRecordingAvailableMessages.

Recordings are accessible in the conversation’s chat in both the integrated visitor UIs (Embedded Visitor UI, Floating Visitor UI) and the Visitor Conversation Desk.

Isolating conversation recording in on-premises installations

It’s possible to implement conversation recording without using external resources or APIs so that recording remains fully isolated in the Unblu cluster. To do so:

Calls must be configured to use RELAYED mode.
You must use a custom TURN server.
You must use an IP proxy.

For more information, refer to the article about call service providers.

The only reason the service connects to the Vonage API, as shown above, is because it has to join the call. The actual access of the audio and video stream is end-to-end encrypted and doesn’t pass through Vonage.

Requirements

To use conversation recording, you must either be running a cluster installation of Unblu, or using the Unblu Cloud.
Each recording launches a Rendering Service dedicated to recording the interaction. As a result, the number of Rendering Services required for universal co-browsing and server-based document co-browsing doubles if you record them. Take this into consideration when deciding on the resources to provision for your cluster.
In on-premises installations, you must provide an S3-compatible object storage service such as Amazon S3 or min.io, or access to Google Cloud Storage.

If you’re an Unblu Cloud customer, Unblu provides an object storage service.
The size of a conversation recording depends on numerous factors, including the resolution of the recording and the complexity of audiovisual data. As a rule of thumb, however, a 10 second recording of a collaboration layer at a resolution of 1920x1080 pixels with sound results in a MP4 file roughly 1 MB large.
Conversation recordings of audio and video feeds can be viewed in any browser that supports fragmented MP4 (fMP4). Safari and Firefox on MacOS both don’t support fMP4, nor does QuickTime.

You can download conversation recordings and view them in any media player that supports fMP4, for example VLC.