Migrating Your Legacy Dynamic Apps to the App Developer Platform

This guide will provide you with the necessary information to migrate your legacy custom Dynamic apps.

We encourage you to make use of the powerful new features provided by the JavaScript SDK and the user-friendly React UI Kit. However, we acknowledge that you might prefer a gradual approach, making only the essential changes necessary for a smooth app migration. This guide is dedicated to assisting you in doing exactly that!

Getting Started

Create a New Custom 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: Enter the name for your app — You will not be able to use the exact same one
   • 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 the secret key of your web app — If your app is validating the request 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.

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 your app in the sidebar.

Migration

Each of the items below may or may not be necessary depending on your app.

Help Scout Data

If your app relies on the data provided in the body of the request to your Callback URL, you will need to update it to get this data from either:

• The JavaScript SDK, if you are using JavaScript, as per this guide or
• The data provided in the query params of the request, in combination with the Help Scout API, as per this guide.

CORS

Because we changed the way we render the app content on the Help Scout interface to render inside of an iframe, you may need to tweak your web server’s HTTP response headers:

• The “X-Frame-Options” header should not be used.
• If set, the “frame-ancestors” directive in the Content-Security-Policy header should include Help Scout’s domain (https://secure.helpscout.net).

You will know if any of these apply to you if, when trying to load your new app, you see an error similar to these on your console:

Refused to frame '{your domain}' because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'self'". or Refused to display '{your callback URL}' in a frame because it set 'X-Frame-Options' to 'sameorigin'.

Signature Validation

If your app is using signature validation, you will need to change it to:

1. Get the signature from the X-HelpScout-Signature query parameter (instead of a header).
2. Validate it using the remaining request’s query parameters.

More information can be found on this guide.

As always, if you have any questions or need assistance, we’re here to help. Happy coding!