Configure the Help Scout handoff

After you complete the 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.

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:

Navigate to Config → Apps, where the Help Scout Utilities app is now listed.
Click Connect to open the app’s configuration form.
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:

In your handoff answer, add the Help Scout Utilities block with action Handoff to a human agent.
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
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.
Optionally map AI Agent variables into any of the additional fields documented below.

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.

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.

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 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:

Trigger a test handoff from the AI Agent, for example via a sandbox conversation that escalates to the new handoff answer.
In Help Scout, confirm a new conversation (email ticket) appears in the configured mailbox.
As the agent, accept the conversation and send a reply. The message appears in the conversation.
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.
Change the conversation status to Closed in Help Scout. The conversation resumes, allowing the end user to continue chatting with the AI Agent.

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.