How to validate Chats, Visits and Conversions (Data Validation)

Enterprise subscribers can 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 visitor cannot be viewed or modified by any third party. When visitor 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 Website definition.

Fastpath: From the main menu of the Digital DX Desktop Client, go to Setup > Account Setup > General > Websites > New/Edit > Data validation tab > Enable data validation

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

By selecting the All HTML must be associated with a Website definition option in General Account > Settings > Extra Security, and ensuring that all Website definitions require validation, every chat assigned to an agent of the account is guaranteed to be validated.

Note: An Enterprise subscription is required.

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
  • SHA-512: The visitor 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 and VisitInfo. 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.

Important: You must define the SecureParameters variable for both the chat and visit types to have proper encryption.

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.

PGP Encryption

Passed parameters should be URL-form encoded into a single string (for example, VisitName=Robert%20Smith&VisitEmail=r.smith%40gmail.com). 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-----"

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.

Data validation relies on asymmetrical cryptography: parameters are encrypted using your private key and the public key of the server. Digital DX decrypts parameters using its private server key and your public 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.

SHA-512 Hashing

The most secure method of validating chats is the full PGP encryption. However, for ease of implementation, we also support the SHA-512 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). The private hashing key will be concatenated in front of this value, and then hashed using the SHA-512 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"

On the New/Edit Website window, you can create and delete the private hashing keys used to validate the visitor 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 visitor (also the chat launch url when a chat is launched)
ReferrerURL referrer The referring page of the visitor
VisitName vn The name of the visitor
VisitRef vr A reference value for the visitor
VisitInfo vi An information value for the visitor
VisitEmail ve The email address of the visitor
VisitPhone vp The phone number of the visitor
CustomURL curl The custom URL for the chat
VisitorIcon vicon The chat icon for the visitor
OperatorIcon oicon The default chat icon for the operator
LastName ln The last name of the visitor
FirstName vn The first name of the visitor (synonymous with VisitName)
InitialQuestion iq The initial question for the visitor 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)
FloatingChatButtonID cbdid The ID of the floating chat button used to launch the request (synonymous with ChatButtonDefID)
ChatWindowID cwdid The ID of the chat window to show to the visitor in chat
DepartmentID rdid The ID of the department to which the chat should be assigned
OperatorID roid The ID of the operator 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.
VisitorKey vk A unique identifier for this visitor. If an operator blocks the chat, it blocks any chat/visitor 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.)

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

Troubleshooting and Error Messages

Do not modify the HTML code generated by Digital DX as it may result in receiving errors. When you click Generate HTML on the Channels > Chat Buttons > HTML page, copy the complete generated code as is into the HTML source of the website that visitors see. Improper setup can result in the following errors:

Chat Not Validated
You have not passed in the required validation. Either there is no validation, that is the encrypted message is blank, or the Type parameter is missing or incorrect. The Type parameter may be incorrect, for example, if it is set to visit before adding a floating chat button.
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 visitor 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.

HTML Code Structure

Sample generated HTML is given below. When HTML is generated with an associated Website definition that has Data validation enabled, the generated HTML includes the comment /* Requires Authentication */. This provides sample data that has not been validated. You can add or remove what is needed from the data on your server, then validate the data and replace the value (either with the hash appended in the case of SHA-512, or just the raw encrypted PGP data).

For chat launches, it is best to use the function callback method to make an asynchronous call to your server to validate the chat and return the validated data.