JavaScript SDK Reference

The Help Scout JavaScript SDK makes it easy to build apps, get context data from Help Scout, listen to context data changes, and interact with Help Scout’s features. This reference guide provides an overview of the available methods and their usage.

Get Application Context

getApplicationContext(): Promise<Context>

Returns a Promise that resolves to an object of the Context type, which contains information about the current Help Scout environment. The Context object usually has the following properties:

• company: An object containing information about the current company.
• conversation: An object containing information about the current conversation.
• customer: An object containing information about the current customer.
• mailbox: An object containing information about the current mailbox.
• user: An object containing information about the current user.

Example: Get Help Scout’s context

import HelpScout from '@helpscout/javascript-sdk';

HelpScout.getApplicationContext().then((context) => {
  console.log('Help Scout Context:', context);
});

ℹ️ Note: Want to dive deeper into the data structure returned by getApplicationContext()? Head over to our Context Object Documentation for a comprehensive breakdown of each property in the context object and how you can use them to enrich your app’s functionality.

📚 Learn More: Interested in diving deeper into fetching data? Visit our comprehensive guide on Getting Data from Help Scout with JavaScript. It’s packed with numerous examples to assist you in mastering context retrieval.

Watch Application Context

watchApplicationContext((context: Context) => void) : void

Adds the provided callback as a listener to context data changes.

Example: Listen to changes in Help Scout’s context

import HelpScout from '@helpscout/javascript-sdk';

HelpScout.watchApplicationContext(context => {
  console.log('Help Scout Context was changed to:', context)
});

Set Clipboard Text

setClipboardText(text: string, successMessage = 'Text copied'): void

Sets the user’s clipboard text. Since apps are rendered in an iframe, this method allows apps to access clipboard functionality that is usually restricted within iframes.

Example: Set the user’s clipboard to “Copy this text!”

import HelpScout from '@helpscout/javascript-sdk';

HelpScout.setClipboardText('Copy this text!')

Set App’s Height

setAppHeight(height: number): void

Sets the height of the iframe containing the app. This method is to communicate the content height to Help Scout, allowing Help Scout to determine the appropriate iframe height.

Example: Set the app’s height to a specific number

import HelpScout from '@helpscout/javascript-sdk';

HelpScout.setAppHeight(200)

Example: Set the app’s height dynamically based on the content height

import HelpScout from '@helpscout/javascript-sdk';

const appElement = document.getElementById('root') as HTMLElement;

const handleResize = () => {
  const height = appElement.clientHeight || 300;
  HelpScout.setAppHeight(height);
};

const resizeObserver = new ResizeObserver(handleResize);
resizeObserver.observe(appElement);

In this example, we first get a reference to the element we want to observe using const appElement = document.getElementById('app') as HTMLElement;. Then, we define a handleResize function that gets the element’s height and calls HelpScout.setAppHeight() with the height value.

Next, we create a ResizeObserver instance and pass our handleResize function to it. We start observing the element using resizeObserver.observe(appElement);.

Show Notification

showNotification(type: NotificationType, text: string, options: NotificationOptions | ConfirmNotificationOptions = {}): void

Example: Show a success notification with the text “Order refunded”

import HelpScout from '@helpscout/javascript-sdk';

HelpScout.showNotification('SUCCESS', 'Order refunded')

Displays a notification within the Help Scout interface.

Get App Styles

getAppStyles(): Promise<string>

Returns a Promise that resolves to a string containing CSS rules generated by Help Scout. Currently, this string includes styles for font families and font sizes used in the Help Scout interface. However, this function is designed to evolve over time to include additional styles for colors and other UI elements. Use getAppStyles to ensure consistent font styling when creating an application without using Help Scout’s React UI Kit.

Example: Apply Help Scout’s styles in your application

import HelpScout from '@helpscout/javascript-sdk';

async function applyStyles() {
  // Get the styles from Help Scout
  const styles = await HelpScout.getAppStyles();
  
  // Create a style element
  const styleElement = document.createElement('style');
  
  // Set the innerHTML of the style element to the styles
  styleElement.innerHTML = styles;
  
  // Append the style element to the head of the document
  document.head.appendChild(styleElement);
}

applyStyles();

This function creates a new style element, sets its content to the styles returned by getAppStyles(), and appends the style element to the document’s head. This ensures that the Help Scout styles are applied to your application.

📚 Learn More: Interested in styling your application? Check our comprehensive guide on Using Help Scout Fonts and Styles. This guide provides you with all the information you need to style your app consistently with the Help Scout interface. This includes leveraging the getAppStyles() method and understanding how to implement it effectively. Additionally, the guide covers how you can utilize the React UI Kit to apply consistent styles without using this method directly.

Open Side Panel

openSidePanel(contentUrl: string): void

Initiates the display of a Side Panel in the Help Scout interface. The Side Panel provides a dedicated space, opening from the right side, which allows apps to display richer content, show detailed information, or collect input from the user.

Example: Open a side panel with expanded content from your app

import HelpScout from '@helpscout/javascript-sdk';

HelpScout.openSidePanel('https://myawesomehelpscoutapp.com/sidepanel');

In this example, a specific page from the app is presented in the Help Scout’s Side Panel. The Side Panel is versatile, suitable for showcasing details like e-commerce order overviews, billing/shipping information, or even interactive user forms.

📚 Learn More: To harness the power of the Side Panel, allowing for richer interactions with your users, visit our detailed guide on Working with the Side Panel. It offers insights into effectively leveraging this feature to maximize user engagement and provide a seamless experience.