Skip to main content

Chat widget

Go to the main menu -> "Setup" -> "Chat setup".

Chat Configuration Terminology​

  • Website: Each website can have several (sub-) domains that the chat can be accessed from and can contain several chat configurations. E.g. several domains pointing to the same website should be all registered in the same website in ITX Portal.
  • Chat configuration: specifies different settings for the given site. The configuration that will be used is given by the most specific matched “URL Postfix” for the given opening hours.
  • URL Postfix: the rest of the URL after the domain.
  • Chat design: specifies different visual settings to match the design of the website it’s showed on. Designs are shared in corporation / corporation group. One configuration can have at most one design.

Passing verified information from website to ITX Portal​

Goal​

Pass and display verified information about the website customer in ITX Portal.

Overall explanation​

The integrity of the verification is achieved by the fact that both the website and ITX Portal knows a common secret. When both parse the information in a specific way we can know for sure that it’s not manipulated in between.

Note: the security to make sure content is not visible to 3rd parties is achieved by HTTPS and is not covered further in this document.

Steps​

Step 1: Generate hash-secret from ITX Portal​

This step must be performed by an ITX user with access to the Chat Setup.

Go to the main menu → "Setup" → "Chat setup" and open the site editor.

Chat site edit button

Activate the hash-verification and note the hash-secret.

Chat site edit page

Step 2: Decide structure of itxChat-object in JavaScript​

Decide on how to fill a itxChat object on the window-object. E.g. as such:

window.itxChat = {
	extSystemHash:"955688900a18261e0da9ee70f1ec3bc8804f8f1d",
	//	extSystemTag:"SYSTEM X",
	//	extSystemId:"12345",
	//	extSystemLookupCode:"12345",
	verifiedData:{
		name : "John Doe",
		phoneNumber : "+4712345678",
		email : "john@example.com",
		additionalInfoA : "A", 
		additionalInfoB : "B"
	},
	unverifiedData : {
		additionalInfoC : "C"
	}, 
	hideInputFields: true
};

The object should be filled with user/information from the server that is relevant to display to the agent or to lookup the correct customer, however no fields are required by the system.

extSystemHash MUST be generated on the server-side of the website to avoid compromising the integrity of the verification. See step 3 for instruction to generate this.

extSystemTag is optional. Represents system Third Party System and should be given by ITX.

extSystemId is optional. Represents the ID of the entity in the system given in ExtSystemTag.

extSystemLookupCode is optional. Will replace ${CODE} when using popup in external system. See ITX Dialer > External System.

External system info

"name", "phoneNumber" and "email" are used to lookup the customer in the ITX Portal if they are registered.

Other fields will be display to the agent, system data can be put in the verifiedData-object. Data that is not part of the hashing method should be put in unverifiedData-object.

The field "hideInputFields" can hide the input fields, which is typically used when all the information is already given, as in the example above.

The script above should be run before the itx-plugin, e.g.: structured as such:

<script>
	window.itxChat = { ... }
</script>
<script id="itx-plugin" charset="utf-8" async src="..."></script>

Note: If the website is a single-page application the script should run only once.

Step 3: Generate and pass hash-result to client​

Hash Algorithm:

  1. Create a list

  2. Add to list hash-secret (from Step 1: Generate hash-secret from ITX Portal)

  3. Add to list one entry for each key-value pair in the verifiedData json as such: "key:value".

    E.g. {name: "John Doe", phoneNumber: "+4712345678" } would result in the two entries:

    "userid:John Doe"
    "phoneNumber:+4712345678"

  4. Add to list the following values of the following if they’re present on the root level of the JavaScript object window.itxChat: name, tag, email, phoneNumber, extSystemTag, extSystemId, extSystemLookupCode

  5. Sort the list alphabetically and join the string using a dash: “-”.

    The example given in Step 2: Generate itxChat-object in JavaScript and the secret nawe21ASme2nasdzZcasxXA31nAQCXZha2m should result in the following string:

    additionalInfoA:A-additionalInfoB:B-email:john@example.com-name:John Doe-nawe21ASme2nasdzZcasxXA31nAQCXZha2m-phoneNumber:+4712345678

  6. Run SHA-1 on the string (and encode as Hex). The resulting hash becomes: 955688900a18261e0da9ee70f1ec3bc8804f8f1d

  7. Pass the hash to the client and set the value of window.itxChat.extSystemHash

Verify after loaded​

There are two options available for verifying the chat after the plugin script has been loaded.

  1. Reload page with an updated verifiedData object
  2. Use the utility function verifySession. This can be run before starting a chat and while in an active chat. 
    window.itxChatUtils.verifySession({ verifiedData, extSystemHash });

Full Java Example of Hash Algorithm​

with use of Gson JsonParser and java.security.MessageDigest:

/*
String name, tag, email, phoneNumber, extSystemTag, extSystemId, extSystemLookupCode;
JsonObject verifiedDataObject; generateExtSystemHashCompareString(name,tag,email,phoneNumber,extSystemTag,extSystemId,extSystemLookupCode, verifiedDataObject);
*/ 
public static String generateExtSystemHashCompareString(Object... parts) throws NoSuchAlgorithmException {
	List<String> stringParts = new ArrayList<String>(); 
	for (Object part : parts) {
		if (part != null) {
			if(part instanceof JsonObject) {
				JsonObject obj = (JsonObject) part;
				for(Entry<String, JsonElement> entry : obj.entrySet()) {
					String valueToString = entry.getValue() != null && entry.getValue().isJsonPrimitive() && ((JsonPrimitive) entry.getValue()).isString()
					? entry.getValue().getAsString()
					: Objects.toString(entry.getValue());
					stringParts.add(entry.getKey() + ":" + valueToString); 
				}
			} else {
				String partToString = part.toString();
				if (!Parse.nullOrEmpty(part.toString())) {
					stringParts.add(partToString);
				}
			}
		}
	}
	Collections.sort(stringParts); 
	String listAsString = Parse.listAsString("-", stringParts);
	String hash = sha1Hex(listAsString);
	return hash;
}
public static String sha1Hex(String text) throws NoSuchAlgorithmException {
	byte[] hash = sha1(text);
	return hexString(hash);
}
private static byte[] sha1(String text) throws NoSuchAlgorithmException {
	MessageDigest sha1 = MessageDigest.getInstance("SHA1");
	Charset utf8 = Charset.forName("UTF-8");
	byte[] data = text.getBytes(utf8);
	return sha1.digest(data);
}
public static String hexString(byte[] b)  {
	StringBuffer hex = new StringBuffer();
	int msb;
	int lsb = 0;
	int i;
	for (i = 0; i < b.length; i++)  {
		msb = ((int)b[i] & 0x000000FF) / 16;
		lsb = ((int)b[i] & 0x000000FF) % 16;
		hex.append(hexChars[msb]);
		hex.append(hexChars[lsb]);
	}

	return hex.toString();
}

SHA1 example in .NET (C#)​

static string Hash(string input)
{
    using (SHA1Managed sha1 = new SHA1Managed())
    {
        var hash = sha1.ComputeHash(Encoding.UTF8.GetBytes(input));
        var sb = new StringBuilder(hash.Length * 2);

        foreach (byte b in hash)
        {
            sb.Append(b.ToString("x2"));
        }

        return sb.ToString();
    }
}

Result​

The following images show the difference between unverified and verified data. If verified data is expected but unverified data is presented, caution and extra verification steps should be made by agent.

Unverified chat Verified chat