End-to-end Encryption for WebChat on Flex

August 25, 2022
Written by
Reviewed by

Copy of C04 Blog Text

A few months ago, Twilio announced Flex Conversations to empower companies to build tailor-made experiences between Customers and Agents on Flex.

On today's topic, we will be building a secure Webchat communication between the Customers and Agents, so secure that only the Agent and the Customer can read the messages. Not even Twilio will know what is being transmitted - so-called end-to-end encryption.

So what's exciting is, not only messages, but also attachments are end-to-end encrypted! Customers and Agents can exchange files securely. Twilio does store the media being exchanged but - as it is end-to-end encrypted - it is like storing a vault without having the keys to open it.

This blog post is a proof-of-concept and it is not production-ready. In case you decide to proceed further with the implementation, have a security specialist auditing the source-code!

Do you need end-to-end encryption?

Not all the companies have the need for end to end encryption for all their use cases, however it may be a requirement for companies who have sensitive communication with their customers. Use-cases are:

  1. Customer from a bank starts the bank Mobile App to talk with their account manager about assets, privately;
  2. Patient who started a WebChat with his/her Doctor to tell the symptoms in a way that no one else will know apart from the party the information was intended for;

Because Twilio cannot read, process or store these messages once they are end-to-end encrypted, companies and customers can relax knowing the chat messages are completely secure.

End-to-end encryption may also be a great option for European companies who need to comply with Schrems II may have concerns about private consumer data that may be processed or accessed in the US.

How it works

What is end-to-end encryption?

E2E Encryption prevents unintended users, including third parties, from reading or modifying data when only the intended readers should have this access and ability. So essentially, when the user hits the send button, the message is encrypted on the device and is sent to the receiving user, who decrypts the message when the message is received on their decide.

The foundations of e2e encryption is based on top of public key cryptography. The modern way to achieve this is the Diffie–Hellman–Merkle key exchange a method of securely exchanging cryptographic keys over public channels. Nowadays, the recommended key exchange functions to use are Elliptic-curve Diffie–Hellman (ECDH) and in our case we would use the Curve25519-XSalsa20-Poly1305 offering to achieve the encryption and decryption.

We make use of the TweetNacl.js library which is a Javascript port of the original TweetNacl library written in C.


"NaCl is also much faster than OpenSSL. For example, on one core of a 2.5GHz Intel Core i5-3210M Ivy Bridge CPU, OpenSSL's RSA-2048 encryption takes 0.13 million cycles but RSA2048 decryption takes 4.2 million cycles and elliptic-curve encryption/decryption (DH) takes 0.7 million cycles. NaCl's elliptic-curve encryption/decryption takes just 0.18 million cycles." - TweetNaCl paper.

Step by step process

  1. The communicating parties, the customer and the agent create a pair of private and public keys each. We call it the customerPrivateKey , customerPublicKey and agentPrivateKey, agentPublicKey;
  2. The customer shares the customerPublicKey with the agent while keeping the customerPrivateKey privately;
  3. The agent shares the agentPublicKey with the customer while keeping the agentPrivateKey privately. This ends the key exchange which happens during the beginning of the chat.
  4. The customer while sending a message, encrypts it with the agentPublicKey.
  5. The agent decrypts the message by using the agentPrivateKey .
  6. For the agent to encrypt a message the same steps 4 and 5 are used from the agent's perspective.

This sequence diagram shows how this would actually look in our implementation.

Handshake of the Keys between Customers and Agents
Handshake of the Keys between Customers and Agents

Known limitations

Because the end-to-end encryption works like a "tunnel" between the Customer and the Agent and no one else can read the messages, we do have a few expected limitations:

Chat Transfer: The plugin does not allow Chat Transfer from Agent 1 to Agent2. It would be possible but it not covered in this blog post. Extra development is needed to make sure - once the 2nd agent receives and accepts the task - it saves the new publicKey of this 2nd agent into the Conversation so the Customer on the WebChat can encrypt the messages with this new publicKey.

Chat Conference: Adding a third person into the Chat (either customer or agent) will also not work, reason being the same as Chat Transfer: The 3rd-person won't have the privateKey to be able to decrypt the messages, nor will know how which key to use to encrypt the messages to send them over (agentPublicKey or customerPublicKey?) - to make things simpler, we decided to now have Chat Conference at this time.

Park an Interaction: End-to-end encryption does not work with Park an Interaction feature, which is the ability to remove the Agent from a Channel while keeping the Customer in it, for cases when the customer is not so responsive, freeing the Agent to pick another Chat in a meanwhile.

Supervisors can't read the messages: Below is an example of how the Supervisors will see the messages in real-time - it is all encrypted. This happens because the Supervisor does not have the privateKey of the Agent and therefore, cannot decrypt the messages.

Supervisors can't read the messages.
Supervisors can't read the messages.


Like the idea of having end-to-end encryption in your WebChat channel? Before continuing, you'll need to walk through all the steps below:

  1. Flex Instance: you need a Twilio account with a Flex Instance
  2. Flex UI 2.0: make sure you have Flex instance with UI 2.0 enabled
  3. Flex Conversations: make sure you have Flex Conversations enabled
  4. Twilio CLI: Install in your computer our Twilio CLI which is the basis for the next Flex Plugin CLI below.
  5. Twilio Flex Plugins CLI: Install locally the Flex Plugins CLI to be able to deploy the Flex Plugin to your Flex Instance.

How to install it

Step 1 of 2 - Running the WebChat
Step 2 of 2 - Installing the Flex Plugin
  • What is it? The custom Flex Plugin to be installed on Flex (agent side) that will decrypt the messages coming from the WebChat (customers side). See the source-code.
  • Installing: Follow the instructions on how to install Flex Plugin here and at the end.
  • Testing: If everything went well, you should be able to start an end-to-end conversation visiting http://localhost:3000/ - Once a message arrives on Flex, the Agent should see a label saying "End-to-end encrypted" as shown in the screenshot below.
Conversation messages with end-to-end encryption notice

Wrapping up

That's it! Hope you enjoyed today's session on how to protect your customers even further with end-to-end encryption for WebChat on Flex.

Bruno Kilian and Prashanth Swaminathan are both Senior Solutions Engineer at Twilio. Both are currently helping companies in EMEA design great customer engagement solutions powered by Twilio.

Before, Bruno worked as Tech Lead in an Insurance Contact Center with ~ 600 agents in 4 countries and Prashanth was a Senior developer is software companies dabbling with data science.