> 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. # Configure the Help Scout handoff After you complete the [initial configuration](/docs/handoffs/help-scout/initial-configuration) and share your credentials, your Ada team sets up the backend integration. When setup is complete, the **Help Scout Utilities** app appears in **Config → Apps** in your AI Agent dashboard, and you can configure the handoff block. In Help Scout, each handoff creates a new conversation (email ticket) in the configured mailbox, and Ada bidirectionally relays text messages and attachments between the end user and the human agent. > **Info** > > Your Ada team will complete the backend integration setup. Contact your Ada representative to confirm when this step is finished before proceeding. ## Connect the Help Scout Utilities app Once your Ada team confirms setup is complete, the **Help Scout Utilities** app appears in your AI Agent's app list, ready to connect. **To connect the app:** 1. Navigate to **Config → Apps**, where the **Help Scout Utilities** app is now listed. 2. Click **Connect** to open the app's configuration form. 3. Click **Save**. ## Add the Help Scout Utilities block Each handoff creates a new conversation in the mailbox you specify and relays messages and attachments in both directions. **To add the Help Scout Utilities block:** 1. In your handoff answer, add the **Help Scout Utilities** block with action **Handoff to a human agent**. 2. The two required Ada ID fields are pre-populated by the block: * `ada_conversation_id` → `@oauth/conversation_id` * `ada_user_id` → `@oauth/end_user_id` 3. Fill in the required Help Scout routing fields: * **Mailbox ID** — the Help Scout mailbox the conversation is created in (provided in your initial configuration). * **Conversation Subject** — the subject line the agent sees on the Help Scout conversation. This can be a static string or a mapped AI Agent variable. 4. Optionally map AI Agent variables into any of the additional fields documented below. > **Note** > > Select the action labeled **Handoff to a human agent**, not **Handoff to a human agent (legacy)**. The legacy action runs the deprecated SunCo-based handoff and will be removed in a future release. ## Handoff input fields The Help Scout Utilities block accepts the following input fields. | Field | Required | Description | | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ada_conversation_id` | Yes | Conversation ID. Populated by `@oauth/conversation_id`. | | `ada_user_id` | Yes | End user ID. Populated by `@oauth/end_user_id`. | | `mailbox_id` | Yes | Help Scout Mailbox ID the conversation is created in (provided by the customer). | | `subject` | Yes | Conversation subject shown in Help Scout. | | `user_email` | No | End user email. Used to find or create the customer in Help Scout. Highly recommended so the agent sees a real contact instead of an anonymous customer. | | `user_phone` | No | End user phone number, attached to the Help Scout customer record. | | `user_first_name` | No | End user first name. | | `user_last_name` | No | End user last name. | | `tags` | No | Comma-separated tags to apply to the Help Scout conversation. Unknown tags are skipped; the handoff does not fail if invalid tags are passed. | | `first_message` | No | If set, shown to the agent as the first chat message; the Ada transcript is added as an internal note instead. If not set, the Ada transcript itself is shown as the first chat message. | | `note` | No | Optional internal note added to the conversation at creation. | | `keep_agent_conversation_open` | No | Enter the literal text `true` or `false` (or map a variable that resolves to one of those). If `true`, ends Ada's handoff without closing the Help Scout conversation. Defaults to `false`, which closes the conversation when the handoff ends. | | `agent_name_override` | No | Static display name shown in Ada for all agent messages — overrides the name fetched from the Help Scout user. Useful when a generic `Agent` or `Support` label is wanted. | > **Note** > > The Mailbox ID can be hardcoded for a single mailbox or mapped from an AI Agent variable for dynamic routing (for example, by language, product line, or customer tier). Each handoff can target a different mailbox. > **Note** > > If the same conversation hands off to Help Scout more than once — for example, the end user returns to the AI Agent after one handoff and then escalates again — only messages since the previous handoff ended are sent in the new conversation's transcript. Each Help Scout conversation contains only the context relevant to its own handoff. ## Meta-variables After a successful handoff, the integration writes the following meta-variables to the Ada end user. You can read these in conversation logic, scripted answers, or downstream reporting. * `agent_system_helpscout_conversation_id` — set at handoff initiation; the Help Scout conversation ID. * `agent_system_helpscout_customer_id` — set at handoff initiation; the Help Scout customer ID. * `agent_system_helpscout_agent_id` — set when an agent first replies. Re-sent only when the assigned agent changes. * `agent_system_helpscout_agent_email` — set when an agent first replies, if the agent's Help Scout profile has an email on file. Re-sent only when the assigned agent changes, alongside `agent_system_helpscout_agent_id`. ## Custom fields Help Scout conversation custom fields can also be sent on the handoff. These are configured per AI Agent by your Ada team. See [Custom fields](/docs/handoffs/help-scout/custom-fields) for the full pattern. ## Test the handoff Test the integration before placing it in a live handoff. Test in a separate handoff answer before placing the new handoff in any live handoff dialogue. **To test the handoff:** 1. Trigger a test handoff from the AI Agent, for example via a sandbox conversation that escalates to the new handoff answer. 2. In Help Scout, confirm a new conversation (email ticket) appears in the configured mailbox. 3. As the agent, accept the conversation and send a reply. The message appears in the conversation. 4. Send a file attachment from both sides — the end user attaches a file in Ada, then the agent replies with one in Help Scout — and confirm both make it through. 5. Change the conversation status to **Closed** in Help Scout. The conversation resumes, allowing the end user to continue chatting with the AI Agent. > **Note** > > The Ada handoff ends only when the Help Scout conversation status changes to **Closed**. Other statuses (Active, Pending, Spam) keep the handoff open and the AI Agent paused. If an agent puts a conversation on hold (Pending) or marks it as Spam, Ada does not resume until the status changes to Closed. --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).