Getting Started

Apps empower you to create Mailbox sidebar extensions, making it possible to display your app’s content within an iframe in the conversation view sidebar. While you have the freedom to use any language, platform, or library to build your app, we also offer a JavaScript SDK and a React UI Kit to streamline your development process.

The sections below will guide you through setting up your first App 🚀

Create App

Building your sidebar app is flexible; it can be crafted using any language, library, or framework of your choosing. The subsequent sections illustrate different methods for creating a JavaScript app. These methods include utilizing our provided app template and manually setting up an app, with or without the use of Vite.

Prerequisites 

The steps below will focus on building a JavaScript web app using our SDK. As a result, the following steps assume some familiarity with Node.js and npm.

Quick setup with App template

Get started quickly with the React-based app template. This template comes with our JavaScript SDK and UI Kit pre-installed. Simply open the GitHub repo and click the “Use this template” button.

GitHub's Use App Template button

This template has everything to get you started, including sample code showcasing some of the JavaScript SDK and UI Kit features.  Once you’ve cloned your copy of the template locally, you can get started by installing the npm packages and starting the server:

npm install
npm run watch

⏭️ Now that you have the app template running locally, skip down to the Help Scout App setup instructions to add the app to the sidebar.

Manual setup

Vite project setup

If you prefer to start from scratch or use a different framework, we recommend using Vite to set up your JavaScript/TypeScript project. Follow their Getting Started Guide for a quick start and skip down to the Install Help Scout packages section once you have it set up.

ℹ️ Note: SSL is required for all Apps so you’ll need to configure your Vite site with an SSL. We recommend using the vite-plugin-mkcert or @vitejs/plugin-basic-ssl Vite plugin.

Manual npm setup

We strongly recommend using one of the previous options (App Template or Vite) for a quicker and smoother setup. A manual setup of an npm web app may require numerous dependencies and configurations, which are beyond the scope of this document. However, if you still prefer a manual setup, follow these initial steps to create an npm package:

  1. Create a new directory for your new application and navigate into it:

    mkdir myawesomeapp
cd myawesomeapp

  2. Initialize npm to create the package.json  file for your app:

   npm init

Follow the prompts to fill out the details about your project.

💡 Tip: You can instead use npm init -y  to skip the questionnaire

Keep in mind that you’ll need to configure the web app further, which involves installing and setting up various dependencies. The specifics of this process will depend on your chosen stack and requirements.

Install packages

If you didn’t use the app template linked above, you’ll need to install the npm packages:

  1. Install the JavaScript SDK:

    npm install @helpscout/javascript-sdk

  2. Install the UI Kit

    npm install @helpscout/ui-kit

Implement your App

  1. To implement a demo app with some of the available features, create or edit the App.tsx  or App.jsx  file to read:

    import React from "react";
import HelpScout from "@helpscout/javascript-sdk";
import { DefaultStyle, Heading, useSetAppHeight } from "@helpscout/ui-kit";
import { useEffect, useState } from "react";

function App() {
  const appRef = useSetAppHeight();

  const [userFirstName, setUserFirstName] = useState("there");

  useEffect(() => {
    HelpScout.getApplicationContext().then(({ user }) =>
      setUserFirstName(user?.firstName || "there")
    );
  }, []);
   
  return (
    <div className="App" ref={appRef}>
      <DefaultStyle />
      <Heading level="h1">Hi {userFirstName}! 👋</Heading>
    </div>
  );
}

export default App;

  2. Start the app on a network available host

💡 Tip: If you are using Vite, you can do that by running npm run build && npm run preview -- --host. Be sure to use one of the Network URLs (not the Local URL) as your callback URL.

Install App

  1. Log into your Help Scout account as an administrator or account owner.
  2. Head to Manage > Apps  in the navigation bar.
  3. Click the “Create” button (on the top of the page).
  4. Click the “Create App” button (on the left sidebar).
  5. Complete the form using the following as a guide:
    • App Name: My Awesome App
    • Callback URL: Enter the URL of your web app — The URL host has to be network available (localhost or 127.0.0.1 will not work)
    • Secret Key: Enter any value — If your app is validating the header signature, this is the key that is used to generate it
    • Mailboxes: Select the mailboxes where this app should appear 
  6. Click the “Save” button.

Create Custom App Page

Access App

Once you’ve created your app, you can easily access it within Help Scout’s conversation sidebar. Follow the steps below to view your new app:

  1. In the navigation menu, click on “Mailboxes” and select one of the mailboxes you associated with your app during its creation.
  2. Open a conversation within the chosen mailbox.
  3. Locate “My Awesome App” in the sidebar.

💡 Tip: You can drag the app to your desired position!

App Sidebar View

With your app now integrated into Help Scout, your team can enjoy a streamlined workflow and access valuable information without leaving the conversation view.

↑Back to top
© Help Scout 2023