--- title: Help Scout API Integration on Truto slug: helpscout category: Helpdesk canonical: "https://truto.one/integrations/detail/helpscout/" --- # Help Scout API Integration on Truto **Category:** Helpdesk **Status:** Generally available ## Unified APIs ### Unified User Directory API - **Groups** — Groups are a collection of users in the source application. In some applications, they might also be called Teams. - **Roles** — The Role object represents a role of a User. - **Users** — The User object represents a User. ### Unified Ticketing API - **Attachments** — Attachments are the files associated with a ticket or a comment. - **Collections** — Tickets and contacts can be grouped into Collections. Collection resource usually maps to the various grouping systems used in the underlying product. Some examples are lists, projects, epics, etc. You can differentiate between these grouping systems using the type attribute of a Collection. - **Comments** — Comments represent the communication happening on a Ticket, both between a User and a Contact and the internal things like notes, private comments, etc. A Ticket can have one or more Comments. - **Contacts** — Contact represent the external people you are in contact with. These could be customers, leads, etc. Contacts can be associated with an Account if the underlying product supports it. - **Fields** — Fields represent the attributes defined for various entities in the underlying product. Depending on the underlying product, custom attributes can be defined by a User on various entities like Ticket, Contact, etc. is_user_defined attribute within Field can be used to differentiate between custom and system defined Fields. - **Tags** — Tags represent a common classification approach used in various ticketing systems. A Ticket may have one or more Tags associated with them. - **Teams** — Teams represent the grouping system used for Users. These are usually called groups, teams, agent groups, etc. in the underlying products. A User can belong to one or more Teams. - **Ticket Status** — Ticket Status represents the completion level of the Ticket. Some products provide customizing the Ticket Status. - **Ticket Types** — Ticket Types represent the classification system used by the underlying products for Tickets. Some examples are bugs, feature, incident, etc. - **Tickets** — Core resource which represents some work that needs to be carried out. Tickets are usually mapped to issues, tasks, work items, etc. depending on the underlying product. - **Users** — Users represent the people using the underlying ticketing system. They are usually called agents, team members, admins, etc. - **Workspaces** — Workspaces represent the top-level subdivision in a ticketing system. They usually have their own set of settings, tickets, statuses, priorities and users. Some of the usual terminologies used by the products for the top-level subdivision are projects, bases, spaces, workspace, etc. A Workspace could belong to an Organization. ## MCP-ready AI tools Truto exposes 90 tools for Help Scout that AI agents can call directly. - **list_all_helpscout_customers** — List customers filtered by mailbox, firstName, lastName, or modifiedSince in Help Scout. Returns id, firstName, lastName, gender, jobTitle, location, organization, photoType, photoUrl, age, createdAt, updatedAt, background, and draft fields. - **get_single_helpscout_customer_by_id** — Get customer details by id in Help Scout. Returns fields including firstName, lastName, jobTitle, location, organization, photoUrl, background, gender, age, createdAt, updatedAt, draft, and embedded sub-entities like emails, phones, chats, social_profiles, websites, properties, and address. - **create_a_helpscout_customer** — Create a new customer in Help Scout with provided customer details. Returns the resource ID and location of the created customer. - **delete_a_helpscout_customer_by_id** — Delete a customer by id in Help Scout, including their survey responses and conversations. This operation hard-deletes the customer and cannot be undone. Fails if user lacks access to all conversations or if customer has more than 100 conversations. - **update_a_helpscout_customer_by_id** — Update a customer profile by id in Help Scout using patch operations on fields such as firstName, lastName, emails, phones, and social profiles. Returns no content on success. - **helpscout_customers_overwrite** — Overwrite customer data by id in Help Scout. Updates fields like firstName, lastName, photoUrl, photoType, jobTitle, location, background, age, gender, and organization. Fields not set will be overwritten with null. - **list_all_helpscout_conversations** — List conversations filtered by mailbox, folder, status, tag, assigned_to, modifiedSince, number, and customFieldsByIds in Help Scout. Returns id, number, threads, type, folderId, status, subject, mailboxId, assignee, createdBy, createdAt, closedBy, closedAt, tags, cc, bcc, primaryCustomer, snooze, nextEvent, and customFields fields. - **get_single_helpscout_conversation_by_id** — Get conversation by id in Help Scout. Returns id, number, threads count, type, folderId, status, state, subject, preview, mailboxId, assignee info, creator info, timestamps, source, tags, cc, bcc, primary customer, custom fields, snooze and next event details. - **create_a_helpscout_conversation** — Create a conversation in Help Scout with required parameters subject, type, mailboxId, status, customer, and threads. Returns the created conversation's ID and location. - **update_a_helpscout_conversation_by_id** — Update a conversation in Help Scout by changing subject, customer, draft status, mailbox, status, or owner using id. Returns no content on success. If conversation merged, returns 404. - **delete_a_helpscout_conversation_by_id** — Delete a conversation by id in Help Scout. Returns no content on success. If the conversation was merged, a 404 is returned; use Get Conversation to find the new location. - **list_all_helpscout_users** — List users in Help Scout. Returns an array of user objects including id, firstName, lastName, email, role, timezone, photoUrl, createdAt, updatedAt, type, mention, initials, jobTitle, phone, and alternateEmails. - **get_single_helpscout_user_by_id** — Get information about a specific user in Help Scout by id. Returns id, firstName, lastName, email, role, timezone, type, photoUrl, initials, mention, jobTitle, phone, alternateEmails, createdAt, and updatedAt. - **delete_a_helpscout_user_by_id** — Delete a user by id in Help Scout. Only Administrators and Account Owners can delete users. The user making the request cannot delete themselves. - **list_all_helpscout_teams** — List teams in Help Scout. Returns an array of teams with fields id, name, initials, mention, createdAt, updatedAt, timezone, and photoUrl. - **list_all_helpscout_team_members** — List team members for team with id in Help Scout. Returns an array of user objects including id, firstName, lastName, email, role, timezone, photoUrl, createdAt, updatedAt, type, mention, initials, jobTitle, phone, and alternateEmails. - **list_all_helpscout_tags** — List tags used across all inboxes in Help Scout. Returns id, name, slug, ticketCount, color, createdAt, and updatedAt for each tag. - **get_single_helpscout_tag_by_id** — Get a tag by id in Help Scout. Returns id, name, slug, and color of the tag. - **list_all_helpscout_conversation_threads** — List threads for a conversation in Help Scout using id. Returns thread id, type, status, state, body, source type and via, customer info, creator info, assigned user, savedReplyId, email fields (to, cc, bcc), createdAt, openedAt, rating, schedule details, and attachments. - **create_a_helpscout_conversation_thread** — Create a reply thread for a conversation in Help Scout with required parameters id, text, and customer. Returns the internal ID of the newly created thread in Resource-Id header. Note: max 100 threads per conversation and company policies may restrict updates on old conversations. - **update_a_helpscout_conversation_thread_by_id** — Update a thread's text or hidden status in Help Scout. Requires id for conversation and thread. Returns no content. Only allowed for administrators or if thread editing is enabled. Supports replace operation on /text and /hidden paths. - **list_all_helpscout_conversation_attachments** — List threads for a conversation in Help Scout using id. Returns thread id, type, status, state, body, source type and via, customer info, createdBy info, assignedTo info, savedReplyId, email fields (to, cc, bcc), createdAt, openedAt, rating details, scheduled details, and attachments. - **helpscout_conversation_attachments_download** — Use this endpoint to download the file associated with an attachment in a conversation thread. The URL is provided in the attachments downloadUrl field when you retrieve the conversation threads - **create_a_helpscout_conversation_attachment** — Upload an attachment to a specific thread in a conversation in Help Scout. Requires conversation_id, thread_id, fileName, mimeType, and base64-encoded data. The response confirms creation. Uploaded attachments are scanned for malicious content and may be inaccessible if detected. - **list_all_helpscout_mailboxes** — List mailboxes in Help Scout. Returns id, name, slug, email, createdAt, and updatedAt for each mailbox. - **get_single_helpscout_mailbox_by_id** — Get mailbox information by id in Help Scout. Returns id, name, slug, email, createdAt, and updatedAt fields. - **list_all_helpscout_me** — Get information about the authenticated user in Help Scout. Returns id, firstName, lastName, email, role, timezone, photoUrl, createdAt, updatedAt, type, mention, initials, jobTitle, phone, alternateEmails, and companyId. - **list_all_helpscout_mailbox_fields** — List custom fields for a mailbox in Help Scout using mailbox id. Returns fields with id, required status, order, type, name, and dropdown options with id, order, and label. - **list_all_helpscout_customer_properties** — List customer property definitions in Help Scout. Returns type, slug, name, and options for dropdown properties. - **create_a_helpscout_customer_property** — Create a customer property in Help Scout with type, slug, and name. Returns the created property. Limit of 50 customer property definitions per company. - **delete_a_helpscout_customer_property_by_id** — Delete a specific customer property definition in Help Scout using id. This is a soft delete operation; the property will be scheduled for hard deletion and its slug released. - **list_all_helpscout_inbox_folders** — List inbox folders for mailbox_id in Help Scout. Returns id, type, name, totalCount, userId, activeCount, and updatedAt for each folder. - **list_all_helpscout_ticket_fields** — Use this endpoint to retrieve all custom field values associated with a specific conversation (ticket) in Help Scout. Custom fields help capture additional information about a conversation, such as priority, order number, or any custom data you’ve configured for your workspace. - **list_all_helpscout_inbox_saved_replies** — List saved replies for inbox_id in Help Scout. Returns id, name, preview for email replies, and chatPreview for chats. - **get_single_helpscout_inbox_saved_reply_by_id** — Get a saved reply by inbox_id and id in Help Scout. Returns id, name, text, and chatText of the saved reply. - **create_a_helpscout_inbox_saved_reply** — Create a saved reply in Help Scout for mailbox_id with required name. Returns the created saved reply including its name, text, and chatText fields. - **update_a_helpscout_inbox_saved_reply_by_id** — Update a saved reply in Help Scout using mailbox_id and id. Returns no content on success. - **delete_a_helpscout_inbox_saved_reply_by_id** — Delete saved reply by id in Help Scout. Requires mailbox_id and id. No content is returned in the response. - **list_all_helpscout_workflows** — List workflows filtered by mailboxId and type in Help Scout. Returns id, mailboxId, type, status, order, name, createdAt, and modifiedAt for each workflow. - **update_a_helpscout_workflow_by_id** — Update workflow status by setting status to 'active' or 'inactive' in Help Scout. Requires id, op as 'replace', value as new status, and path as '/status'. Returns no content on success. - **helpscout_workflows_run** — Run a specific manual workflow in Help Scout using its workflow_id. Requires workflow_id. Applies workflow actions to each conversation listed in conversationIds (max 50). Returns no content on successful execution. - **list_all_helpscout_webhooks** — List webhooks in Help Scout. Returns an array of webhooks with fields including id, url, state, events, notification, payloadVersion, and label. - **get_single_helpscout_webhook_by_id** — Get information about a specific webhook in Help Scout by id. Returns id, url called on events, list of events, notification flag, label, payloadVersion, and state. - **create_a_helpscout_webhook** — Create a webhook in Help Scout with url, events, and secret. Returns the webhook id in the Resource-ID header. - **update_a_helpscout_webhook_by_id** — Update webhook with id in Help Scout. Requires url, events, and secret. Returns no content on success. - **delete_a_helpscout_webhook_by_id** — Delete a webhook by id in Help Scout. Returns no content on success. - **get_single_helpscout_satisfaction_rating_by_id** — Get satisfaction rating by id in Help Scout. Returns id, threadId, conversationId, conversationNumber, mailboxId, comments, rating, createdAt, user, and customer details. - **list_all_helpscout_mailbox_folders** — List inbox folders for mailbox_id in Help Scout. Returns id, type, name, totalCount, userId, activeCount, and updatedAt for each folder. - **get_single_helpscout_customer_address_by_id** — Get the address of a specific customer in Help Scout by customer id. Returns city, state, postalCode, country, and address lines. - **create_a_helpscout_customer_address** — Create an address for a customer in Help Scout. Requires id, city, state, postalCode, and country. Returns location of the created address. - **update_a_helpscout_customer_address_by_id** — Update address for a customer in Help Scout using id. Requires city, state, postalCode, and country. Returns no content on success. - **delete_a_helpscout_customer_address_by_id** — Delete address for a specific customer in Help Scout. Requires id. No content is returned in the response. - **list_all_helpscout_customer_chat_handles** — List chat handles for a customer in Help Scout. Requires customer_id. Returns an array of chat objects with id, value, and type fields. - **create_a_helpscout_customer_chat_handle** — Create a chat handle for a customer in Help Scout. Requires customer_id, type, and value. Returns the internal ID of the newly created chat handle. - **update_a_helpscout_customer_chat_handle_by_id** — Update chat handle for a specific chat identified by id and customer_id in Help Scout. Requires type (chat type) and value (chat handle). No content is returned in the response. - **delete_a_helpscout_customer_chat_handle_by_id** — Delete a chat handle for a customer in Help Scout using customer_id and id. No content is returned in the response. - **list_all_helpscout_customer_emails** — List emails for a specific customer in Help Scout. Requires customer_id. Returns an array of email objects including id, value, and type. - **create_a_helpscout_customer_email** — Create an email for a customer in Help Scout. Requires customer_id, type (home, other, work), and value (email). Returns Resource-Id header with the internal ID of the new email. - **update_a_helpscout_customer_email_by_id** — Update email for customer with customer_id and id in Help Scout. Returns no content on success. - **delete_a_helpscout_customer_email_by_id** — Delete an email for a specific customer in Help Scout using customer id and email id. No content is returned in the response. - **list_all_helpscout_customer_phones** — List phone numbers for a customer in Help Scout using customer_id. Returns an array of phones with id, value, and type fields. - **create_a_helpscout_customer_phone** — Create a phone for customer with customer_id in Help Scout. Requires type and value. Returns the internal ID of the newly created phone in Resource-Id header. - **update_a_helpscout_customer_phone_by_id** — Update phone for customer using customer_id and id. Requires type (phone location) and value (telephone number). Response returns no content. - **delete_a_helpscout_customer_phone_by_id** — Delete a phone by id for a customer in Help Scout. Requires customer_id and id. Returns no content on success. - **list_all_helpscout_customer_social_profiles** — List social profiles for a customer in Help Scout. Requires customer_id. Returns id, value (profile URL), and type of each social profile. - **create_a_helpscout_customer_social_profile** — Create a social profile for a customer in Help Scout using customer_id. Requires type and value. Returns the internal ID of the newly created social profile. - **update_a_helpscout_customer_social_profile_by_id** — Update social profile for customer with customer_id and social profile id in Help Scout. Requires type and value fields. No content is returned in the response. - **delete_a_helpscout_customer_social_profile_by_id** — Delete a social profile by id for a customer identified by customer_id in Help Scout. No content is returned in the response. - **list_all_helpscout_customer_websites** — List websites for a customer in Help Scout. Requires customer_id. Returns an array of website objects with id and value fields. - **create_a_helpscout_customer_website** — Create a website for a customer in Help Scout using customer_id and value. Returns the internal ID of the newly created website in Resource-Id header. - **update_a_helpscout_customer_website_by_id** — Update website URL for a specific website of a customer in Help Scout. Requires customer_id, id, and value (website URL). Returns no content on success. - **delete_a_helpscout_customer_website_by_id** — Delete a specific website by id for a customer identified by customer_id in Help Scout. No content is returned in the response. - **list_all_helpscout_user_statuses** — List user statuses in Help Scout. Returns userId, email (status, updatedAt, performedBy, source), and chat (status, mailboxStatuses) fields for each user. - **get_single_helpscout_user_status_by_id** — Get the status of a specific user in Help Scout by id. Returns userId, email status details (status, updatedAt, performedBy, source), and chat status details (status and mailboxStatuses). - **update_a_helpscout_user_status_by_id** — Update user status in Help Scout. Requires id and status. Returns no content on success. - **list_all_helpscout_organizations** — List organizations in Help Scout. Returns id, name, website, description, location, logoUrl, note, domains, phones, and brandColor for each organization in the response. - **get_single_helpscout_organization_by_id** — Get details of a specific organization in Help Scout using id. Returns fields including id, name, website, description, location, brandColor, customerCount, conversationCount, and properties. - **create_a_helpscout_organization** — Create an organization in Help Scout. Returns the id of the created organization in the Resource-ID header, which uniquely identifies the organization. - **update_a_helpscout_organization_by_id** — Update an organization in Help Scout using id. Performs a full replacement—any omitted fields are cleared. Returns no content on success. - **delete_a_helpscout_organization_by_id** — Delete a specific organization in Help Scout using id. Also removes this organization reference from all customers. Returns no content on success. - **list_all_helpscout_organization_conversations** — List conversations for an organization in Help Scout. Requires organization_id. Returns conversation details such as id, subject, status, type, assignee, createdAt, and primaryCustomer information. - **list_all_helpscout_organization_customers** — List customers associated with a specific organization in Help Scout. Requires organization_id. Returns id, firstName, lastName, jobTitle, location, organization, photoUrl, createdAt, and updatedAt for each customer. - **list_all_helpscout_organization_property_definitions** — List all organization-property-definitions in Help Scout. Each account can have up to 50 property definitions. Returns slug, name, type, and options for dropdown properties. - **get_single_helpscout_organization_property_definition_by_id** — Get an organization property definition in Help Scout using id. Returns slug, name, type, and options array with dropdown labels for the property. - **create_a_helpscout_organization_property_definition** — Create a new organization property definition in Help Scout. Requires type, slug, and name. Returns the created property's details including type, slug, name, and options for dropdown types. - **update_a_helpscout_organization_property_definition_by_id** — Update an existing organization property definition in Help Scout. Requires id. You can update the property's name and options list. The response returns no content (HTTP 204) on success. - **delete_a_helpscout_organization_property_definition_by_id** — Delete an organization property definition in Help Scout using id. This performs a soft-delete and the property will be permanently removed after a grace period. - **list_all_helpscout_company_reports** — Get overall company performance report in Help Scout. Returns filterTags (available tag filters), current and previous time range statistics, user performance metrics, and deltas showing performance change when two time ranges are specified. - **list_all_helpscout_customer_helped_reports** — Get the customers helped report in Help Scout for a given time range. Returns current and optionally previous arrays including 'date' and 'customers' fields showing how many customers were helped during each period. - **list_all_helpscout_company_drilldown_reports** — Get detailed conversation data for a company in Help Scout using required parameters start and end. Returns conversation fields including id, number, type, subject, status, customerName, and assignedName. ## How it works 1. **Link your customer's Help Scout account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Help Scout.** The Proxy API is a 1-to-1 mapping of the Help Scout API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **AI-Powered Ticket Triage and Response Drafting** — AI support platforms can ingest incoming Help Scout conversations, analyze sentiment and intent, apply tags, route to the right mailbox, and post hidden internal notes with suggested responses — all without the end customer seeing any automation. - **Bi-Directional CRM Contact Sync** — Vertical CRMs can keep their customer records perfectly in sync with Help Scout by writing back customer details, addresses, phone numbers, emails, social profiles, and organization associations — ensuring support agents always have the latest context from the system of record. - **Voice of Customer and CSAT Analytics** — Feedback and analytics platforms can poll closed conversations, correlate Help Scout's native satisfaction ratings with their own survey data, and enrich conversations with outcome tags to build unified customer sentiment dashboards. - **Event-Driven Workflow Automation** — Workflow orchestration tools can listen for Help Scout webhook events, trigger external business logic, and programmatically run Help Scout's native workflows on batches of conversations to enforce consistent handling across teams. - **Contextual Agent Sidebar via Custom Fields** — SaaS products can dynamically read a user's mailbox custom fields and customer properties, then push enriched external data (subscription tier, usage metrics, order history) into those fields so agents see full context without leaving Help Scout. ## What you can build - **Two-Way Conversation Sync with Internal Notes** — Sync Help Scout conversations and threads into your product, and push back internal notes, status updates, and tags without ever emailing the end customer. - **Dynamic Custom Field Mapping Engine** — Query mailbox fields and ticket fields from Help Scout to auto-generate matching forms in your UI, letting users map their data to the right Help Scout workspace without manual configuration. - **Deep Customer Profile Sync** — Programmatically create and update Help Scout customers including nested sub-entities like emails, phone numbers, chat handles, social profiles, addresses, and website URLs from your application's contact database. - **Organization and Property Management** — Create organizations, link customers to them, and define custom organization property definitions to surface external identifiers (e.g., account IDs, MRR) directly in the Help Scout agent sidebar. - **Automated Workflow Execution Pipeline** — List available Help Scout workflows and programmatically run them against batches of up to 50 conversations at once, enabling bulk triage, tagging, and assignment from external triggers. - **Attachment-Aware Bug Tracking Integration** — Download and upload conversation attachments to bridge Help Scout support threads with external QA or bug-tracking systems, keeping screenshots and logs linked across tools. ## FAQs ### What authentication method does the Help Scout integration use? Help Scout uses OAuth 2.0 for API access. Truto handles the full OAuth flow — token exchange, refresh, and storage — so your end users simply authorize their Help Scout account through Truto's managed connect flow. ### How does Help Scout's data model map to Truto's Unified Ticketing API? Help Scout Conversations map to Tickets, Threads map to Comments, Customers map to Contacts, Mailboxes map to Workspaces, Users map to Users, Teams map to Teams, Tags map to Tags, and mailbox/ticket custom fields map to Fields. Attachments and ticket statuses are also supported through their respective unified resources. ### Can I create internal notes on conversations without notifying the customer? Yes. Use the create_a_helpscout_conversation_thread endpoint with a hidden/internal note type. This is ideal for posting AI summaries, audit trails, or agent-facing context without triggering any email to the end customer. ### How are Help Scout's nested customer sub-entities handled? Help Scout stores customer emails, phones, addresses, chat handles, social profiles, and websites as separate sub-entities. Truto exposes dedicated CRUD endpoints for each — for example, create_a_helpscout_customer_email or update_a_helpscout_customer_phone_by_id — so you can manage granular contact data without overwriting the entire customer record. ### Can I trigger Help Scout's native workflows via the API? Yes. The helpscout_workflows_run endpoint lets you programmatically execute a predefined Help Scout manual workflow against a batch of conversations. You can also list all workflows with list_all_helpscout_workflows and toggle them with update_a_helpscout_workflow_by_id. ### Does the integration support webhook management for real-time events? Yes. You can create, list, update, and delete Help Scout webhooks via Truto (create_a_helpscout_webhook, list_all_helpscout_webhooks, etc.), allowing your application to receive real-time notifications for conversation events instead of relying on polling.