Validating Chats, Visits and Conversions (Data Validation)
Enterprise subscribers can set BoldChat 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.
Data validation is set for a BoldChat Website definition.
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.
- PGP –The data passed to BoldChat 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 BoldChat 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.
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:
You can provide your public signing key on the New/Edit Website window. BoldChat 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. BoldChat 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.
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:
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.
|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|
|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|
|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.)|
|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
- 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.