> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Initial Help Scout configuration

Before your Ada team can enable the Help Scout integration, complete the following prerequisites in your Help Scout instance. This guide assumes an active Help Scout account with at least one mailbox. Once finished, share the collected information with your Ada representative.

> **Info**
>
> Help Scout's UI labels these **Inboxes** in the navigation menu but uses **Mailbox** in field names and API references — they refer to the same entity. Throughout these docs, **Mailbox ID** is the value you enter into the handoff block.

## Create a mailbox for Ada conversations

Conversations handed off from Ada are created in a specific mailbox. A dedicated mailbox for Ada handoffs is recommended so they can be routed and reported on separately.

**To create the mailbox:**

1. In Help Scout, navigate to **Manage → Inboxes** and create a new inbox (for example, `Ada Handoffs`).
2. Open the new inbox and copy its **Mailbox ID** from the URL — it is the numeric value at the end (for example, `321091` in `.../inboxes/321091`).
   Save this ID; you enter it into the handoff block in Ada later.
3. Under the inbox's **Default Settings**, set the **Default Assignee** to **Person Replying** and the **Default Status** to **Active**.

## Create an OAuth2 app for Ada

Ada authenticates to the Help Scout API using OAuth2 client credentials. Create a dedicated app for Ada and share its **App ID** and **App Secret** with your Ada team.

**To create the OAuth2 app:**

1. In Help Scout, navigate to **Your Profile → My Apps**.
2. Click **Create My App**.
3. Enter a name (for example, `Ada Integration`) and set the **Redirection URL** to your AI Agent's URL (for example, `https://<agent-handle>.ada.support`).
4. Click **Create**.
5. Copy the **App ID** and **App Secret**.
   The App Secret is shown only once on creation, so save it somewhere safe. You share both with your Ada team.

> **Note**
>
> If you are connecting multiple AI Agents to the same Help Scout instance, you can create one OAuth app and reuse the same App ID and App Secret across all of them. Similarly, one Help Scout webhook per mailbox covers every AI Agent routing handoffs to that mailbox — a separate OAuth app or webhook per AI Agent is not required.

## Create a webhook for Ada

Help Scout notifies Ada of agent replies and conversation status changes through a webhook.

**To create the webhook:**

1. In Help Scout, navigate to **Manage → Apps → Webhooks**.
2. Click **Create Webhook**.
3. Set the **Label** to `Ada Integration`.
4. Set the **Callback URL** based on the AI Agent's cluster:
   * **US & CA:** `https://solutions.ada.support/messaging-connectors/helpscout/webhooks/helpscout`
   * **EU:** `https://solutions.eu.ada.support/messaging-connectors/helpscout/webhooks/helpscout`
5. For the **Secret Key**, generate a strong random value (32 or more characters).
   Save it; you share this with your Ada team as the Help Scout webhook signing secret.
6. Under **Events**, subscribe to both **Conversation Agent Reply** and **Conversation Status Updated**.
7. Under **Inbox**, select the Ada mailbox created above so only those events fire the webhook.
8. Click **Save**, then set the webhook **Status** to **Active**.

## Share with your Ada team

Once the prerequisites above are complete, share the following with your Ada representative securely — not in a shared channel.

1. **Help Scout App ID**
2. **Help Scout App Secret**
3. **Help Scout webhook signing secret** (the **Secret Key** entered when creating the webhook)

Keep the **Mailbox ID** available as well — it is needed when the handoff block is configured in Ada. The Mailbox ID is not a secret and is safe to share.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).