Accessing Help Scout Data in a React App or using the JavaScript SDK

This guide will provide you with the necessary information to access Help Scout data using the useHelpScoutContext() hook and <HelpScoutContextProvider> component from the UI Kit in a React application, as well as the more general HelpScout.getApplicationContext() and HelpScout.watchApplicationContext() methods from the JavaScript SDK.

Not using JavaScript? Check this guide instead.

Prerequisites

Ensure that you have completed the Getting Started Guide and set up a Help Scout App. If you’re building a React application, make sure to also have the @helpscout/ui-kit package installed.

Using the UI Kit’s Context Provider in a React App

While you can wrap any component with the <HelpScoutContextProvider> component, in the following example we are wrapping the root component. By doing this in your main.tsx file where the root of your React application is rendered, you ensure that all components in your app can access the context. However, the provider can be used at any level where its context is required by a child component.

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import { HelpScoutContextProvider } from "@helpscout/ui-kit";

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <HelpScoutContextProvider>
      <App />
    </HelpScoutContextProvider>
  </React.StrictMode>
);

Now that the <HelpScoutContextProvider> is set up, you can use the useHelpScoutContext() hook within your components to access Help Scout context data. This hook returns an object containing the following properties: company, conversation, customer, mailbox, and user. You can find the full details about these objects here.

Here’s an example of how to use the useHelpScoutContext() hook in your App.tsx file:

import { DefaultStyle, Heading, useHelpScoutContext } from "@helpscout/ui-kit";

function App() {
  const { user } = useHelpScoutContext();
  return (
    <div className="App">
      <DefaultStyle />
      <Heading level="h1">Hi {user?.firstName || "there"} 👋</Heading>
    </div>
  );
}

export default App;

In the example above, the useHelpScoutContext() hook is used to access the user property from the Help Scout context. The user’s first name is then displayed in a <Heading> component.

For more detailed information on using Providers, see our UI Kit Providers guide.

Getting Data from Help Scout with JavaScript SDK

For non-React applications or for more granular control, the JavaScript SDK provides the HelpScout.getApplicationContext() and HelpScout.watchApplicationContext() methods. The first fetches contextual information from the current Help Scout environment, such as company, conversation, customer, mailbox, and user details. The second listens to changes in this contextual information.

Fetching context data

To fetch context data on load, simply call the getApplicationContext() method in your app. This method returns a Promise that resolves with an object containing the aforementioned properties.

You can find the full details about these objects here.

Here’s an example of how to use getApplicationContext():

import HelpScout from '@helpscout/javascript-sdk';

HelpScout.getApplicationContext().then((context) => {
  console.log('Help Scout Context:', context);
});

You can access specific properties of the context object by using dot notation or destructuring assignment. Here are some examples:

Accessing the user’s first name

HelpScout.getApplicationContext().then(({ user }) => {
  console.log('User First Name:', user?.firstName);
});

Accessing the customer’s email

HelpScout.getApplicationContext().then(({ customer }) => {
  console.log('Customer Email:', customer?.emails?.[0]?.value);
});

Accessing the conversation subject

HelpScout.getApplicationContext().then(({ conversation }) => {
  console.log('Conversation Subject:', conversation?.subject);
});

Handling Errors

Since getApplicationContext() returns a Promise, you can use the .catch() method to handle errors:

HelpScout.getApplicationContext()
  .then((context) => {
    console.log('Help Scout Context:', context);
  })
  .catch((error) => {
    console.error('Error fetching Help Scout Context:', error);
  });

Listening to changes in context data

To listen to changes in the context data, call the watchApplicationContext() method passing a listener function as the param.

Here is an example of how it can be used in your application:

import HelpScout from '@helpscout/javascript-sdk';

HelpScout.watchApplicationContext(context => {
  console.log('Help Scout Context was changed to:', context)
});

Deep Dive into Context Objects

After you’ve familiarized yourself with the examples above, we encourage you to dive deeper into the full details of the different context objects. Understanding these objects and their properties will enable you to build more powerful and customized integrations with Help Scout. Don’t hesitate to explore the comprehensive documentation for each object:

By leveraging the richness of these objects, you can unlock the full potential of the Help Scout JavaScript SDK and React UI KIt to create exceptional experiences for your users. Get started now and discover the possibilities!

↑Back to top
© Help Scout 2024