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.

​window.Pylon("show")

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

​window.Pylon("hide")

Closes the chat window.

​window.Pylon("onShow")

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.

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

​window.Pylon("onHide")

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.

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

​window.Pylon("hideChatBubble")

Hides the chat bubble. Useful for hiding it in situations where it’s inappropriate or it’s blocking something underneath (ie an open modal). Does not override the “Show Chat Bubble” setting on the settings page.

​window.Pylon("showChatBubble")

Shows the chat bubble. Useful for hiding it in situations where it’s inappropriate or it’s blocking something underneath (ie an open modal). Does not override the “Show Chat Bubble” setting on the settings page.

​window.Pylon("setTheme", "string")

Sets the chat window theme based on the provided argument. Valid values are light and dark, e.g. window.Pylon("setTheme", "light"). You can set your light mode and dark mode color palettes on the Settings page.

​window.Pylon("onChangeUnreadMessagesCount")

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.

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

​window.Pylon("setNewIssueCustomFields")

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. Fields with null or undefined values are ignored.

You must first create the corresponding custom fields inside of Pylon.

Be sure to use the custom field slug, not the label!

Example:

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

You can find the slug value on the custom fields page next to the custom field.

window.Pylon("setTicketFormFields")

Pass in an object field slugs to their values. Ticket forms in the Chat Widget will have these values set as default values.

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

Example:

window.Pylon("setTicketFormFields", { subject: "I need help on Pylon because..." });

You can find the slug value on the custom fields page next to the custom field.

window.Pylon("setVisibleTicketForms")

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.

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.

Example:

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.

window.Pylon("showNewMessage", "string")

Pass in a message to prepopulate 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.

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.

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});

window.Pylon("showTicketForm", "string")

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

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")

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

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"

https://support.usepylon.com/articles/1234567899-how-to

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