Help Scout

1. Overview

Helpscout is a customer service platform designed to help businesses manage customer communications across various channels. It provides tools for email support, live chat, and knowledge base creation, fostering a more personal and efficient customer experience.

With the GoInsight Helpscout node, you can seamlessly integrate customer support operations into your automated workflows. This allows you to manage key resources within your Helpscout account programmatically, including:

• Conversations and Threads: Create, retrieve, update, and delete conversations and their associated threads (like notes or chats).
• Customer Management: Add new customers, retrieve customer lists, update profiles, and remove them.
• Organization Management: Manage company or organization profiles linked to your customers.
• Support Resources: Fetch information about mailboxes, tags, and custom customer properties.

2. Prerequisites

Before using this node, you must have a valid Helpscout account. You may also need administrative privileges or specific permissions within your Helpscout account to generate and manage API credentials.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node provides a comprehensive set of operations to manage conversations, customers, organizations, and other resources within your Helpscout account. The table below summarizes the available actions.

Operation Details

Create a Conversation

Creates a conversation in an inbox with at least one thread.

Input Parameters:

• ConversationData: Conversation data to create.Must include the following fields:type(str),customer(dict), mailboxId(int),subject(str),status(str),threads(list).

Output:

• Conversation (object): Created conversation data from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete a Conversation

Deletes a conversation in Inbox.

Input Parameters:

• ConversationId: A conversation id in an inbox.

Output:

• Success (bool): Indicates if the conversation was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Conversations

Gets all conversations from HelpScout using client credentials authentication.

Options:

• FilterFields: Filter fields to apply to the query.

Output:

• Conversations (object-array): Conversation data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Organization Conversations

Gets all conversations for an organization from HelpScout using client credentials authentication.

Input Parameters:

• OrganizationId: Organization ID to get conversations for.

Options:

• Page: Page number for pagination. Defaults to 1.

Output:

• Conversations (object-array): Conversation data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Conversation

Gets a conversation from HelpScout by ID using client credentials authentication.

Input Parameters:

• ConversationId: conversation ID.

Output:

• Conversation (object): Conversation data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update Conversation Tags

Allows for a single conversation’s tags to be updated.

Input Parameters:

• ConversationId: conversation ID.

Options:

• Tags: List of tags to be applied to the conversation, if the tag specified does not exist it will be first created and then applied.

Output:

• Success (bool): Updates tags successfully or not.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update a Conversation

Updates a conversation in HelpScout by ID using client credentials authentication.

Input Parameters:

• ConversationId: A conversation id in an inbox.
• ConversationData: Conversation data to update.

Output:

• Conversation (object): Updated conversation data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Customer

Creates a customer in helpscout.net using client credentials authentication.

Input Parameters:

• CustomerData: Customer data to create.

Output:

• Customer (object): Created customer data from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete a Customer

Deletes a customer from HelpScout by ID using client credentials authentication.

Input Parameters:

• CustomerId: HelpScout customer ID.

Output:

• Success (bool): Indicates if the customer was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Customers

Gets all customers from HelpScout using client credentials authentication.

Options:

• FilterFields: Filter fields to apply to the query.

Output:

• Customers (object-array): Customer data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Organization Customers

Gets all customers for an organization from HelpScout using client credentials authentication.

Input Parameters:

• OrganizationId: Organization ID to get customers for.

Options:

• Page: Page number for pagination. Defaults to 1.

Output:

• Customers (object-array): Customer data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Customer

Gets a customer from HelpScout by ID using client credentials authentication.

Input Parameters:

• CustomerId: Customer ID.

Output:

• Customer (object): Customer data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update a Customer

Updates a customer in HelpScout by ID using client credentials authentication.

Input Parameters:

• CustomerId: HelpScout customer ID.
• CustomerData: Customer data to update.

Output:

• Success (bool): Indicates whether the update was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create Customer Property Definition

Creates a customer property definition in HelpScout using client credentials authentication.

Input Parameters:

• PropertyData: Customer property definition data to create.Must include fields:name(str),type(str),slug(str).

Output:

• Success (bool): Indicates whether the operation was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete Customer Property Definition

Deletes a customer property definition from HelpScout by ID using client credentials authentication.

Input Parameters:

• Slug: HelpScout customer ID.

Output:

• Success (bool): Indicates if the property definition was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Customer Property Definitions

Gets customer property definitions from HelpScout using client credentials authentication.

Output:

• Properties (object-array): Customer property definitions retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update Customer Property Definition

Updates a customer property definition in HelpScout by ID using client credentials authentication.

Input Parameters:

• CustomerId: HelpScout customer ID.
• PropertyData: Customer property definition data to update.

Output:

• Success (bool): Indicates whether the update was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Mailboxes

Gets all mailboxes from helpscout.net using client credentials authentication.

Output:

• Mailboxs (object-array): Mailbox data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Mailbox

Gets a mailbox from HelpScout by ID using client credentials authentication.

Input Parameters:

• MailboxId: https://secure.helpscout.net/ mailbox ID.

Output:

