Debugging: the widget on your website misbehaves

Lesson 8 of 11 · Debugging. You find out why the widget on your website misbehaves, with the Web Widget inspector you switched on in lesson 3.

Lesson 8 of 11 · Debugging. You find out why the widget on your website misbehaves, with the Web Widget inspector you switched on in lesson 3.

The scenario

A new version of your website went live, and the widget no longer behaves as before. A value the page passes on, such as a product type, no longer reaches the ticket. Signed-in customers chat as anonymous visitors. Help articles in your AI agent's replies open in a new tab. Your web developer asks where to start.

Goal: a list of what the widget refuses or ignores on the page, with the reason, for your developer.

What you need

• The page with the problem, open in Chrome.
• In the same Chrome, signed in to your Zendesk account: as an agent or admin to check ticket fields against the account and to open the ticket, as an admin to see the allowed domains.

Steps

1. If the inspector is not open on the page, click the extension's icon and then Inspect this widget. Allow the site when Chrome asks.
2. If the inspector shows Capture started late, click Reload page. It then sees every message and zE command from the start.

3. On the Overview tab, read Checks. Each check names the problem, explains it and, where there is one, shows the zE call. Every check is explained in The checks in the Web Widget inspector.

   

4. Match the checks to what you see on your site:

   Check	What it tells you
   Conversation field, with the field ID and name	The widget ignores the value, for example because a drop-down only takes one of its option values, or because the field is not editable for end users.
   Login (JWT)	The sign-in failed or came too late. The text says why.
   Article links open in a new tab	The links point to a Help Center on its own domain, such as help.example.com. The widget only opens articles on your account's zendesk.com address in its article viewer.
   The widget refused a zE command	A call the widget did not accept, shown with its arguments.
   This domain isn't allowed	Your brand only allows listed domains in Admin Center, and the new domain is not on the list.

5. Open the Account tab. Under Login (JWT) you see the loginUser calls, each step of the sign-in, and the claims of the token your site hands the widget. The checks flag an expired token, a missing external_id, a scope other than user, a missing kid, or a token that comes after more than 4 seconds. When the sign-in works, the status reads Logged in.

   

6. On the same tab, Ticket fields and tags checks your site's conversationFields and conversationTags as the widget does: does the field exist, is it editable for end users, and does the value fit its type. Both sections are described in The Settings and Account tabs of the Web Widget inspector.
7. To see what reached Zendesk, click the Ticket link on the Overview or Messages tab.
8. Send the checks to your developer. Zendesk's side of the widget code is in How do I find the widget code on my website. After the fix, reload the page: Checks then reads No problems found. Click Turn off the inspector on this site when you are done.

Why it matters

• The widget drops a field or tag it cannot use, without telling your visitor. The check names the field and the reason, so your developer knows where to look.
• The inspector reads the token only in the page. The token and its signature are never shown, stored or sent anywhere.
• The same checks also flag low contrast, a covered launcher and a widget language that differs from the page.
• To see the widget's raw data and timing, use the DevTools panel from lesson 9.