Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Help Scout to Fondoo

Live3 min readUpdated

Help Scout in Fondoo: what your AI agent can do with it, what to set up first, the permissions it needs and its limits.

In Help Scout open Your Profile → My Apps and create an OAuth2 application (a placeholder redirect URL is fine for the client-credentials flow), then paste its App ID and App Secret; the credentials act as the Help Scout user who owns the app, which must be an active, invited user, and replies and notes are authored as that user. Optionally set mailboxId (the numeric inbox ID, shown in the inbox URL) to scope listing and to choose where new conversations are created. For live updates add a webhook (Manage → Apps → Webhooks) pointing at the URL from get_helpdesk_webhook, subscribe to convo.created, and paste its secret key as webhookSecret. The Inbox API requires a Standard, Plus or Pro plan.

Official documentation: https://developer.helpscout.com/mailbox-api/

Use add_connection_key without fields for a signed, one-use secure paste page. Then call test_connection and inspect confirmed versus unknown permissions. Direct tool credentials carry a chat-log warning. list_connections never returns credentials.

Auth: client_credentials (OAuth2 POST https://api.helpscout.net/v2/oauth2/token, 2-day bearer token cached encrypted and renewed before expiry). Category: support. Required provider scopes: none; the app acts with the permissions of the Help Scout user that owns it.

Capabilities are discoverable with list_connector_manifests; invoke them through connector_action. Writes retain shared Fondoo scopes, approvals, dry runs, audit, events and metering. Use rotate_connection_key before expiry and delete_connection to remove stored credentials; revoke upstream credentials separately.

Support provider switch

Create a site-scoped vault connection, then set_provider({siteId,capability:"support",provider:"help_scout"}). The shared support operations (support_list_tickets, support_get_ticket, reply, note, status, assign) then use the same normalized adapter contract as Zendesk: tickets.list, tickets.get, tickets.comments, tickets.create, tickets.update. Agent replies need owner approval. Complaints, refunds, legal and other protected categories stay human-only: the classifier routes them to a person and agents cannot answer them, whichever helpdesk is selected. Configure matching rules in Help Scout as well.

  • tickets.list: GET /conversations (status, mailbox when mailboxId is set, page); cursor = next page. Status map: active → open, pending, closed/spam → closed; Help Scout has no solved or new.
  • tickets.get: GET /conversations/{id}?embed=threads; description is the first customer thread as plain text.
  • tickets.comments: GET /conversations/{id}/threads; note threads are private, line items and forwards are skipped; bodies are returned as body (vendor HTML, never rendered) and plain_body.
  • tickets.create: POST /conversations (type:"email", customer thread); needs mailboxId on the connection. The new ID comes from the Resource-ID header.
  • tickets.update: a public comment is POST .../reply to the primary customer (status rides on the reply so it is not silently re-activated), a private one is POST .../notes; status and assignment use PATCH JSON-patch (/status, /assignTo); tags uses PUT .../tags, which replaces the whole tag list. priority is validated but ignored (Help Scout has none).

Webhook

Call get_helpdesk_webhook({connectionId}) for the URL (/webhooks/helpdesk/<connectionId>). In Help Scout (Manage → Apps → Webhooks) add that URL, subscribe to convo.created, and use a long random secret key pasted as webhookSecret. Fondoo verifies X-HelpScout-Signature (base64 HMAC-SHA1 of the raw body) in constant time before any operation runs, takes the event from X-HelpScout-Event, fetches the conversation itself, and stores no message bodies from the webhook. Only the selected provider's new conversations create Fondoo events.

API endpoints used

Limits and uncertainties

  • Rate limit: per account per minute by plan, writes count double; the reviewed page lists no number (a figure of 400/min is widely cited but unverified). Fondoo budgets 30 executes per minute; X-RateLimit-Retry-After is honoured on writes.
  • Webhooks carry no timestamp, so there is no replay window; ingestion is idempotent per conversation instead.
  • Uncertain: the Get Conversation page does not list a priority field, and the create page's status values (active, closed, pending) differ from the reply page's longer list; Fondoo only sends the three common values.
  • Uncertain: the webhook payload for convo.created is the full conversation object per the webhooks page; only its id is used.
  • Not implemented: attachments, merge/move, snooze, custom fields, customer or mailbox management, drafts, CSAT.