• Mailbox (object): Mailbox data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create an Organization

Creates an organization in helpscout.net using client credentials authentication.

Input Parameters:

• OrganizationData: Organization data to create.

Output:

• Organization (object): Created organization data from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete an Organization

Deletes an organization from HelpScout by ID using client credentials authentication.

Input Parameters:

• OrganizationId: HelpScout organization ID.

Output:

• Deleted (bool): Indicates if the organization was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Organizations

Gets all organizations for the account from HelpScout using client credentials authentication.

Options:

• Page: Page number for pagination. Defaults to 0.
• Sort: Organizations can be sorted by name, customerCount, conversationCount, or lastInteractionAt. (e.g., name,asc or customerCount,desc) If the direction is omitted,it defaults to descending.

Output:

• Organizations (object-array): Organization data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update an Organization

Updates an organization in HelpScout by ID using client credentials authentication.

Input Parameters:

• OrganizationId: Organization ID.
• OrganizationData: Organization data to update.This is a complete update, meaning that all fields must be provided, even if they are meant to be unchanged. Otherwise, all missing fields will be removed from the organization.

Output:

• Organization (object): Updated organization data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Tags

Gets all tags used across all inboxes from HelpScout using client credentials authentication.

Options:

• Page: Page number for pagination. Defaults to 0.

Output:

• Tags (object-array): Tag data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Chat Thread

Creates a new chat thread to a conversation.

Input Parameters:

• ConversationId: A conversation id in an inbox where the thread will be created.
• ThreadData: Customer thread data to create.

Output:

• ResourceId (string): Internal ID of the newly created thread.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Customer Thread

Creates a new customer thread to a conversation.

Input Parameters:

• ConversationId: A conversation id in an inbox where the thread will be created.
• ThreadData: Customer thread data to create.

Output:

• ResourceId (string): Internal ID of the newly created thread.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Note

Creates a new note to a conversation.

Input Parameters:

• ConversationId: A conversation id in an inbox where the thread will be created.
• ThreadData: Customer thread data to create.Must include a field: text(str)

Output:

• ResourceId (string): Internal ID of the newly created thread.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Threads

Gets all threads from a HelpScout conversation using client credentials authentication.

Input Parameters:

• ConversationId: A conversation id in an inbox to get threads from.

Output:

• Threads (object-array): Thread data retrieved from HelpScout.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update a Thread

Updates a thread in HelpScout conversation by ID using client credentials authentication.

Input Parameters:

• ConversationId: A conversation id in an inbox.
• ThreadId: HelpScout thread ID.
• ThreadData: Thread data to update. Must include fields: op(str), path(str), value(any)

Output:

• Success (bool): Indicates whether the update was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

5. Example Usage

This section will guide you through creating a simple workflow to add a new customer to your Helpscout account.

The workflow will consist of a Start node, a Helpscout: Create a Customer node, and an Answer node.

1. Add the Tool Node

• In the workflow canvas, click the "+" button to add a new node.
• In the panel that appears, select the "Tools" tab.
• Find and select "Helpscout" from the list of tools.
• From the list of supported operations for Helpscout, click on "Create a Customer" to add the node to your canvas.

2. Configure the Node

• Click on the newly added "Create a Customer" node to open its configuration panel on the right.
• Credentials: Find the credentials field at the top of the panel. Click the dropdown menu and select your pre-configured Helpscout credentials.
• Parameters: Fill in the required input parameters for the action.
  • CustomerData: This parameter requires a JSON object containing the new customer's details. You can construct this object using data from previous nodes or enter it manually. For example, to create a customer named Jane Doe with a work email, you would enter:

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas will disappear.
• Click the "Run Test" button in the top-right corner of the canvas to execute the workflow.
• After a successful run, you can click the logs icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the operation was successful and retrieving the new customer's data.

After completing these steps, your workflow is fully configured. When executed, it will create a new customer in your Helpscout account with the specified details.

6. FAQs

Q: Why am I getting a 401 Unauthorized error?

A: This error typically indicates an issue with your credentials. Please check the following:

• Ensure your API key is correct and has not expired.
• Verify that the credentials selected in the node configuration match the intended Helpscout account.
• Confirm that your Helpscout user role has the necessary permissions to perform the requested action.

Q: How can I find my Mailbox ID?

A: You can find the Mailbox ID in the URL when viewing a mailbox in the Helpscout web application.

• Navigate to the desired mailbox in Helpscout.
• Look at the URL in your browser's address bar. It will look something like https://secure.helpscout.net/mailbox/123456/....
• The number immediately following /mailbox/ is your Mailbox ID. In this example, it is 123456.

Q: What is the required format for the CustomerData or ConversationData objects?

A: The structure of these objects must match the schema expected by the Helpscout API. For a complete list of available fields and their data types, it is best to consult the official Helpscout API documentation. A basic example for creating a customer is provided in the "Example Usage" section above.

7. Official Documentation

For more detailed information about the Helpscout API, including all available endpoints and data schemas, please refer to the Helpscout Official API Documentation.