HandoffsHelp Scout

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.

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.

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 .