Contact usRequest a demo

Record retention policies

Unblu stores various types of data about conversations, such as the participants and the messages they entered. For some entities, you may want to ensure that they’re only deleted after a certain period. You may also have to do so to comply with legal requirements. To this end, you can specify record retention policies for different entities, depending on how long you want them to remain in the Unblu database.

Unblu lets you specify record retention policies for:

  • Audit log entries

  • Conversations

  • Person presences and related entities (persons and device info entities); this is a preview feature

  • Webhook call log entries

The record retention policy for person presences also affects how long Unblu retains device and anonymous person entities.

How record retention policies work

A record retention policy ensures that a specific time interval has passed before entities of a certain type are marked for deletion and collected by a garbage collection job. This interval runs from the timestamp of a particular event until the end of the period defined in the policy.

The event in question depends on the type of entity:

  • Audit log entries: the end of the retention interval is calculated from the timestamp of the entry’s creation.

  • Conversations: the end of the retention interval is calculated from the timestamp of when the conversation ended.

  • Person presences and related entities: the end of the retention interval is calculated from the timestamp of when the person presence ended, that is, when the person went offline or logged out.

  • Webhook call logs: the end of the retention interval is calculated from the timestamp of when the webhook call was executed.

When an entity is collected by a garbage collection job, the following data is deleted:

  • Audit log entries: the audit log entry in question

  • Conversations: the conversation and everything related to it, such as:

    • Messages

    • Files exchanged during the conversation

    • Bot threads

    • Conversation-specific configuration and text property settings

    • Canned response usages

    • Invitations to join the conversation

    • Any conversation recordings and their associated blobs

    • All conversation participations, presences, state changes and sessions

  • Person presences and related entities:

    • When a person presence is deleted, all related information is also deleted: person presence tracking, conversation presences, and geolocation records.

    • When a person is deleted, their related device info, activation timestamps, canned response usages, reasons for autopausing notifications, and metadata properties are also deleted.

  • Webhook call logs: the webhook call log entry in question, any blobs associated with the webhook call—​this is the case if the request or response string was contained more than 5000 characters—​and any references to the blobs.

Note that the order entities are deleted in isn’t specified. For example, if the number of entities of a particular type that expires within a check interval is greater than the batch size, you can’t know which entities will be deleted when the job is executed next.

Retention of person presences

This is a preview feature. It may be subject to change or removal with no further notice.

To enable preview features, set com.unblu.platform.enablePreview to true.

For more information on preview features, refer to the Unblu release policy.

New accounts start with person presence retention disabled, and only a superadmin can enable it. While it’s disabled, Unblu never deletes the account’s person presences, device information entities, or anonymous person entities.

The record retention policies of person presences and their related entities have some particular features.

  • Person presences are deleted even if they’re referenced by a message in a conversation or a conversation presence.

    If you set the person presence retention interval to, say, 1 day, and the conversation retention interval to 10 days, person presences referenced by a conversation are marked for deletion before the conversation is deleted.

  • Device information entities are only marked for deletion if they’re no longer referenced by a person presence.

    They store the name and version of the device’s operating system and browser, the raw user agent string, the device type, and the screen size. They also store the device identifier, the person the device belongs to, when Unblu last saw the device, and when two-factor authentication was last completed on it. The device identifier is the value of the device cookie or, in a mobile app, the mobile SDK’s device ID. For devices that receive push notifications, device information entities store the push tokens and push notification settings, too.

  • Person entities are only marked for deletion if they’re anonymous—​that is, if they aren’t authenticated—​and there are no references to them from person presence or user entities.

    Person presence retention removes an anonymous visitor’s person presences, conversation presences, person presence tracking, geolocation records, and device information, as well as the person entity itself. The conversation and audit log retention policies remove the visitor’s conversations and audit log entries. The visitor’s device cookie expires after com.unblu.identifier.deviceCookieMaxAge.

Geolocation

Unblu derives the approximate location of visitors, agents, and Branch clients from their IP address, and stores their continent, country, region, city, coordinates, and time zone. The geolocation record doesn’t contain the IP address. Audit log entries do, though: each one stores the IP address of the request that made the logged change, including changes a visitor’s own requests make to a conversation. Each geolocation record belongs to a person presence, and Unblu deletes it together with the presence.

