> For the complete documentation index, see [llms.txt](https://docs.eesel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eesel.ai/integrations/helpdesks/help-scout.md).

# Help Scout

Set up an AI agent for Help Scout that drafts or sends replies in your shared mailbox, answers Beacon live chats, and learns from your Docs site and past conversations.

eesel's AI agent for Help Scout works inside your Help Scout mailbox. It drafts or sends replies, adds notes and tags, answers Beacon live chats, and learns from your Docs site and past conversations.

Help Scout keeps everything in a shared mailbox rather than a ticket queue. Your AI teammate works the same way, picking up conversations beside your team, inside Help Scout. It reads your Docs site and your past conversations first, so it knows how you answer before it touches anything. Then it handles conversations the way you tell it to. It can leave a draft in the reply box for a person to check. It can answer the routine ones itself. It can tag, assign and close the rest.

In this example the agent answered as an internal note and named the Docs page the answer came from.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-5d10724ad75085cf7398254225b1d04bb2ce6165%2Fhelp-scout-hero.png?alt=media" alt="A Help Scout conversation about a charge after cancelling, with eesel AI posting an internal note that answers the question and names the Docs page it came from"><figcaption><p>Your agent reads the conversation, searches your Docs site, and writes up what it found.</p></figcaption></figure>

{% hint style="info" %}
**On the older Help Scout connection?** Its pages in eesel say it is deprecated. It keeps working. To get new features, connect Help Scout again as below and set up your automations on the new connection. Then switch off the old automations, so the two connections don't both answer.
{% endhint %}

## Set up eesel in Help Scout

{% stepper %}
{% step %}

### Ask your agent to connect Help Scout

Open the chat in your dashboard and ask it to connect Help Scout. It gives you a link to sign in to Help Scout and approve eesel. Prefer to click? Open **Integrations** in the left sidebar, search for Help Scout and click **Connect**.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-5cfc4bd1e5c53fd052a9ff6785cf78d663ab2237%2Fhelpscout-connect-chat-native.png?alt=media" alt="The dashboard chat where the user asks to connect Help Scout, and the agent replies with a Connect Help Scout link and says to sign in as an admin or account owner and approve"><figcaption><p>The agent replies with a Connect Help Scout link.</p></figcaption></figure>
{% endstep %}

{% step %}

### Approve it in Help Scout

Sign in as a Help Scout admin or account owner. Help Scout asks you to authorize eesel AI. Click **Authorize**.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-010e7cd42cabd2a984c28c063aa100397cafaeeb%2Fhelpscout-authorize-native.png?alt=media" alt="Help Scout&#x27;s Authorize eesel AI to access your account screen, with an Authorize button and a Deny link"><figcaption><p>Help Scout's screen to authorize eesel AI.</p></figcaption></figure>

eesel acts as the Help Scout user who signs in. It sees what that user sees, and its replies, drafts and notes show that user's name. Many teams create a separate Help Scout user for eesel, so its work is easy to tell apart. Live chat needs one, see [Live chat (Beacon)](#live-chat-beacon).

This approval is the one step a person has to do in the browser. If an AI agent is doing the setup for you, it hands you the link and waits.
{% endstep %}

{% step %}

### Confirm the connection

You land back on the Help Scout page in eesel, marked **Connected**. Your past conversations start syncing.

Back in the chat, the agent confirms the connection and tells you what it found in your inbox.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-d2e340b9818562eaba7b4354ce7d2a1ded69a330%2Fhelpscout-connected-chat.png?alt=media" alt="The dashboard chat after approval, where the agent says Help Scout is connected, lists the mailbox and tags it found, and notes the Help Center articles are not arriving yet because no Docs address is saved"><figcaption><p>The agent confirms it is connected and says what it can already read.</p></figcaption></figure>
{% endstep %}

{% step %}

### Check what it can read

**Integrations > Help Scout** in the left sidebar shows the connection and its sources. Each source has its own toggle and shows a document count once its sync is done. From a terminal, `eesel status` lists the integration as connected with its source counts.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-a5888d850fc711707d9ee053843a0fa7504d4a4e%2Fhelpscout-integration-page-native.png?alt=media" alt="The connected Help Scout integration page in eesel, with Help Center marked Needs setup and its toggle off, and Conversations showing 6 docs with its toggle on"><figcaption><p>Conversations has synced. Help Center needs its address first.</p></figcaption></figure>

**Conversations** syncs on its own. By default it learns from closed conversations changed in the last 30 days, across every mailbox. Click the gear icon to pick mailboxes, statuses, or how many days back to go.

**Help Center** is your public Help Scout Docs site. It stays locked until you give it the site's address. Click it, enter the URL (for example `https://docs.example.com`) and click **Save Settings**.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-4c7980a511209f113cc502e399f97260e0fbb75d%2Fhelpscout-help-center-url.png?alt=media" alt="The Help Center settings page in eesel, with the Docs site URL field filled in and a Save Settings button"><figcaption><p>Enter your Docs site's address and save.</p></figcaption></figure>

That unlocks Help Center and starts the crawl. Once it finishes, both sources show a document count.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-6131457d5b91e14a5121d59b1353da92696b61d2%2Fhelpscout-help-center-synced.png?alt=media" alt="The Help Scout integration page in eesel, with Help Center showing 5 docs and Conversations showing 6 docs, both toggled on"><figcaption><p>Help Center and Conversations both synced and switched on.</p></figcaption></figure>
{% endstep %}

{% step %}

### Create your first automation

Connecting alone does not start your agent. It needs an automation first. Tell it what to handle and it creates an [automation](/automations-and-schedules/automations-and-schedules.md). An automation is a Help Scout trigger plus instructions. In the instructions you describe which conversations it should handle and what to do with them. It leaves the rest alone.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-d89af559028d0bdcb78f835acd254700916950cd%2Fhelpscout-automation-chat-native.png?alt=media" alt="The dashboard chat where the agent says the new-conversation automation is live, and explains it leaves one draft reply for the team to send and never sends anything itself"><figcaption><p>Ask in chat for the automation you want, and the agent builds it.</p></figcaption></figure>

It shows up on your Automations page, switched on and ready. From a terminal, `eesel automations` lists it as on.

Some actions ask for your approval before they run. In this example, **Leave draft reply** is set to ask first, so each draft waits for a quick approval before it lands in Help Scout. You can change this for each action. See [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md).

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-cd37417f649f64af3e2e5604c5606f36bc105727%2Fhelpscout-automation-live-native.png?alt=media" alt="The Automations page in eesel with the A customer opens a new conversation rule listed and toggled on, and the chat open beside it"><figcaption><p>The new automation on your Automations page, switched on.</p></figcaption></figure>

Open the automation to see or change what it does. The trigger event is fixed when the automation is created. So a new automation is required for each different trigger event.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-a5f8ae675076c280466abe1fed150b9ed1fcfc2c%2Fhelpscout-automation-editor-native.png?alt=media" alt="The automation editor showing the name A customer opens a new conversation, the Help Scout event it runs on, and instructions telling the agent to leave one draft reply for the team to review and send"><figcaption><p>The automation editor, where you change the instructions it follows.</p></figcaption></figure>

When you save your first automation, eesel adds a webhook named **eesel AI** to your Help Scout account. That is how events reach your agent as they happen. Leave it in place.

{% hint style="warning" %}
**Send reply always sends.** A sent reply cannot be recalled. To keep a person in the loop, use **Leave draft reply** instead. It saves the reply unsent in the conversation's reply box, and a teammate reviews, edits and sends it from Help Scout.
{% endhint %}
{% endstep %}

{% step %}

### Check automation work in Help Scout

Open Help Scout and look at the next conversation that comes in to see what the automation did there. In this example the agent left its reply waiting in the conversation's reply box. A teammate reviews it and sends it.

Help Scout shows the draft as written by the user who connected eesel. If that was you, the author shows as **You**, and the **Draft** label marks a reply nobody on your team typed.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-0966112e59b8f02eaf0f2f876ddd4b7c372e9edf%2Fhelpscout-draft-in-conversation.png?alt=media" alt="A Help Scout conversation about live match buffering, with the customer&#x27;s email above and a reply below it marked Draft and attributed to You"><figcaption><p>The customer email, with the drafted reply under it marked Draft.</p></figcaption></figure>

Scroll down and the whole draft is there, from the greeting to the sign-off, ready to edit and send.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-54cf5e4fb97f6a220d141291ffe274bd059c209b%2Fhelpscout-draft-in-conversation-full.png?alt=media" alt="The Help Scout conversation scrolled to the draft reply, labelled Draft, showing the full reply text from Hi Marta to the Vostrel Support sign-off with an Edit button below"><figcaption><p>The full draft reply in the conversation, labelled Draft, with the Edit button below it.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**From Claude Code, Cursor or a terminal.** The same setup works as commands: `eesel login`, then `eesel integrations connect helpscout_v2` (a person approves it in the browser; if the receipt has no link, ask `eesel chat` for one), `eesel integrations download start` to copy your sources in, and `eesel automations` to see and switch on the automations. Trigger keys for this page are in the Triggers table below. Full command reference: [The eesel CLI](/apis-and-developer-resources/cli.md). Step-by-step: [Set up from Claude Code or the terminal](/getting-started/set-up-from-a-coding-agent.md). From an MCP client: [Claude Code and MCP clients](/apis-and-developer-resources/claude-code-and-mcp-clients.md).
{% endhint %}

## Live chat (Beacon)

Your agent can answer visitors in Help Scout's Beacon live chat. It replies in the chat, ends the chat once the visitor's question is answered, and hands the chat to your team when it can't help or the visitor asks for a person. A handover goes back to the queue for whoever is available, or to a person your instructions name, with a note that sums up the chat.

To set it up, create an automation on **A visitor sends a live chat message**. Ask your agent in chat, or pick the event under **Automations > New automation**. There is nothing else to connect.

Two things to know first:

* **It answers during staffed hours.** Beacon offers chat only while someone on your team is Available in Help Scout. Out of hours, Beacon offers email instead, and your email automations pick those up.
* **Connect eesel as its own Help Scout user.** Chat messages show the name of the user who connected eesel. With a separate user, visitors and your team see eesel's messages under that name, and eesel can tell its chats apart from yours.

The chat actions always run on their own, since a visitor is waiting.

## Sources, triggers and actions

### Sources

Sources are what it learns from. Toggle each one on or off from the Help Scout page under Integrations:

| Source            | Description                                                                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Conversations** | Your past conversations. Closed conversations from the last 30 days in every mailbox by default. Pick mailboxes, statuses and how far back from the source's settings |
| **Help Center**   | Your public Help Scout Docs site, crawled from the URL you save on the source. Locked until you save one                                                              |

Every other integration you connect is also a source. So a Help Scout reply can draw on Confluence, Notion, your website, and your files at once. See [Integrations](/integrations/overview.md).

### Triggers

Triggers are the Help Scout events an automation can run on. They arrive as they happen:

| Trigger                                 | Fires when                                                                                                 | Best for                                    | Key                             |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------- |
| **A customer sends a message**          | A customer replies on a conversation, in any mailbox. Replies and notes from your team don't fire it       | Following a conversation through to the end | `helpscout_v2_customer_reply`   |
| **A customer opens a new conversation** | A customer opens a new conversation, in any mailbox. Conversations your team or eesel starts don't fire it | Drafting a first reply, triage and routing  | `helpscout_v2_new_conversation` |
| **A visitor sends a live chat message** | A visitor sends a message in a Beacon live chat                                                            | Answering live chat during staffed hours    | `helpscout_v2_live_chat`        |

### Actions

Actions are what it can do. You find them in the **Actions** section of the Help Scout page under Integrations. Each one can run on its own, ask you first, or stay off. Look-up actions run on their own by default, and the rest ask you first.

|               | Action                                  | What it does                                                                                                                                                                                                                          |
| ------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Respond**   | Leave draft reply                       | Saves a reply unsent in the conversation's reply box, for a teammate to review, edit and send. Nothing reaches the customer. Most teams start here                                                                                    |
|               | Send reply                              | Sends a reply to the customer. A sent reply cannot be recalled                                                                                                                                                                        |
|               | Leave internal note                     | Adds a private note only your team sees                                                                                                                                                                                               |
| **Manage**    | Update conversation                     | Changes a conversation's status (for example closes it), assignee, mailbox or subject                                                                                                                                                 |
|               | Add tags / Remove tags                  | Adds or removes tags on a conversation                                                                                                                                                                                                |
|               | Create conversation                     | Opens a new conversation for a customer, filed as their message and tagged `eesel-created`. Nobody is emailed. It adds a note that the customer's email address was not verified. Useful for handing a website chat over to your team |
|               | Create customer                         | Creates a customer record. Nobody is emailed                                                                                                                                                                                          |
| **Look up**   | List conversations                      | Lists and searches conversations by mailbox, folder, status, tag, assignee, search text, or the day they were created or last updated                                                                                                 |
|               | Read conversation                       | Reads a conversation with every reply, note and draft                                                                                                                                                                                 |
|               | List mailboxes / List tags / List users | Lists your mailboxes, the tags your team uses, and your Help Scout users                                                                                                                                                              |
|               | Find customer                           | Finds customers by email or name                                                                                                                                                                                                      |
| **Live chat** | Chat reply                              | Sends a message in a Beacon live chat, and can end the chat                                                                                                                                                                           |
|               | Hand off live chat to a person          | Hands a Beacon chat back to the queue, or to a named person, with a note for your team                                                                                                                                                |

You stay in control the whole way. Adjust your AI agent's access to knowledge and its action permissions to your liking. See [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md).

## Limitations

* **Its work shows the name of the user who connected eesel.** Replies, drafts, notes and chat messages all appear under that Help Scout user. Connect eesel as its own user to keep them apart from yours.
* **Live chat runs during staffed hours.** Beacon only offers chat while someone on your team is Available.
* **One agent answers live chat per Help Scout account.** If several agents have a live chat automation on the same account, the oldest one answers.
* **One trigger per automation.** The trigger event is fixed when the automation is created, so each trigger needs its own automation.
* **Sent replies cannot be recalled.** To keep a person in the loop, use **Leave draft reply** instead of **Send reply**.
* **No sender blocklist.** The first check cannot see the sender's email address. To skip a sender or domain, tag their conversations with a Help Scout Workflow, for example `no-ai`, and tell the automation to skip that tag.
* **Mailboxes are named by ID.** To keep an automation to one mailbox, name the mailbox ID (the number in its Help Scout URL) in the instructions.

## Troubleshooting

<details>

<summary>Connection didn't complete?</summary>

Sign in to Help Scout as an admin or account owner, and finish the approval on Help Scout's screen. Then start again from the chat, or from **Integrations** in the left sidebar.

</details>

<details>

<summary>Agent not replying to conversations?</summary>

Check the automation is switched on on the agent's **Automations** page, and that its instructions cover the conversations you expect. Check that **Leave draft reply** or **Send reply** is turned on. In Help Scout, check the **eesel AI** webhook is still there. eesel checks it every hour and sets it up again if it stopped working.

</details>

<details>

<summary>Live chats not being answered?</summary>

Check someone on your team is Available in Help Scout, since Beacon only offers chat then. Check the **A visitor sends a live chat message** automation is switched on, and that it is on the agent you expect, since only one agent per Help Scout account answers live chat.

</details>

<details>

<summary>Help Center is locked, or Docs articles are not showing up?</summary>

Help Center stays locked until you save your Docs site URL on it. Click Help Center, enter the address, and save. Confirm the URL is correct and the site is public. Clearing the URL locks Help Center again and takes it off every agent.

</details>

<details>

<summary>Past conversations not training?</summary>

By default only closed conversations from the last 30 days sync. Open the Conversations settings to add statuses, go further back, or check the mailboxes you picked.

</details>

<details>

<summary>Only actions are available, no sources or triggers?</summary>

You may have connected **Help Scout (API Keys)**, which is a separate integration marked *Actions only*. Connect the plain **Help Scout** integration to get sources and triggers as well.

</details>

## FAQ

<details>

<summary>How do I add an AI agent to Help Scout?</summary>

Ask your agent in the dashboard chat to connect Help Scout, sign in to Help Scout as an admin or owner and approve eesel, then ask your agent to create an automation, for example "draft a reply to every new conversation". Connecting alone does nothing: your agent only acts once you create an automation. The steps are in [Set up eesel in Help Scout](#set-up-eesel-in-help-scout).

</details>

<details>

<summary>Can the AI agent answer Help Scout Beacon live chat?</summary>

Yes, while someone on your team is Available in Help Scout. Create an automation on **A visitor sends a live chat message**. Your agent answers, ends the chat when it's resolved, and hands it to your team when it can't help. See [Live chat (Beacon)](#live-chat-beacon).

</details>

<details>

<summary>Does the Help Scout AI agent send replies or only draft them?</summary>

Either, depending on how you set it up. **Leave draft reply** saves the reply unsent in the conversation's reply box and sends the customer nothing, so a teammate reviews, edits and sends it from Help Scout. **Send reply** puts the message straight in front of the customer and cannot be recalled.

</details>

<details>

<summary>How do I keep a human in the loop with the Help Scout AI agent?</summary>

Use **Leave draft reply** instead of **Send reply**, or leave actions set to ask you first. See [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md) for choosing what your agent may do.

</details>

<details>

<summary>Can I limit which Help Scout conversations the AI agent handles?</summary>

Yes. In the automation's instructions, describe the conversations you want in plain language and what to do with them. It takes account of the conversation's tags, its mailbox, its subject, and whether the message looks automated. To skip a sender or domain, tag those conversations with a Help Scout Workflow and tell the automation to skip the tag, as in [Limitations](#limitations). Skipped conversations are listed in the automation's activity, with the reason.

</details>

<details>

<summary>Can I train the Help Scout AI agent on past conversations, and where does the data go?</summary>

Yes. The Conversations source syncs on its own once you connect. The content trains your own agent inside eesel and goes nowhere else. Your agent also learns from your Help Scout Docs site and anything else you connect, such as Confluence, Notion, Google Drive or your website.

</details>

<details>

<summary>Can I connect Help Scout to Claude or ChatGPT?</summary>

Yes, through eesel. Once Help Scout is connected, you can talk to your eesel agent from Claude, ChatGPT or Cursor, and it works with your Help Scout data. See [Use eesel from Claude and other assistants](/apis-and-developer-resources/use-eesel-from-claude-and-other-assistants.md), [Use eesel from ChatGPT](/apis-and-developer-resources/use-eesel-from-chatgpt.md) and [Claude Code and MCP clients](/apis-and-developer-resources/claude-code-and-mcp-clients.md).

</details>

<details>

<summary>What reporting do I get for the Help Scout AI agent?</summary>

The Activity page lists every conversation your agent handled, with a link to it in Help Scout, what it searched, each action it took, who approved it, and its reasoning. The [Reports](/reports/reports.md) page shows volume, triggers, and approvals over time. You can also ask your agent for a written report, or put one on a schedule.

</details>

<details>

<summary>How do I disconnect Help Scout from eesel?</summary>

Open Help Scout under **Integrations** in the left sidebar, then use the **...** menu at the top right to remove the connection. Your agent loses the sources and actions straight away, and eesel removes its webhook from your Help Scout account.

</details>

## Related pages

* [Helpdesk](/use-cases/helpdesk.md) for the job your teammate takes on in a ticket queue
* [Automations and Schedules](/automations-and-schedules/automations-and-schedules.md) for triggers, instructions and schedules
* [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md) for choosing what your agent may do
* [Integrations overview](/integrations/overview.md) for how sources, triggers and actions fit together
* [Set up from Claude Code or the terminal](/getting-started/set-up-from-a-coding-agent.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.eesel.ai/integrations/helpdesks/help-scout.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.