> For the complete documentation index, see [llms.txt](https://docs.usepylon.com/pylon-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usepylon.com/pylon-docs/chat-widget/javascript-api.md).

# JavaScript API

Available API methods to programmatically interface with the chat widget

We expose some functions in the Frontend to programmatically control the Chat window.

{% hint style="info" %}
Calls made before the widget finishes loading are queued and run once it loads. Every call requires a valid `window.pylon.chat_settings` with `app_id`, `email`, and `name` (see [Chat Setup](/pylon-docs/chat-widget/chat-setup.md)).
{% endhint %}

## `window.Pylon("show")` <a href="#window-pylon-show" id="window-pylon-show"></a>

Opens the chat window. Useful for programmatically triggering the chat window from an explicit support flow or button on your site.

## `window.Pylon("hide")` <a href="#window-pylon-hide" id="window-pylon-hide"></a>

Closes the chat window.

## `window.Pylon("onShow")` <a href="#window-pylon-onshow" id="window-pylon-onshow"></a>

Pass in a callback function that is called when the chat is shown. Useful for managing state of the chat window. If you pass in `null` as the callback function, the existing callback is removed.

```javascript
window.Pylon("onShow", function () {
  console.log("show chat!");
});
```

## `window.Pylon("onHide")` <a href="#window-pylon-onhide" id="window-pylon-onhide"></a>

Pass in a callback function that is called when the chat is hidden. Useful for managing state of the chat window. If you pass in `null` as the callback function, the existing callback is removed.

```javascript
window.Pylon("onHide", function () {
  console.log("hide chat!");
});
```

## `window.Pylon("hideChatBubble")` <a href="#window-pylon-hidechatbubble" id="window-pylon-hidechatbubble"></a>

Hides the chat bubble (and closes the chat window if it's open). Useful for hiding it in situations where it’s inappropriate or it’s blocking something underneath (ie an open modal).

This has no effect when **Show Chat Bubble** is turned off in the widget's settings.

## `window.Pylon("showChatBubble")` <a href="#window-pylon-showchatbubble" id="window-pylon-showchatbubble"></a>

Shows the chat bubble again after you've hidden it with `hideChatBubble`.

This has no effect when **Show Chat Bubble** is turned off in the widget's settings. In that case, use `show` to open the chat window directly.

## `window.Pylon("onShowChatBubble")` / `window.Pylon("onHideChatBubble")` <a href="#window-pylon-onshowchatbubble" id="window-pylon-onshowchatbubble"></a>

Pass in a callback function that is called when the chat bubble is shown or hidden. Pass in `null` to remove the existing callback.

```javascript
window.Pylon("onShowChatBubble", function () {
  console.log("bubble shown");
});
window.Pylon("onHideChatBubble", function () {
  console.log("bubble hidden");
});
```

## `window.Pylon("setTheme", "string")` <a href="#window-pylon-settheme" id="window-pylon-settheme"></a>

Sets the chat window theme based on the provided argument. Valid values are `light` and `dark`, e.g. `window.Pylon("setTheme", "dark")`. The widget uses light mode until you call this, and remembers the choice in the user's browser. You can set your light mode and dark mode palettes on the widget's **Styling** tab (see [Styling](/pylon-docs/chat-widget/styling.md)).

## `window.Pylon("onChangeUnreadMessagesCount")` <a href="#window-pylon-onchangeunreadmessagescount" id="window-pylon-onchangeunreadmessagescount"></a>

Pass in a callback function that is called immediately and when the unread message count changes. If you pass in `null` as the callback function, the existing callback is removed.

```javascript
window.Pylon("onChangeUnreadMessagesCount", function (unreadCount) {
  console.log("unread changed!", unreadCount);
});
```

## `window.Pylon("onPopupMessageVisibilityChange")` <a href="#window-pylon-onpopupmessagevisibilitychange" id="window-pylon-onpopupmessagevisibilitychange"></a>

Pass in a callback function that is called with `true` or `false` when the preview of a new reply above the chat bubble appears or disappears. Pass in `null` to remove the existing callback.

```javascript
window.Pylon("onPopupMessageVisibilityChange", function (isShowing) {
  console.log("reply preview showing:", isShowing);
});
```

## `window.Pylon("onPopupSurveyVisibilityChange")` <a href="#window-pylon-onpopupsurveyvisibilitychange" id="window-pylon-onpopupsurveyvisibilitychange"></a>

Pass in a callback function that is called with `true` or `false` when a popup survey appears or disappears. Pass in `null` to remove the existing callback.

```javascript
window.Pylon("onPopupSurveyVisibilityChange", function (isShowing) {
  console.log("survey showing:", isShowing);
});
```

## `window.Pylon("onSurveySubmitted")` <a href="#window-pylon-onsurveysubmitted" id="window-pylon-onsurveysubmitted"></a>

Pass in a callback function that is called when the user submits a popup survey. It receives an object with `surveyType` (`CSAT`, `NPS`, or `GENERIC`), `score`, and, if the user left one, `feedback`. Pass in `null` to remove the existing callback.

```javascript
window.Pylon("onSurveySubmitted", function ({ surveyType, score, feedback }) {
  console.log("survey submitted", surveyType, score, feedback);
});
```

## `window.Pylon("setNewIssueCustomFields")` <a href="#window-pylon-setnewissuecustomfields" id="window-pylon-setnewissuecustomfields"></a>

Pass in an object of custom field slugs to their values. New issues created through the Chat Widget messaging will have these custom fields values set. Values can be strings, numbers, or booleans. Fields with `null` or `undefined` values are ignored.

You must first create the corresponding custom fields [inside of Pylon](https://app.usepylon.com/settings/issue-custom-fields).

{% hint style="info" %}
Be sure to use the custom field slug, not the label!
{% endhint %}

Example:

```javascript
window.Pylon("setNewIssueCustomFields", { user_id: "abc123" });
```

You can find the slug value on the custom fields [page](https://app.usepylon.com/settings/issue-custom-fields) next to the custom field.

<figure><img src="https://mintlify.s3-us-west-1.amazonaws.com/pylon/images/chat-slug.png" alt=""><figcaption></figcaption></figure>

## `window.Pylon("setTicketFormFields")` <a href="#window-pylon-setticketformfields" id="window-pylon-setticketformfields"></a>

Pass in an object of field slugs to their values. Ticket forms in the Chat Widget will have these values set as default values. For multi-select fields, pass an array of values.

Note that the passed object will apply to all ticket forms. Superfluous and/or invalid fields will be ignored.

Example:

```javascript
window.Pylon("setTicketFormFields", {
  subject: "I need help on Pylon because...",
  affected_products: ["billing", "reporting"],
});
```

You can find the slug value on the custom fields [page](https://app.usepylon.com/settings/issue-custom-fields) next to the custom field.

<figure><img src="https://mintlify.s3-us-west-1.amazonaws.com/pylon/images/chat-slug.png" alt=""><figcaption></figcaption></figure>

## `window.Pylon("setVisibleTicketForms")` <a href="#window-pylon-setvisibleticketforms" id="window-pylon-setvisibleticketforms"></a>

Pass in an array of ticket form slug strings to make those ticket forms visible in the Chat Widget. Pass in `null` to revert back the originally visible ticket forms.

{% hint style="info" %}
Only ticket forms that are selected in a Form Set within the Chat Widget's settings are allowed. In the example below, the ticket forms with the slugs `test-ticket-form-1` and `test-ticket-form-2` will not become visible unless they are also selected as part of any Form Set within the Chat Widget's settings.
{% endhint %}

Example:

```javascript
window.Pylon("setVisibleTicketForms", ["test-ticket-form-1", "test-ticket-form-2"]);
```

The ticket form slug can be found in the edit ticket form page under `Form Slug`.

<figure><img src="https://982123570-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9hXBoCTTNw5flARlUVJf%2Fuploads%2FSsodw5UjG5Nc2DhYSwM6%2FScreenshot%202025-12-01%20at%205.32.37%E2%80%AFPM.png?alt=media&amp;token=58eabf60-768d-467b-9547-a6479dbfce70" alt=""><figcaption></figcaption></figure>

## `window.Pylon("showNewMessage", "string")` <a href="#window-pylon-shownewmessage-string" id="window-pylon-shownewmessage-string"></a>

Opens a new conversation with a message prepopulated in the editor. For example, use this when a user runs into an error in your application and you want to prefill a message they can submit. Call it with no message to open a blank new conversation.

```javascript
window.Pylon("showNewMessage", "I'm experiencing an issue with syncing from Google Sheets to Email and could use some assistance");
```

Optionally, this string can also be HTML. For example, for rendering a link. Pass an optional argument indicating the message to be shown is HTML.

NOTE: Only specific HTML tags are supported: `<a>`, `<b>`, `<p>`, and `<i>`. If other tags are used, the editor may error.

```javascript
window.Pylon("showNewMessage", "I'm experiencing an issue with <a href='https://www.app.company.com/sync/123'>syncing</a> from Google Sheets to Email and could use some assistance", { isHtml: true});
```

To set custom fields on just this conversation, pass `customFields`. These are merged over any values set with [`setNewIssueCustomFields`](#window-pylon-setnewissuecustomfields).

```javascript
window.Pylon("showNewMessage", "Sync failed for workspace 123", {
  customFields: { workspace_id: "123" },
});
```

The message can be at most 2,500 characters. `showNewMessage` does nothing when the Chat module is turned off for the user.

## `window.Pylon("showIssue", "string")` <a href="#window-pylon-showissue" id="window-pylon-showissue"></a>

Opens the chat window to an existing conversation, by issue ID. Use it with `onActiveIssueChange` or `getCurrentIssue` to restore the conversation a user had open, for example after a page reload.

```javascript
window.Pylon("showIssue", "3f2b6c1e-8a4d-4c1b-9e2f-1a2b3c4d5e6f");
```

## `window.Pylon("getCurrentIssue")` <a href="#window-pylon-getcurrentissue" id="window-pylon-getcurrentissue"></a>

Returns the conversation open in the chat window as `{ issueID, issueNumber }`, or `null` if none is open. Unlike other methods, this returns a value directly, so call it after the widget has loaded (calls queued before then return nothing).

```javascript
const current = window.Pylon("getCurrentIssue");
```

## `window.Pylon("onActiveIssueChange")` <a href="#window-pylon-onactiveissuechange" id="window-pylon-onactiveissuechange"></a>

Pass in a callback function that is called when the open conversation changes. It receives `{ issueID, issueNumber }`, or `null` when the user leaves the conversation. If a conversation is already open when you register the callback, it is called right away. Pass in `null` to remove the existing callback.

```javascript
window.Pylon("onActiveIssueChange", function (issue) {
  if (issue) {
    sessionStorage.setItem("pylonIssueID", issue.issueID);
  } else {
    sessionStorage.removeItem("pylonIssueID");
  }
});

const savedIssueID = sessionStorage.getItem("pylonIssueID");
if (savedIssueID) {
  window.Pylon("showIssue", savedIssueID);
}
```

## `window.Pylon("showTicketForm", "string")` <a href="#window-pylon-showticketform-string" id="window-pylon-showticketform-string"></a>

Navigates the chat bubble to a specified ticket form, by ticket form slug.

```javascript
window.Pylon("showTicketForm", "test_ticket_form");
```

The ticket form slug can be found in the edit ticket form page under `Form Slug`.

## `window.Pylon("showKnowledgeBaseArticle", "string")` <a href="#window-pylon-showknowledgebasearticle-string" id="window-pylon-showknowledgebasearticle-string"></a>

Navigates the chat bubble to a specified knowledge base article, by article ID.

```javascript
window.Pylon("showKnowledgeBaseArticle", "123456789");
```

The article ID can be found in the URL of the public view of a knowledge base article, as the first set of numbers following `articles/`. In the following example, the identifier is "1234567899"

<figure><img src="https://982123570-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9hXBoCTTNw5flARlUVJf%2Fuploads%2F0kYoAV0QsGlxwPcWJu6e%2Fimage.png?alt=media&amp;token=dcb8a3bb-ca25-4c86-892a-170ac7c5a122" alt=""><figcaption><p>https://support.usepylon.com/articles/1234567899-how-to</p></figcaption></figure>

It can also be found in the article settings panel in the Pylon app, under the article slug input.

<figure><img src="https://982123570-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9hXBoCTTNw5flARlUVJf%2Fuploads%2Fbb2fdkXMVVgcvolEqaCe%2Fimage.png?alt=media&amp;token=3e2d18cb-f41a-4347-9a20-501eec91cb2e" alt="" width="375"><figcaption></figcaption></figure>

## `window.Pylon("setLocale", "string")` <a href="#window-pylon-setlocale-string" id="window-pylon-setlocale-string"></a>

Sets the widget's language and saves it as the user's preferred language. **This reloads the page** so the new language takes effect.

Supported values: `en`, `es`, `et`, `fr`, `de`, `it`, `ja`, `ko`, and `pt-br` (`pt` is treated as `pt-br`). The language must also be one of your organization's supported languages.

```javascript
window.Pylon("setLocale", "fr");
```

If you already know the user's language when the page loads, set `locale` in `chat_settings` instead (see [Chat Setup](/pylon-docs/chat-widget/chat-setup.md)). It avoids the reload and takes priority over the saved preference.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.usepylon.com/pylon-docs/chat-widget/javascript-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