To stop Unblu from storing locations for an account, set com.unblu.platform.server.geolocation.geoLocationTrackingEnabled to false. The change only applies to new sessions. Sessions that are already running keep storing their location until they end.

For sessions that start while location tracking is off, Unblu doesn’t show or send a location:

  • On the customer dashboard, these sessions are left out of the customer’s most frequent locations and the map.

  • Queue items leave the location empty.

  • The participant information popup leaves out the location.

  • Invitation webhook events and the new assignment request email don’t contain a location.

Switching location tracking off doesn’t remove the locations Unblu has already stored. The customer dashboard shows them until person presence retention deletes the presences they belong to.

The account’s person presence retention interval starts when a person presence ends. Once the interval is over, Unblu marks the presence for deletion. Person presence retention is a preview feature, and new accounts start with it disabled. Until a superadmin enables it, Unblu keeps every geolocation record.

Setting record retention policies

You can set record retention policies in the Record retention section of the Account Configuration interface, or by calling the Unblu web API endpoint /recordretention/update.

Admins can change the retention interval for their account within the lower and upper bounds specified by the configuration properties. Superadmins can also disable retention policies entirely.

Configuration properties for record retention policies

For each entity type, there are three configuration properties you can define:

  1. The default retention interval for the entity. These retention intervals are automatically applied to the record retention policies of new accounts. The exception is person presences, whose retention is disabled in new accounts.

  2. The maximum retention interval for the entity. These retention intervals are relevant when you modify an account’s record retention policies in the Account Configuration interface. If the admin enters a value that exceeds the value of the relevant configuration property, an error message appears beneath the input field.

    Setting a large maximum retention interval increases the number of records stored in the Unblu database. In time, this can lead to performance issues. Retention intervals of more than 1 year are strongly discouraged. If you need to store data for longer than that, use a dedicated archiving system.

  3. When to display information about an impending deletion in the relevant Unblu UIs. These configuration properties provide default values for the record retention policies of new accounts, but they also affect existing record retention policies. Changes you make to them are reflected in the Record retention section of the Account Configuration interface and vice versa.

    The possible values are:

    • One week before deletion; this is the default value

    • One day before deletion

    • The day of deletion

    • Never

For more information on the individual configuration properties, refer to the Record retention section of the configuration properties reference.

Permissible retention intervals

The retention intervals you specify must have a minimum duration.

  • For audit logs, conversations, and person presences, the shortest permissible retention interval is one day.

  • For webhook call logs, the shortest permissible retention interval is one hour.

If you set a retention interval that’s shorter than allowed, Unblu applies the shortest permissible retention interval to the entity in question.

You can set the maximum retention interval for each type of entity with the following configuration properties:

For new accounts, you can set the default retention period for each type of entity, for example with com.unblu.record_retention.conversationRetentionIntervalDefault. Note, however, that changing these configuration properties doesn’t affect the retention interval once the account’s been created.

Orphaned webhook delivery log payloads

Under certain circumstances, some payloads are orphaned when the corresponding webhook call log entries are deleted. There is a separate garbage collection job to remove orphaned webhook delivery log payloads. You configure it with the following configuration properties:

The payload cleanup job is only required for cleaning up data created before the garbage collection feature was introduced. You can disable it by setting com.unblu.server.storage.blob.deliveryLogOrphanPayloadCleanup.enabled to false.

Conversations stuck in the CREATED state

Sometimes, conversations remain in the CREATED state. While this doesn’t have an impact on users, it does result in the number of conversations gradually increasing over time.

There’s a cleanup job that deletes conversations in the CREATED state that also match the following criteria:

  • The engagement type is one of the request or PIN engagement types.

  • The timestamp of when the last message was sent in the conversation is empty, that is, there were never any messages in the conversation.

The cleanup job to remove conversations that meet these criteria may be configured with the following configuration properties:

  • com.unblu.conversation.cleanup.created.checkInterval

  • com.unblu.conversation.cleanup.created.minTimeSinceCreation

  • com.unblu.conversation.cleanup.created.batchSize

See also