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. |