JavaScript SDK Reference

The Help Scout JavaScript SDK makes it easy to build apps, get context data from Help Scout, 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 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);
});

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.

Argument Type Description
text string The text to be copied to the clipboard.
successMessage string (optional) The message to be displayed after the text is successfully copied. Defaults to ‘Text copied’.

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.

Argument Type Description
height number The desired height of the iframe in pixels.

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.

Argument Type Description
type NotificationType The type of the notification. Accepts one of the following values: 'CONFIRM', 'ERROR', 'MESSAGE', 'SUCCESS', 'WARNING'.
text string The text to be displayed in the notification.