Validating Chats, Visits and Conversions (Data Validation)

Set Digital DX to validate all chats, visits and conversions. Use this feature to ensure that incoming chats originate from the website associated with the chat button and that chat and visit parameters provided by the customer cannot be viewed or modified by any third party. When customer monitoring and/or conversion tracking is enabled, this feature also ensures that the visit/conversion data originates from the website with the monitoring/conversion HTML code.

Setup

Data validation is set for a Digital DX Website. Even if you have a single webpage only where you want to display a chat window, you must create a Digital DX website.

Fastpath: In the Web Admin Center, go to Organization > Websites > Data Validation

When enabled and required, all chat, visit, or conversion data must be validated as originating from your server before reaching an agent.

Data Validation Methods:

  • PGP: The data passed to Digital DX can be PGP encrypted using our public key and signed with your private key to completely hide the parameters passed into chat
  • HMAC-SHA512: The customer can be disallowed from tampering with the data passed to Digital DX by generating a hash of the data using a private hashing key

Both methods rely on a new parameter in the HTML: SecureParameters. This replaces custom variable parameters such as VisitRef, VisitInfo, etc. Any visit, chat or conversion related data when validation is enabled that are not passed into the SecureParameters variable will be ignored by the server. Additionally, if security fails, the chat, visit or conversion will fail as well.

For browsers with JavaScript disabled, Digital DX loads an image inside the noscript tag to register the visit/conversion. In this case, use the parameter secured to pass the secured parameters.

Note: When using a Digital DX AI-enabled chat widget, you can set the domain manually as follows:
_bcvma.push(["setDomain", "s3.amazonaws.com"]);

PGP Encryption

Passed parameters should be URL-form encoded into a single string (for example, VisitName=Robert%20Smith&VisitEmail=r.smith%40gmail.com&ChatWindowID=123456). This is what you will PGP encrypt, sign and pass as the SecureParameters variable. The final string passed in as the SecureParameters variable will look like this:

"-----BEGIN PGP MESSAGE-----\nVersion: BCPG v1.50\n\nhQEMA9/66abKVXSZAQf/UT+3OtVApwD0H+Fv2S5bXqMfkvHEQgbvXLwMiLPRy2gs\nv3L4EbMGMoIjt8Leg1D/M8bgbovYEs546LwXdAcOQt/n4c2+9WB8mph9lDW4+z9U\n5eWwwDjatrF8yKvpVM+g0+y8SEtuuBr2xrNfXBaCXRSyEN/88tl7drvIjzAg5lUV\nuPMtDvLnE9bAhu02FQx04Dc0lKGDROPlXCp/6tW6rXRmdvZfPRe4GDCzkHoZVOGR\nByNMD1swSIWC60IL5so4wWvmOqgP/fU57W2QNz7wmF9RtSG+L8zdhYX0BKdQAOVL\nKzhRtoMbBpNcT1m0prFhw40sfGDcVnPLJhD4RvLv79LBpwE2HeW3LNm6ZH45ou1A\nmIzik8ZGExDVLY4N9tax6goP1tYXTOq2Zc/XuwIQHhXMdEZaxeLppsjt1cOym/BV\n/2y8uPO8DPQa4jTXDPOsmLJpzAJMnk3EhMMaDDzOIS32i8IyY2sYPgd651ifXrO7\n38zCnPC6zMByBuwqvoT5xlELYE0KFRvm7fmYhYK2KHQrazneESRX0TnLrI3k6mSR\ndK/MSLVb5v6aNY6f/RySADE/XqhEJ8DVXRyN8Qum+vtl1PMGOothaFemT4bZbZ+8\nw7PKCZSFWqKcEZyk1eJl02V8u1VgmYkaya2vvLGFqTGxSVk6jALrPcIyCxW7z1XV\nVSwdraDtqMyJ6aAOkUEF5qidyupoajpyjxWRsaM5Al/VJOjR6u97fu9aSNtGNW73\nmmpqBh2MwbPvO5wWTadN3VLRowlkzNWIX0pdKvdA69fQ4NlGLra9bmH0ofjQuCl9\nNTRAqn5pbyb8aCyWtxMTtgxZwgNsdWMg0yYMLV+HdH3zVT6Bc+lExzOl5rxOXxbz\nQxj3Bqil615AQP2JIi4A6FQ0+Om1xNtm+t6eIFAR3GDYjaw+GgBv+r4mdXRfz/6I\nOQysntG1rMgCHjXg6B2y46PAp2tdVptJVcUhyz93m99MBT3nKtUmmb5sVHJRnmIg\nQjQv+3SKjVnMwncHveNXosBBeem2Vdrb+lVbI3eQ0XD/fEi43oQdl8hSNuqfw1jy\nDz4Gi2EaYyaDqrRMS6nEMaOujfD6zcPpbR8MSbmQTvmi5eOWPQZhopXrN2ogxtea\n5jUabllMN5PxGkXWBAhWG1hUVkYH8SMucQ==\n=/htM\n-----END PGP MESSAGE-----"
Important: When using a Digital DX AI-enabled chat window, the ChatKey is pre-populated by the system. In this case, an Unsecured=ChatKey parameter must be used.

