> ## Documentation Index
> Fetch the complete documentation index at: https://developers.opereit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the Help Scout connector

> Connect Opereit to Help Scout so agents can file carrier claims without leaving a conversation

The Opereit connector for Help Scout adds an **Opereit** card to the conversation sidebar. The card lists the claims linked to the conversation, and agents click **New claim** to file a carrier claim for a shipment without leaving Help Scout.

> [!NOTE]
>
> The connector is currently private. An administrator of your Help Scout
> account must set it up, on a plan that allows custom apps (Standard or Plus).
> You also need to work with your Opereit Product Manager, who gives you two
> values in step 3: the **Content URL** and the **Content signature key**.

> [!WARNING]
>
> The keys in this guide are secrets. Share them with your Opereit Product
> Manager only through a secure channel, such as your password manager. Never
> send them by email, chat or in a Help Scout conversation.

**1. Create an API key**

Follow the [API keys guide](https://developers.opereit.ai/guides/api-keys.md) to create an API key named
`Help Scout`. Keep the **Key ID** and **Key Password** at hand for step 3.

**2. Create the app that lets Opereit read the messages**

Opereit reads the messages of a conversation to find its shipments and
fill in the claim for you. For that, create an app in Help Scout. An
administrator does this once.

Click the **Settings** gear in the top bar, then **My Apps** in the
**Account** menu.

![Help Scout top bar with the Settings gear highlighted](https://mintcdn.com/opereit/fJuPhHqy6XJLUTwt/images/help-scout/settings-menu.png?fit=max\&auto=format\&n=fJuPhHqy6XJLUTwt\&q=85\&s=00a5f7035ba470bbb58a556191549463)

Click **Create App**.

![My apps page with the Create App button](https://mintcdn.com/opereit/fJuPhHqy6XJLUTwt/images/help-scout/my-apps.png?fit=max\&auto=format\&n=fJuPhHqy6XJLUTwt\&q=85\&s=18b2982d6f114e2873192becc828397d)

Set **App name** to `Opereit`. **Redirection URL** is required, but Opereit
doesn't use it. Enter any valid `https://` address, for example
`https://helpscout-module-production.up.railway.app`. Then click **Create**.

![Create Custom App dialog with the app name and the redirection URL filled in](https://mintcdn.com/opereit/fJuPhHqy6XJLUTwt/images/help-scout/create-custom-app.png?fit=max\&auto=format\&n=fJuPhHqy6XJLUTwt\&q=85\&s=f68c7bcce7e2d025e0abd1d7f925d69f)

Open the app you just created. Copy the **App ID** and the **App secret**
for step 3.

![Edit app page with the App ID and App secret hidden](https://mintcdn.com/opereit/fJuPhHqy6XJLUTwt/images/help-scout/edit-app-credentials.png?fit=max\&auto=format\&n=fJuPhHqy6XJLUTwt\&q=85\&s=d71345c11671192bfd47772ee48c6e8c)

> [!NOTE]
>
> Opereit reads conversations with the access of the person who created the
> app. Create it with a user who will stay in your team and keep access to
> the mailboxes that use Opereit. If that user is removed or loses access,
> Opereit can no longer read the conversations.

**3. Send the keys to Opereit and get the connection values**

Contact your Opereit Product Manager and send them, through a secure
channel:

* The **Key ID** and **Key Password** from step 1.
* The **App ID** and **App secret** from step 2.

In return, your Product Manager gives you two values that only Opereit can
create for your account:

* **Content URL**: the address of the connector for your account. It ends
  in `/load?connection=hsc_…`.
* **Content signature key**: the key that proves to Opereit that a request
  comes from your Help Scout.

Keep both for step 4.

**4. Add the Opereit app to your sidebar**

In Help Scout, open **Workspace**, then **Apps**, and click **Create**.

![Help Scout Apps page with the Create button](https://mintcdn.com/opereit/fJuPhHqy6XJLUTwt/images/help-scout/apps-directory.png?fit=max\&auto=format\&n=fJuPhHqy6XJLUTwt\&q=85\&s=404a9cc97c625678036c979cffd85e44)

Fill in the form:

| Field | Value |
| - | - |
| **App name** | `Opereit` |
| **Content URL** | The **Content URL** from step 3, exactly as you received it. |
| **Content signature key** | The **Content signature key** from step 3. |
| **Side Panel URLs** | `https://helpscout-module-production.up.railway.app/*`, including the `*` at the end. |

![Create an app form with the app name, Content URL, Content signature key and Side Panel URLs](https://mintcdn.com/opereit/fJuPhHqy6XJLUTwt/images/help-scout/create-sidebar-app.png?fit=max\&auto=format\&n=fJuPhHqy6XJLUTwt\&q=85\&s=331314f5b3b7a77cb97357bcf2da11bf)

Click **Save**. If Help Scout asks which mailboxes should show the app,
select the ones your team uses for shipping conversations.

**5. Start filing claims**

You're done. Open a conversation in one of those mailboxes and look for the
**Opereit** card in the right sidebar. If the conversation mentions a
shipment that already has a claim, the claim appears under **Claims for
this conversation**. Click **New claim** to open the claim form, filled in
with what Opereit can read from the conversation.

![Opereit card in the Help Scout sidebar with the claims for the conversation and a New claim button](https://mintcdn.com/opereit/fJuPhHqy6XJLUTwt/images/help-scout/sidebar-card.png?fit=max\&auto=format\&n=fJuPhHqy6XJLUTwt\&q=85\&s=2da6103ba13a2e091e4b9308551cfb4b)

## Troubleshooting

> [accordion] The Opereit card shows an error instead of the claims
>
> Help Scout and Opereit don't agree on the connection. Check that the
> **Content URL** is exactly the one you received, with nothing added or cut
> off, and that the **Content signature key** has no extra spaces. If both
> are right, contact your Opereit Product Manager.

> [accordion] The claim form isn't filled in, or linked claims don't show up
>
> Opereit may not be able to read the conversation. Check that the user who
> created the app in step 2 is still active and has access to the mailbox. If
> the **App ID** or the **App secret** changed, send the new values to your
> Opereit Product Manager.

> [accordion] An open claim already exists for this shipment
>
> Opereit allows one open claim per shipment, so **New claim** is disabled.
> Contact Opereit support if you need to fix the earlier claim.

> [accordion] Opereit rejects the connection
>
> The API key is wrong or has been revoked. Create a new key as described in
> the [API keys guide](https://developers.opereit.ai/guides/api-keys.md) and send the new **Key ID** and
> **Key Password** to your Opereit Product Manager.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.