Getting Started

Apps allow you to create Inbox sidebar extensions which allows you to render your app’s URL within an iframe in the sidebar of the conversation view. Although you can use any language, platform, or library to build your app, we offer a JavaScript SDK and a React UI Kit for your convenience.

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

Create App

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.

Project setup

Note: Apps created using Create React App are currently not supported.

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.

This template has everything to get you started, including sample code showcasing some of the JavaScript SDK methods and UI Kit components.  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 start

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

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: An SSL is required for all Apps so you’ll need to configure your Vite site with an SSL. We recommend using the @vitejs/plugin-basic-ssl Vite plugin.

Manual 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

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

1. Install the UI Kit

  npm install @helpscout/ui-kit

Implement your App

1. 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 } from "@helpscout/ui-kit";
  import { useEffect, useState } from "react";

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

    useEffect(() => {
      HelpScout.getApplicationContext().then(({ user }) =>
        setUserFirstName(user?.firstName || "there")
      );
    }, []);

    return (
      <div className="App">
        <DefaultStyle />
        <Heading level="h4">Hi {userFirstName}! 👋</Heading>
      </div>
    );
  }

  export default App;

1. Start the server:

  npm start

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 — If you’re using the app template or Vite, you can set this to https://127.0.0.1:5173/
   • Secret Key: Enter any value
   • Mailboxes: Select the mailboxes where this app should appear 
6. Click the “Save” button.

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!

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