You can provide your public signing key on the New/Edit Website window. Digital DX uses it to generate a new server key in the back-end for encrypting the data and providing you a public key for encrypting the data.

The server-side generated keys are 2048-bit, and we recommend you use the same key size for your signing key.

For your first test, you can encrypt your data and pass it into the website setup data verification area. The server will decrypt it, verify the signature, and return the plain-text data or any error messages encountered.

HMAC-SHA512 Hashing

The most secure method of validating chats is the full PGP encryption. However, for ease of implementation, we also support the HMAC-SHA512 hashing algorithm.

The parameters you want to pass should be URL-form encoded into a single string (for example, VisitName=Robert%20Smith&VisitEmail=r.smith%40gmail.com&ChatWindowID=123456&Unsecured=ChatKey). The private hashing key will be concatenated in front of this value, and then hashed using the HMAC-SHA512 algorithm. The hashed value should then be hex-encoded and appended to the front of the SecureParameters variable. The final string passed in as the SecureParameters variable will look like this:

"1939D964B68EBFA61DE8C0B45D0C3C4836169C87DAB362116474A3B67B113B65F0172D3FA3191EC3525DA3E50B11A09B00B0A2869A1585EF148420347DE17A9EVisitName=Robert%20Smith&VisitEmail=r.smith%40gmail.com&ChatWindowID=123456&Unsecured=ChatKey"
Important: When using a Digital DX AI-enabled chat window, the ChatKey is pre-populated by the system. In this case, an Unsecured=ChatKey parameter must be used.

On the New/Edit Website window, you can create and delete the private hashing keys used to validate the customer data.

For your first test, you can hash the key and data to append the data to the hash and pass it to the data verification area of the New/Edit Website window. The server will parse out and verify the hash, returning plain-text data or any error messages.

Parameters

Once validation is enabled, you can use both original parameter names ("vr", "vn", etc.) and human-readable versions:

Friendly Name Original Meaning
URL url The current page of the customer (also the chat launch url when a chat is launched)
ReferrerURL referrer The referring page of the customer
VisitName vn The name of the customer
VisitRef vr A reference value for the customer
VisitInfo vi An information value for the customer
VisitEmail ve The email address of the customer
VisitPhone vp The phone number of the customer
CustomURL curl The custom URL for the chat
VisitorIcon vicon The chat icon for the customer
OperatorIcon oicon The default chat icon for the agent
LastName ln The last name of the customer
FirstName vn The first name of the customer (synonymous with VisitName)
InitialQuestion iq The initial question for the customer in chat
ConversionRef cr The conversion reference value for the conversion (must be unique per conversion code)
ConversionInfo ci An information value for the conversion
ConversionAmount ca The amount of the conversion (should be a number simply as 1000.15 for one thousand and fifteen one hundredths)
LanguageCode lc The language code for the chat
customField_[name]   Value of the custom field with the given name

