Contact usRequest a demo

Conversation recording

Unblu’s conversation recording capabilities help your organization to meet compliance requirements and to support high standards of service.

When customers chat with your agents, a record of the entire conversation is stored in the conversation history. If your organization uses Unblu’s audio and video call features, you can record the audio and video feeds of the call. You can also record just the audio feed of a call.

The conversation recording feature introduced with Unblu 7 extends these recording options to the co-browsing and screen sharing collaboration layers and allows you to archive audio and video calls.

You can configure Unblu to start recording automatically, or to let agents manually start recording a conversation when they feel it’s necessary or appropriate.

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.

How conversation recording works

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:

  1. Enable conversation recording for your account by setting the account-level configuration property com.unblu.messenger.recordingEnabled to true.

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

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

Conversation recording announcement banner

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

Conversation recording behavior

A number of configuration properties influence the recording itself:

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:

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.


There are three webhooks for conversation recordings:

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.


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

See also