Help Scout integration

What it does

The Help Scout integration lets you run mailbox automations on behalf of any client whose support inbox you manage. Connect a Help Scout account once, then create, update, and delete conversations, post agent replies, manage customers, and route live mailbox events (new conversation, customer reply, new customer) into the rest of your workflow without writing any code.

Connect a Help Scout account

1. In TaskJuice, open Settings -> Connections and choose Add connection -> Help Scout.
2. You will be redirected to secure.helpscout.net to sign in to the Help Scout account TaskJuice should act on.
3. Approve the scopes requested by the TaskJuice OAuth application. Help Scout returns to TaskJuice with an access token tied to the authorizing account.

The connection is read- and write-capable across conversations, customers, mailboxes, and threads in the authorizing account. Rotate or revoke access from Help Scout Profile -> My Apps -> Authorized Applications at any time.

Triggers

• helpscout/conversation-created. Triggers when a new conversation is created in a Help Scout inbox.
• helpscout/customer-reply-created. Triggers when a customer adds a reply thread to an existing conversation.
• helpscout/customer-created. Triggers when a new customer record is created.
• helpscout/conversation-assigned. Triggers when a conversation is assigned to a user.
• helpscout/conversation-status-changed. Triggers when a conversation's status changes (active, pending, closed, spam).
• helpscout/conversation-tags-updated. Triggers when the tags on a conversation change.
• helpscout/agent-reply-created. Triggers when a user (agent) adds a reply thread to a conversation.
• helpscout/note-created. Triggers when an internal note is added to a conversation.
• helpscout/conversation-deleted. Triggers when a conversation is deleted.
• helpscout/conversation-merged. Triggers when a conversation is merged into another conversation.
• helpscout/conversation-moved. Triggers when a conversation is moved to a different inbox.
• helpscout/satisfaction-rating-received. Triggers when a customer submits a satisfaction rating.
• helpscout/conversation-custom-fields-updated. Triggers when the custom fields on a conversation change.
• helpscout/customer-updated. Triggers when an existing customer record changes.
• helpscout/customer-deleted. Triggers when a customer record is deleted.
• helpscout/tag-created. Triggers when a new tag is created in the account.
• helpscout/tag-updated. Triggers when an existing tag is renamed or otherwise edited.
• helpscout/tag-deleted. Triggers when a tag is deleted from the account.
• helpscout/organization-created. Triggers when a new organization is created.
• helpscout/organization-updated. Triggers when an existing organization is edited.
• helpscout/organization-deleted. Triggers when an organization is deleted.
• helpscout/survey-response-received. Triggers when a customer answers a Help Scout Message survey.
• helpscout/user-status-changed. Triggers when a user changes their email or chat availability.
• helpscout/beacon-chat-created. Triggers when a customer opens a new Beacon chat.
• helpscout/beacon-chat-customer-replied. Triggers when a customer replies on an existing Beacon chat.

TaskJuice registers the webhook for you when you publish a workflow and removes it when you unpublish — one account-level webhook subscribed to exactly the events your published triggers use, updated in place as workflows change. Nothing needs configuring inside Help Scout. Each delivery is verified against the secret TaskJuice minted at registration: Help Scout signs the raw request body with HMAC-SHA1 and delivers the base64 digest in the X-HelpScout-Signature header.

If you prefer to manage the webhook yourself, open Profile -> My Apps -> Webhooks in Help Scout, create one pointing at the TaskJuice incoming webhook URL, and paste its secret into the TaskJuice connection setup.

Actions

