Zendesk Widget Customisation

At the office we’ve been using Zendesk both for support for our clients, and also as a way to organise internal it support and repairs.

Zendesk recently released a new widget that you can add to any website and that serves as a proxy for your Zendesk Helpcenter. The widget allows users to search the helpcenter, and create tickets right from your company’s website.

They also offer some customisation (custom fields, color, …) and through the API you can also prepopulate certain fields like emailadres and username.

Installing the widget is simple: you basically need to add a block of code to your website’s header:

This block of code shows you the basic form. By adding a few extra zE(function()..) lines of code, you can further tweak the forms’s behavior.

zE(function() {
	zE.identify ({
    	name:'John Citizen',       
    	email:'john@example.com'
    });
});

But filling in the same name for every user is stupid, so it’s easier to create some variables and set them from within your website’s existing code. In the example below I’ve added to variables userName and userMail which are (in this example) loaded from an external source.

zE(function() {
	var userName = document.getElementById("existingName").value;  
	var userMail = document.getElementById("existingMail").value;

	zE.identify({
		name:userName,
		email:userMail
	});
});

For example, the code below allows you to prefill the name and email field.

The widget configuration also allows you to add custom fields. At our company for example we also ask for a users Customer ID when they fill in a form. It’s a custom field we added to the Zendesk website.

Now, since a user is often already logged into our website so they can purchase stuff or check the status of their repairs, our website already knows the customer’s ID, where a customer probably doesn’t know it by head. So it would be a great user experience if we could prefill that data when the users opens the widget.

Zendesk’s Widget API doesn’t allow prepopulating custom fields by default. But it only requires a few extra lines of code to fill in those fields with existing information too.

When you inspect the source code of the widget you’ll notice that each field is listed as a with a data-reactid.

The name field has .3.1.0.2.0.1:$name as ID for example. And a custom field has a similar ID .3.1.0.2.1.0.1:$ze23905451.1

<div class="rf-Fieldset" data-reactid=".3.1.0.2.1.0">
    <label class="Arrange.." data-reactid=".3.1.0.2.1.0.1:$name">
		...
	</label>
    <label class="Arrange.." data-reactid=".3.1.0.2.1.0.1:$email">
        ...
    </label>
    <label class="Arrange.." data-reactid=".3.1.0.2.1.0.1:$ze23905451.1">
        ...
    </label>
</div>

So if we want to fill in that custom field we need its ID, and specifically the part behind the $-sign. So in our example ze23905451. Which corresponds to the custom Customer ID field we’ve added to our Zendesk forms.

Now that we know the $ID of the field, it’s fairly easy to customize the existing script so that it doesn’t only fill in a user’s name and email, but also the custom field.

First we create a new variable UserID that loads the Customer ID from our existing website.

Then we add a new key:value to the zE.identify array. The key is the $ID we found earlier in the source code, and the value is the variable UserID.

zE(function() {
	var userName = document.getElementById("existingName").value;
	var userMail = document.getElementById("existingMail").value;
    var userID = document.getElementById("existingID").value;  

    zE.identify({
        name: userName,
        email: userMail,     
        ze23905451: userID
    });
}

So now, when a user is logged in to our website, and opens the widget, the form doens’t only fill in their name and email address, but also their customer id. It’s easier for the end user, and we get the correct data into Zendesk.

It’s undocumented use of the Zendesk Widget API, but since it follows their existing code chances are it’ll keep working, and I expect them to release this information sooner later than later via the official channels too.