Common Issues

The chat doesn't show up!

This can happen for a variety of reasons. These can range from not finishing the setup instructions, to deep configuration issues.

Here's some common causes to go through in order, or skip to a section if the cause is known:

1. Check that the chat is enabled in the settings page. It's very easy to miss the toggle and forget to hit "Save".

2. Make sure all required fields in window.pylon.chat_settings are set and that the app_id field matches the value in the settings page.

   window.pylon.chat_settings = {
     // REQUIRED FIELDS
     app_id: "YOUR_APP_ID",
     email: "YOUR_EMAIL",
     name: "YOUR_NAME",
   
     // REQUIRED ONLY IF HMAC IDENTITY VERIFICATION IS ENABLED
     email_hash: "YOUR_EMAIL_HASH",
   
     // OPTIONAL FIELDS
     avatar_url: "YOUR_AVATAR_URL",
     account_id: "057a3564-fc1b-4224-9292-dcf718653452",
     account_external_id: "ab38e36b-3e28-4e2d-b976-6282735b77eb"
   }

   1. Call window.pylon.chat_settings in the browser console to verify that these settings are actually being applied.

   2. Email and name are frequently forgotten or swapped on accident.

   3. If "Require Identity Verification" is enabled in the settings page, then the window.pylon.chat_settings.email_hash field becomes required

3. Check if the content is being blocked by the Content Security Policy (CSP) in the application. These errors should be visible in the console.

   1. *.usepylon.com, *.posthog.com, and *.pusher.com are required in the connect-src and script-src directives. If the CSP has additional directives such as img-src then some content in the chat widget may not load, but the chat bubble itself should still show.

4. See how much content is being loaded by checking the embedded scripts

   1. Inspect the page to see if any chat widget content is loaded.

      1. The chat source loads within the head of an iframe id="pylon-frame" within the body of the HTML document.

      2. Afterwards, the chat widget itself renders within a div id=pylon-chat within the body of the top level HTML document

      3. If all expected chat widget content to be rendered is nested inside of pylon-chat, then check for any conflicting styles being applied from the parent application.

Debugging can be tricky and may require either someone more familiar with the chat or someone with engineering expertise.

New responses from Slack aren't showing up in the chat

1. Check that *.pusher.com is allowed by the CSP. Pusher is used for sending and receiving some message updates in the chat.

2. Sometimes we aren't able to sync messages properly if the chat support slack channel is set to an existing account's slack channel. Try changing the chat support channel to a different channel.

3. Another possible cause is that an invalid account_id is set within window.pylon.chat_settings. The account_id field represents a Pylon account ID and not an ID from an external provider. If an external ID is needed as a reference, then the account_external_id field can be used.

New responses aren't showing up as unread in the chat

If the slack user is the same between our dashboard and the chat widget, then replying from the Pylon dashboard will immediately mark messages as read from both sides, and the unread message count callback will not fire.

A separate user is recommended for testing so that this issue isn't encountered, and to also more closely resemble the end-user experience.

Fonts or styles aren't being applied

Check if these are being blocked by the CSP. Fonts are loaded in a stylesheet from widget.usepylon.com.

The chat widget domain widget.usepylon.com may need to be added to the style-src and font-src CSP directives.

The window.Pylon JavaScript API doesn't do anything

You may be trying to test the chat widget integration in your app locally or in development mode which can have different behavior from production.

A common cause of issues with this when using React is when the embed script is added to the document through a useEffect instead of the recommended way of placing the script directly within the HTML file. Strict mode in development mode can cause the chat widget to be inserted twice and can cause binding issues that prevent window.Pylon from working.

Custom field values aren't being set with window.Pylon("setNewIssueCustomFields")

For example, if you have an issue custom field that is:

• Field Type "Select"

• Field Name "My Selectable Field"

• Options "Option 1", "Option 2", and "Option 3"

Assuming that no slugs have been edited, then setting this custom field to "Option 1" for a new issue from Widget chat would look like

window.Pylon("setNewIssueCustomFields", { "my_selectable_field": "option_1" });

Navigating to a new page removes the chat widget

If using the chat widget within a multi-page app (MPA):

• Check that the embed script is in each HTML file served in the app

If using the chat widget within a single-page app (SPA):

• See if there is any lifecycle behavior (e.g. useEffect in React) that is interfering with the chat widget

If using server-side rendering (SSR) or static-site generation (SSG):

• You may have to dig into your app's hydration process to see if anything is preventing the chat widget from showing