How to Build an AI Agent for Help Scout (2026)

What a Help Scout AI agent does

The loop is the same as any support agent, wired to Help Scout: a new conversation arrives → the agent reads it and the customer's history → it calls tools (look up the order, search your Docs, check a policy) → it posts a reply to the customer or reassigns the conversation to a human. The trick is doing that reliably against real conversations. (New to agents generally? Start with AI agents for customer service.)

Option 1: Build it against the Help Scout API

Help Scout has a full REST API (the Mailbox API v2), so you can build the agent yourself. The pieces:

• Read conversations — the Conversations and Threads endpoints pull the conversation, its message threads, and the customer.
• Reply / act — post a reply thread, change status, or reassign via the API.
• Trigger on new conversations — a Help Scout webhook fires your endpoint when a conversation is created.

A reply tool against the real Help Scout Mailbox API looks like this:

import requests
HS = "https://api.helpscout.net/v2"

def reply_to_conversation(conversation_id: str, customer_id: int, body: str):
    r = requests.post(f"{HS}/conversations/{conversation_id}/reply",
        json={"text": body, "customer": {"id": customer_id}, "draft": False},
        headers={"Authorization": f"Bearer {OAUTH_TOKEN}"}, timeout=10)
    r.raise_for_status()          # handle 429 rate limits, token refresh
    return {"status": "sent", "thread": r.headers.get("Resource-Id")}

That endpoint returns 201 Created with the new thread id in the Resource-Id header (Help Scout Mailbox API docs). Wrap it (and a get_customer, a search_docs) as tools in an agent loop on the model of your choice — see our from-scratch walkthrough in how to build an AI agent: from scratch vs. platform.

The production part

The API calls are the easy bit. A Help Scout agent you'd trust also needs: a webhook endpoint (with signature verification and idempotency so a retried event doesn't double-reply), rate-limit handling (Help Scout throttles, and OAuth tokens expire and need refreshing), grounding in your Docs/help center (embed the articles, keep them fresh), guardrails (escalate refunds, don't leak PII), hosting 24/7, observability, and an eval harness over real historical conversations. That's weeks of work plus upkeep — the undifferentiated infrastructure every support agent needs.

Option 2: Connect Help Scout via Macha

If the goal is a working agent on your Help Scout — not a project to maintain — a platform that connects natively is far faster. Macha layers on top of Help Scout (it's not a Help Scout replacement or a marketplace app you install — it connects via OAuth and works autonomously):

• One-click connect — Macha ships a native Help Scout connector: authorize Help Scout and the agent can read conversations and post replies, with a full set of conversation tools ready to use.
• Ground on your help center — add your Help Scout Docs site as a Source so replies quote real articles.
• Any other system as a tool — Custom Tools turn your order/billing APIs into agent capabilities by describing them.
• Runs and grades — the agent runs in the cloud triggered by new conversations; Agent Analytics show every run, and Studies grade it against real historical conversations before it goes live.

Build vs. connect — for Help Scout

So which should you build?

Build on the API if you need a fully custom runtime, have strict data-residency needs, or the agent is your product. For most Help Scout teams who just want conversations resolved, a native connector gets you a measurable agent on your real conversations far faster — and you keep your model of choice. You can start free on Macha, connect Help Scout, and test an agent on your own conversations the same day.

FAQ

Is a Help Scout AI agent the same as Help Scout's own AI? Not necessarily. Help Scout offers built-in AI features, but you can also run a model-agnostic agent on top of Help Scout (via its Mailbox API or a platform like Macha) — useful if you want a specific model, custom tools, or to grade the agent your own way.

Do I need to install a Help Scout app? No — Macha connects to Help Scout via OAuth and works autonomously; it's an AI layer on top of Help Scout, not a marketplace app you install.

Can the agent take actions, not just answer? Yes — via the Help Scout API (reply, change status, reassign, tag) plus your own systems' APIs as tools (order lookups, refunds) through Custom Tools, with guardrails on what it can do unattended.

How do I make sure it's accurate before it replies to customers? Ground it in your Docs and grade it against real historical conversations first (Macha's Studies do this), start in a draft/approve mode, and widen autonomy per conversation type as it earns trust.