Validating Chats, Visits and Conversions (Data Validation)
Set Bold360 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.
Data validation is set for a Bold360 Website.
When enabled and required, all chat, visit, or conversion data must be validated as originating from your server before reaching an agent.
- PGP – The data passed to Bold360 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 Bold360 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.
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. Bold360 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.
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). 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:
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.
|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|
|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 customer in chat|
|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|
|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 Bold360 ai 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.) |
Note: When using a Bold360 ai chat window, the ChatKey is pre-populated by the system. In this case, an unsecured=ChatKey parameter must be used.
|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.)|
- 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.
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 HMAC-SHA512, 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.