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. Fires when a new conversation is created in any mailbox on the connected account.
• helpscout/customer-reply-created. Fires when a customer adds a reply thread to an existing conversation.
• helpscout/customer-created. Fires when a new customer record is created in the connected account.

Each trigger verifies the inbound POST against the Help Scout webhook signature. In Help Scout, open Profile -> My Apps -> Webhooks, click Create Webhook, paste the TaskJuice incoming webhook URL, set the secret to the value shown in the TaskJuice connection setup, and subscribe to the convo.created, convo.customer.reply.created, and customer.created events. Help Scout signs the raw request body with HMAC-SHA1 and delivers the base64 digest in the X-HelpScout-Signature header.

Actions

• helpscout/list-conversations. List conversations across the connected account, filtered by mailbox, status, tag, assignee, or last-modified timestamp.
• helpscout/get-conversation. Look up a single conversation by ID, optionally embedding the conversation's threads.
• helpscout/create-conversation. Open a new conversation in a specified mailbox with an initial customer or staff thread.
• helpscout/update-conversation. Patch a conversation's subject, status, assignee, mailbox, or primary customer via the Help Scout JSON-Patch endpoint.
• helpscout/delete-conversation. Permanently delete a conversation. Deleted conversations cannot be restored.
• helpscout/add-reply. Post a customer-facing reply thread on an existing conversation, optionally as a draft.
• helpscout/list-customers. List customers in the connected account, filtered by email, mailbox, name, or last-modified timestamp.
• helpscout/create-customer. Create a new customer with name, email, organization, job title, and optional additional emails, phone numbers, and address.

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.