• helpscout/list-conversations. Lists conversations across the Help Scout account, paginated by page number (50 per page).
• helpscout/get-conversation. Retrieves a single Help Scout conversation by ID, optionally including embedded threads.
• helpscout/create-conversation. Creates a new Help Scout conversation in the specified mailbox.
• helpscout/update-conversation. Updates a Help Scout conversation field (subject, status, assignee, mailbox, or customer) via the JSON-Patch endpoint.
• helpscout/delete-conversation. Permanently deletes a Help Scout conversation.
• helpscout/add-reply. Adds a customer-facing reply thread to an existing Help Scout conversation.
• helpscout/list-customers. Lists customers in the Help Scout account, paginated by page number.
• helpscout/create-customer. Creates a new customer in the Help Scout account.
• helpscout/get-customer. Retrieves a single Help Scout customer by ID, including embedded emails, phones, chats, websites and properties.
• helpscout/overwrite-customer. Replaces a Help Scout customer record wholesale.
• helpscout/add-note. Adds an internal note thread to a Help Scout conversation.
• helpscout/list-threads. Lists every thread on a Help Scout conversation, paginated by page number.
• helpscout/create-chat-thread. Appends a chat thread to a Help Scout conversation on behalf of a customer.
• helpscout/create-phone-thread. Logs a phone conversation as a thread on a Help Scout conversation.
• helpscout/list-mailboxes. Lists the Help Scout inboxes (mailboxes) the connected account can see.
• helpscout/get-mailbox. Retrieves a single Help Scout inbox (mailbox) by ID.
• helpscout/list-tags. Lists every tag defined in the Help Scout account, with the conversation count per tag.
• helpscout/search-conversations. Searches Help Scout conversations with the advanced query syntax, with optional inbox, status, tag and assignee filters.
• helpscout/search-customers. Searches Help Scout customers with the advanced query syntax, with optional inbox and name filters.
• helpscout/list-users. Lists the users (agents) on the Help Scout account, optionally filtered by email or inbox.
• helpscout/get-user. Retrieves a single Help Scout user (agent) by ID.
• helpscout/update-conversation-tags. Replaces the tag set on a Help Scout conversation.
• helpscout/update-conversation-custom-fields. Replaces the custom-field values on a Help Scout conversation.
• helpscout/snooze-conversation. Snoozes a Help Scout conversation until a future timestamp, optionally waking it on the next customer reply.
• helpscout/list-customer-emails. Lists every email on a Help Scout customer.
• helpscout/create-customer-email. Adds a email to a Help Scout customer.
• helpscout/update-customer-email. Replaces a email on a Help Scout customer.
• helpscout/delete-customer-email. Permanently removes a email from a Help Scout customer.
• helpscout/list-customer-phones. Lists every phone on a Help Scout customer.
• helpscout/create-customer-phone. Adds a phone to a Help Scout customer.
• helpscout/update-customer-phone. Replaces a phone on a Help Scout customer.
• helpscout/delete-customer-phone. Permanently removes a phone from a Help Scout customer.
• helpscout/list-customer-websites. Lists every website on a Help Scout customer.
• helpscout/create-customer-website. Adds a website to a Help Scout customer.
• helpscout/update-customer-website. Replaces a website on a Help Scout customer.
• helpscout/delete-customer-website. Permanently removes a website from a Help Scout customer.
• helpscout/list-customer-social-profiles. Lists every social profile on a Help Scout customer.
• helpscout/create-customer-social-profile. Adds a social profile to a Help Scout customer.
• helpscout/update-customer-social-profile. Replaces a social profile on a Help Scout customer.
• helpscout/delete-customer-social-profile. Permanently removes a social profile from a Help Scout customer.
• helpscout/list-customer-chats. Lists every chat handle on a Help Scout customer.
• helpscout/create-customer-chat. Adds a chat handle to a Help Scout customer.
• helpscout/update-customer-chat. Replaces a chat handle on a Help Scout customer.
• helpscout/delete-customer-chat. Permanently removes a chat handle from a Help Scout customer.
• helpscout/get-customer-address. Retrieves a Help Scout customer's mailing address.
• helpscout/create-customer-address. Sets a Help Scout customer's mailing address.
• helpscout/update-customer-address. Replaces a Help Scout customer's mailing address.
• helpscout/delete-customer-address. Permanently removes a Help Scout customer's mailing address.
• helpscout/list-organizations. Lists the organizations in a Help Scout account, newest interaction first.
• helpscout/get-organization. Retrieves a single Help Scout organization by ID, optionally with counts and property values.
• helpscout/create-organization. Creates a Help Scout organization.
• helpscout/update-organization. Replaces a Help Scout organization.
• helpscout/delete-organization. Permanently deletes a Help Scout organization.
• helpscout/list-organization-conversations. Lists the conversations belonging to a Help Scout organization.
• helpscout/list-organization-customers. Lists the customers belonging to a Help Scout organization.
• helpscout/get-resource-owner. Retrieves the Help Scout user the connected credential belongs to.
• helpscout/create-user. Invites a new user to the Help Scout account.
• helpscout/delete-user. Permanently removes a user from the Help Scout account.
• helpscout/list-user-statuses. Lists the email and chat availability status of every user in the Help Scout account.
• helpscout/get-user-status. Retrieves one Help Scout user's email and chat availability status.
• helpscout/set-user-status. Sets a Help Scout user's email or chat availability status.
• helpscout/list-teams. Lists the teams in a Help Scout account.
• helpscout/list-team-members. Lists the users who belong to a Help Scout team.
• helpscout/update-team-members. Replaces the full member list of a Help Scout team.
• helpscout/list-system-users. Lists the Help Scout system users, the non-human actors that appear as the author of automated activity.
• helpscout/get-system-user. Retrieves a single Help Scout system user by ID.
• helpscout/get-tag. Retrieves a single Help Scout tag by ID.
• helpscout/get-satisfaction-rating. Retrieves a single Help Scout satisfaction rating by ID.
• helpscout/list-workflows. Lists the workflows configured in a Help Scout account.
• helpscout/run-workflow. Runs a manual Help Scout workflow against a set of conversations.
• helpscout/update-workflow-status. Activates or deactivates a Help Scout workflow.
• helpscout/list-inbox-folders. Lists the folders in a Help Scout inbox, with conversation counts.
• helpscout/list-inbox-custom-fields. Lists the custom fields defined on a Help Scout inbox, including each dropdown field's options.
• helpscout/list-customer-properties. Lists the custom property definitions available on Help Scout customers.
• helpscout/create-customer-property. Defines a new custom property on Help Scout customers.
• helpscout/delete-customer-property. Permanently deletes a customer property definition and every value stored against it.
• helpscout/create-customer-thread. Adds a thread to a Help Scout conversation as if the customer had sent it.
• helpscout/update-thread. Edits the text of a Help Scout thread, or hides and unhides it.
• helpscout/schedule-thread. Schedules a draft Help Scout thread to send at a future time.
• helpscout/unschedule-thread. Cancels a scheduled send on a Help Scout thread, leaving it as a draft.
• helpscout/publish-scheduled-thread. Sends a scheduled Help Scout thread immediately.
• helpscout/unsnooze-conversation. Removes the snooze on a Help Scout conversation and returns it to the appropriate folder.
• helpscout/upload-attachment. Attaches a file to a Help Scout thread.
• helpscout/get-attachment-data. Retrieves the metadata and base64 contents of a Help Scout attachment.
• helpscout/delete-attachment. Permanently removes an attachment from a Help Scout thread.
• helpscout/delete-customer. Hard-deletes a Help Scout customer along with their conversations and microsurvey responses.
• helpscout/get-inbox-routing. Reads the automatic assignment configuration on a Help Scout inbox, including who is currently eligible for new conversations.
• helpscout/update-inbox-routing. Replaces the automatic assignment configuration on a Help Scout inbox.
• helpscout/list-webhooks. Lists the webhooks registered on a Help Scout account.
• helpscout/get-webhook. Retrieves a single Help Scout webhook registration by ID.
• helpscout/create-webhook. Registers a webhook on a Help Scout account.
• helpscout/update-webhook. Replaces a Help Scout webhook registration.
• helpscout/delete-webhook. Permanently removes a Help Scout webhook registration.

Known limitations

• Rate limits follow Help Scout's documented quotas (400 requests per minute per OAuth client). TaskJuice retries on 429 responses honoring the Retry-After header.
• Help Scout conversations are immutable through a single PATCH call; the update-conversation action applies one JSON-Patch operation per invocation. Chain multiple actions to update several fields.
• Webhook signing uses HMAC-SHA1 (base64) on the raw body. The signature is delivered in X-HelpScout-Signature and is automatically verified by TaskJuice's inbound auth recipe.
• The OAuth access token expires after 48 hours. TaskJuice refreshes the token automatically using the long-lived refresh token returned during the initial authorization.