The Meya Developer Hub

Welcome to the Meya developer hub. You'll find comprehensive guides and documentation to help you start working with Meya as quickly as possible, as well as support if you get stuck. Let's jump right in!

Sensitive Data

Overview of Sensitive Data features within Meya

This guide provides an overview of how sensitive data is handled on the Meya platform.

To set up the Sensitive Data integration, check out How To Setup the Sensitive Data Integration.


Want to know how to access encrypted, decrypted, and redacted versions of sensitive data from your app code? Check out this guide:

Sensitive data: scopes, Jinja2 filters, and Python APIs


Data Encryption Key (DEK): A key designed to encrypt and decrypt data. The same symmetric DEK that encrypted the data must be used to decrypt it. When the DEK is expired or destroyed, the data can no longer be decrypted. On the Meya platform, DEKs are unique to each piece of sensitive data.

Key Encryption Key (KEK): A key that is used for encrypting and decrypting other keys. Two types of KEKs are generated by the Meya platform for sensitive data:

  • the app KEK, which is unique per app and cycles every 24 hours, and
  • the ref KEK, which is unique per piece of sensitive data.

Time-To-Live (TTL): The period during which the sensitive data is valid. After the TTL has expired, the sensitive data is only available in redacted (★★★★★) form.

  • app KEKs have a TTL of 24 hours
  • sensitive data has a TTL of 24 hours

How does it work?

Here’s an overview of the encryption/decryption process.


  1. Data flagged as sensitive is given a TTL which, by default, is 24 hours.
  2. A unique ref KEK is generated for the data, along with an ref ID that can be used to find the sensitive data later for decryption.
  3. A unique DEK is generated for the data.
  4. The data is encrypted with the DEK.
  5. The DEK is encrypted with the ref KEK, and then again encrypted with the app KEK.
  6. The encrypted data and encrypted DEK are stored using the ref ID and the TTL.
  7. The ref KEK and ref ID can now be used for future decryption.


  1. The ref KEK and ref ID are extracted.
  2. The encrypted data and encrypted DEK are retrieved from storage using the ref ID.
  3. The DEK is decrypted first using the app KEK, then decrypted again using the ref KEK.
  4. The sensitive data is decrypted using the DEK.

What data gets encrypted, and when?

Entries can have certain fields flagged as sensitive. For example, the meya.text.event.say entry has the text field flagged as sensitive. Sensitive fields are encrypted if the entry itself is flagged as sensitive.


Encrypted when

HTTP entries

transport: true

WS entries

transport: true


transcript: true and thread.mode != bot

Media events

transcript: true

Component responses

transcript: true and sensitive: true for the component

Trigger responses

sensitive: true for the incoming event

Component response example


In order to enable encryption, the sensitive data integration needs to be added to your app.

How To Setup the Sensitive Data Integration

Assuming that the Sensitive Data integration is enabled and has transcript: true (the default), the result field of the Response class will be encrypted since the component’s sensitive property is True by default:

HTTP and WS transport encryption

When the Sensitive Data integration file has transport: true (the default), all HTTP and WS entries are flagged as sensitive and are encrypted.

Non-bot mode encryption

When the Sensitive Data integration file has transcript: true (the default), events can either be flagged as sensitive: true or sensitive: false based on the thread.mode, and based on the event user’s type.

bot mode is not considered sensitive; anything else (e.g. agent, prechat) is and will be encrypted. The agent and system user types are considered sensitive.

How long is sensitive data available?

Sensitive data is encrypted and stored for 24 hours. Contact us if you need to use a different configuration.


Data marked as sensitive CANNOT be decrypted after the TTL expires. It will only be available in its redacted form.

When is sensitive data encrypted?

Sensitive data is automatically detected and encrypted at the incoming edge of integrations, based on the rules outlined above.

When is sensitive data decrypted?

Sensitive data is auto-decrypted at the outgoing edge of integrations only when that integration has been flagged to process sensitive data.

  • Messaging integrations will always process sensitive data.
  • Customer support integrations will always process sensitive data.
  • Other integrations require a manual override in order to decrypt sensitive data.
  • Authorized developers (typically admins) can view sensitive data on the Logs page of the Console until the sensitive data TTL expires:

What happens to sensitive data when its TTL expires?

When the sensitive data’s TTL expires, the encrypted data and encrypted DEK are deleted. Trying to decrypt expired sensitive data always results in the redacted form: ★★★★★

Can apps use sensitive data?

Sensitive data can be used by your app, in its encrypted form or (until the TTL expires) in its decrypted form. For example, you can copy encrypted sensitive data from an original event to flow scope, thread scope, or user scope, or you can pass decrypted sensitive data to a component for processing.


Be careful when handling sensitive data in BFML or Python. If you decrypt sensitive data, you need to make sure you aren’t logging it or using it for other non-sensitive entries. Also avoid decrypting then re-encrypting sensitive data, because this will extend the built-in TTL.

Complete example

Imagine a user requests to be transferred to an agent. Let’s take a look at what will happen to their sensitive data throughout the conversation.

In this example, the user’s email address has been marked as sensitive data, which is why it is encrypted while the thread.mode is prechat.

When the chat is transferred to the agent, all of the data is considered sensitive (which is the default behaviour when thread.mode is agent) and is encrypted.

Updated 3 months ago

Sensitive Data

Overview of Sensitive Data features within Meya

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.