Help Scout

Help Scout

Help Scout is a shared-inbox customer support platform (email, chat, phone). Conversations are tickets; customers carry contact profiles; inboxes (mailboxes) scope routing and custom fields.

Hierarchy

• Inbox — mailbox that receives conversations; capture inbox id before nested field or folder reads.
• Conversation — support ticket with subject, status, assignee, tags, and a thread timeline.
• Customer — profile linked to conversations; match by id or email on creates.
• Team / User — roster data for assignment and workload context.
• Workflow — automation definitions (list before manual runs).
• Tag — account-wide labels for filtering and reporting.

Operational order

1. List inboxes to resolve mailbox ids for new conversations or inbox-scoped metadata.
2. List or search conversations before fetching threads — always take conversation ids from a fresh list response.
3. List customers when you need profile context or before linking a ticket to a known contact.
4. List teams and users when assigning or summarizing ownership.
5. Prefer combined read tools: omit id to list, pass id to fetch one row; pass team id to load members; pass inbox id with sub_resource for fields or folders.

Write semantics

• Conversation create — supply subject, mailbox id, channel type, customer object, and at least one thread.
• Conversation update — send a JSON Patch operation array (replace subject, status, assignee, mailbox, or linked customer id — one op per field).
• Reply — add a reply on an existing conversation id with customer object and text (draft flag optional).
• Customer create — supply profile fields; customer update — JSON Patch array on the customer row.
• Deletes — conversation and customer removal are permanent; customer delete is GDPR erasure and may fail when conversation count exceeds upstream limits.

Gotchas

• Stale conversation ids: Merged or deleted tickets return not-found on thread reads — re-list conversations and use a current id.
• JSON Patch updates: Conversation and customer updates require a patch operation array, not a flat body.
• Rate limits: Help Scout enforces per-account request quotas; pace bulk reads and writes.
• Merged conversations: Old ids may 301 to a new location for 60 days, then 404 — fetch the conversation row to resolve the canonical id before mutating.