Additional fields that require validation:

Friendly Name Original Meaning
ChatButtonID cbdid The ID of the chat button used to launch the request (which will additionally set the department and chat window if not overridden with another parameter)
Important: To show the proper chat window, you must either define the ChatWindowID (or ChatButtonID) parameter as a secure parameter, or the cwdid (or cbdid) parameter as an unsecured one. Otherwise, your chat will be displayed in a default chat window. The default window does not support bot chats.
FloatingChatButtonID cbdid The ID of the floating chat button used to launch the request (synonymous with ChatButtonID)
ChatWindowID cwdid The ID of the chat window to show to the customer in chat
Important: To show the proper chat window, you must either define the ChatWindowID (or ChatButtonID) parameter as a secure parameter, or the cwdid (or cbdid) parameter as an unsecured one. Otherwise, your chat will be displayed in a default chat window. The default window does not support bot chats.
DepartmentID rdid The ID of the department to which the chat should be assigned
OperatorID roid The ID of the agent to whom the chat should be assigned
ConversionCodeID ccid The ID of the conversion code
InvitationID idid The ID of the associated Auto-Invite Ruleset

Finally, there are several validation-related fields for enhancing chat functionality once the chat is validated:

Friendly Name Original Meaning
Type type The type of the request to enforce. Chat, visit, or conversion. Recommended on all requests.
Expiration expires The time when the request should no longer be considered valid. Recommended on all requests. Counted in milliseconds from midnight 1970-01-01 UTC.
Note: The expiration should allow for a realistic duration of a session, and not too short.
ChatKey ck A unique identifier for this chat request. Repeated chat launches with this key will fail. Recommended on all chat-type requests.
Note: Assign this parameter to a session ID or similar to allow for launching more than a single validated chat during a session.
When using a
Digital DX AI-enabled chat window, the ChatKey value is pre-populated by the system. This parameter must be listed as a value in the Unsecured parameter.
VisitorKey vk A unique identifier for this customer. If an agent blocks the chat, it blocks any chat/customer with this VisitorKey from re-launching chat.
Unsecured unsecured An & separated list of parameter names. These parameters when not present in the validated data can be pulled from the query string of the request normally and/or changed/populated without server validation. For example: VisitName&InitialQuestion&VisitPhone (note the & must be URI encoded to %26 when it is part of the secure parameter string.)
Important: When using a Digital DX AI-enabled chat window, the ChatKey is pre-populated by the system. In this case, an Unsecured=ChatKey parameter must be used.

API Parameters

If you are using the chat API, the following parameters are required when the chat is created:

Friendly Name Original Meaning
APIKey APIKey The API key being used. This must match the API key passed in through the authentication header.
Data Data Pre-populated data passed into the chat. (Note: Individual fields must be listed in the 'Unsecured' parameter to not require validation.)

Error Messages

Improper setup can result in the following errors:

Chat Not Validated
You have not passed in the required validation. Either there is no validation or the Type parameter has been set incorrectly (for example, you use the type visit to launch a chat).
Error Validating Chat
You tried to validate the chat, but the hash/encryption process was unable to either decrypt or verify the information.
Validated chat launch has expired
You are passing in an Expiration timestamp that is in the past. Make sure of the following: Confirm that your server's clock is accurate; Confirm that you are passing in the time dynamically at chat launch; Confirm that you are providing a sufficient buffer so chats can't be launched after they expire.
Validated chat launch has already been used
You are passing in a ChatKey value that has already been used to launch a chat. Confirm that the chat key is unique per potential chat launch or is being dynamically generated at chat launch.

If customer monitoring or conversion tracking is not being generated correctly, use the verification area of the New/Edit Website window to verify that the data has not expired and that type is set correctly.