Help Scout Integration for WooCommerce

Help Scout Integration for WooCommerce connects your store to a Help Scout mailbox. Customers can start support conversations from their orders or a support form, and logged-in customers can view and reply to conversations from My Account. Store staff can create conversations from WooCommerce orders. An optional Help Scout custom sidebar can display matching WooCommerce customer and order information while an agent works on a conversation.

This guide covers installation, Help Scout authentication, mailbox settings, customer-facing support options, the optional sidebar, and troubleshooting. The instructions reflect the current configuration and security controls.

• An active WooCommerce store with Help Scout Integration for WooCommerce installed.
• An active Help Scout account with permission to create an OAuth application and access the mailbox you want to connect.
• WordPress administrator or store manager access with permission to manage WooCommerce settings.
• Access to your site’s HTTPS address and the WordPress admin area.
• If you want the customer-data sidebar inside Help Scout, access to create and install a Help Scout custom app.

1. Download the extension ZIP file from your WooCommerce account.
2. In WordPress, go to Plugins > Add New Plugin > Upload Plugin.
3. Choose the ZIP file, select Install Now, and then Activate Plugin.
4. Go to WooCommerce > Settings > Integration > Help Scout. Depending on the WooCommerce admin layout, the tab may be labeled Integrations.

Leave this settings page open while you create your Help Scout application. It displays the redirect URL needed in the next step.

The extension uses a Help Scout OAuth application rather than a legacy API key.

1. Sign in to Help Scout with an account permitted to create applications.
2. Open your profile menu, select Your Profile, then open My Apps.
3. Select Create My App.
4. Enter an identifiable application name, such as WooCommerce store support.
5. For the redirect URL, copy the Redirect URL shown on the WooCommerce Help Scout settings page. Use the URL shown on your site rather than typing or guessing it. It ends in /wp-content/plugins/woocommerce-help-scout/allow-access.php and must retain any WordPress subdirectory.
6. Save the Help Scout application, then copy its App ID and App Secret.

In WooCommerce, enter the App ID in APP Key and the App Secret in APP Secret. Do not substitute a Help Scout Docs API key or a WooCommerce REST API key for these values.

1. Open the mailbox you want WooCommerce support conversations to use.
2. In Help Scout, navigate to the mailbox settings and open Edit Mailbox.
3. Find the numeric mailbox ID in the browser address, for example https://secure.helpscout.net/settings/mailbox/123456/.
4. Enter only the numeric ID (in this example, 123456) into the WooCommerce Mailbox ID field.

Use a mailbox that the connected Help Scout account can access. The extension’s settings accept one Mailbox ID.

Return to WooCommerce > Settings > Integration > Help Scout and configure the following fields.

• APP Key: Enter the App ID from your Help Scout OAuth application.
• APP Secret: Enter its App Secret. Treat this as a credential and do not share it in support tickets or screenshots.
• Mailbox ID: Enter the numeric ID of the mailbox that should receive support conversations.
• API Handler: Keep Standard selected. Use Custom (v2) only if OPMC Support directs you to do so for a particular issue.
• Assigned To (optional): Enter a Help Scout user ID if you want new conversations assigned to that user. The ID can be found in the user’s Help Scout profile URL. Leave blank to create conversations without a specified assignee.
• Conversation CC (optional): Enter additional recipient email addresses, separated by commas.
• Conversation BCC (optional): Enter hidden-copy recipient email addresses, separated by commas.
• Debug Log: Leave disabled during normal operation. Enable temporarily when investigating a problem.
• Legacy Signature Fallback: Leave disabled. This deprecated option is not part of normal setup and is intended only for explicitly directed legacy compatibility work.
• Hide Support Conversations From Sidebar: Enable only if you do not want the Support Conversations item shown in the customer’s My Account navigation.
• Hide Help Button From Order Details Page: Enable only if you do not want the Get Help action on customer order details.

1. Select Save changes.
2. Once the App Key and App Secret have been saved, select Allow Access on the same settings page.
3. Sign in to Help Scout if prompted and approve the connection.
4. Return to WooCommerce and check for the successful connection notice.

1. In a separate browser session, sign in to a test customer account on your WooCommerce store.
2. Open My Account > Orders, then select View on a test order.
3. Select Get Help, if shown, and submit a short test question.
4. Open the configured Help Scout mailbox and confirm that the conversation was created.
5. Reply to the conversation from Help Scout and confirm that the customer can view the conversation and send a reply from My Account > Support Conversations.

If the test fails, see Troubleshooting below before changing the API Handler.

The custom Help Scout sidebar lets agents view available WooCommerce information for the contact in a conversation, including customer details, recent orders, and active subscriptions when the matching data and required extension are available. This feature requires a separate Help Scout custom app in addition to the OAuth application created earlier.

1. In Help Scout, open the area for managing or creating Custom Apps.
2. Create an app using the Dynamic Content type, where supported by your Help Scout account.
3. Enter a descriptive name, such as WooCommerce customer information.
4. For the content callback URL, enter your store’s URL followed by /wp-json/helpscout/v1/get-customer-order-data. For example: https://yourstore.example/wp-json/helpscout/v1/get-customer-order-data. If WordPress is installed in a subdirectory, include that directory in the URL.
5. Configure the custom app’s shared signature secret to correspond to the WooCommerce Help Scout APP Secret, following the supported authentication settings for your Help Scout custom app.
6. Assign or install the custom app to the mailbox where your support team works, and save the app.
7. Open a conversation for a customer with a known WooCommerce order to check whether the sidebar displays matching information.

The newer callback URL above is the intended endpoint for the current integration. The older /wp-json/helpscout/v1/get-order-and-customer-data endpoint is retained as a legacy alias and should not be used for a new sidebar configuration.

• Check that the Help Scout contact email matches the customer’s WooCommerce account email or the billing email used on their orders.
• Check that the contact actually has orders on the connected WooCommerce store.
• For guest purchases, use the original billing email; guest orders do not always have a registered WordPress customer account.
• If you use WooCommerce Subscriptions, confirm that the relevant subscription belongs to the matching customer account.
• Verify that the custom app was installed in the correct Help Scout mailbox.
• Confirm your web application firewall or security plugin is not blocking authenticated requests to the REST callback.

1. Sign in to My Account and open Orders.
2. Choose an order, then select Get Help.
3. Enter a subject and a description of the issue, then submit the conversation.
4. Use Support Conversations in My Account to view and reply to accessible conversations.

The Get Help action is hidden when the corresponding plugin setting is enabled. In the Orders list, the extension may also display a Ticket/Conversation action that opens the support conversation area.

1. Go to WooCommerce > Orders and open the relevant order.
2. Locate the Help Scout conversation panel on the order screen.
3. Enter the subject and message, and submit it to the configured Help Scout mailbox.
4. Continue handling the conversation in Help Scout.

Order details can be included in the conversation to help the support team identify the purchase.

Logged-in customers can access My Account > Support Conversations to see their associated conversations and reply. The extension checks conversation ownership before displaying messages or accepting replies; a customer cannot access another customer’s conversation by changing its ID.

If a customer cannot see a conversation, verify that they are using the correct WooCommerce account and that the Help Scout customer email association is correct.

Add the following shortcode to a Shortcode block or to a page that processes WordPress shortcodes:

[wc_help_scout_form]

The form accepts support requests from logged-in customers and guests. When a logged-in customer has eligible orders, the form can offer an order selector. Visitors without an available order enter their name and email address. The form also includes subject, description, and file upload fields.

Supported attachment formats in the extension include JPG, JPEG, PNG, and PDF. Uploads are also subject to your site’s server and PHP upload limits.

1. Open Comments in WordPress admin.
2. Find the comment and select Create a Conversation in its Help Scout actions.
3. Check the confirmation notice and follow the link to Help Scout where available.

The comment must contain a valid author email address and message. For product comments, the extension may include related order information if a matching purchase is found.

1. Confirm both the APP Key and APP Secret are filled in, then Save changes.
2. Check that the redirect URL in Help Scout matches the exact redirect URL displayed by the extension. Pay particular attention to HTTPS, domain changes, and WordPress subdirectories.
3. Start Allow Access while signed in as a WooCommerce administrator or store manager, and finish the process using the same signed-in WordPress account.
4. If the connection reports an invalid state, return to the settings page and start Allow Access again. The authorization state is temporary and single-use.
5. If a token exchange fails, check the App ID, App Secret, and redirect URL before retrying.

• Confirm the extension is active and you are viewing an eligible order in the customer’s account.
• Check that Hide Help Button From Order Details Page is not selected.
• If the site has overridden WooCommerce order templates, test with an up-to-date default WooCommerce-compatible theme on staging.

• Check that Hide Support Conversations From Sidebar is not enabled.
• Confirm the customer is signed in.
• Visit Settings > Permalinks in WordPress and save the existing structure to refresh rewrite rules if the endpoint returns a 404.
• Check whether custom account navigation or theme overrides are hiding the menu item.

Confirm that the customer is signed in to the account associated with the conversation. The extension restricts conversation viewing and replies to the owner. If the conversation was created using a different email or Help Scout contact, check the customer association before retrying. Do not disable conversation access checks.

• Check the Help Scout contact email and WooCommerce billing email, especially for guest purchases.
• Confirm the custom app callback uses /wp-json/helpscout/v1/get-customer-order-data.
• Verify that the REST request reaches the store and passes its signature check.
• If HPOS is enabled, verify the order is accessible through the current WooCommerce order screens and that the email matches.
• Check whether the same customer has used multiple email addresses for purchases.

Verify the Help Scout custom app’s shared secret, callback URL, and the API Handler setting. Confirm that a security plugin or proxy is not stripping incoming authentication information. If the error continues, contact OPMC Support with the HTTP status and relevant redacted log entries. Do not send your APP Secret or authentication tokens.

This may indicate an outdated callback URL, a mistyped endpoint, or a REST request blocked by the site. Update the Help Scout custom app to the current callback shown above, confirm that WordPress REST API routes are accessible, and check for firewall or permalink problems. The deprecated WooCommerce Legacy REST API is not required for this extension’s current Help Scout sidebar endpoint.

• Confirm the shortcode is entered exactly as [wc_help_scout_form].
• Check the connected Help Scout mailbox and OAuth authorization.
• For attachments, use JPG, JPEG, PNG, or PDF files within the site’s permitted upload size.
• For order selection, confirm the customer is logged in and the orders belong to that account.
• If the form fails only with HPOS disabled, record that fact for OPMC Support; do not switch storage modes on a live store solely as a troubleshooting step.

1. Enable Debug Log under WooCommerce > Settings > Integration > Help Scout and save.
2. Reproduce the problem once.
3. Go to WooCommerce > Status > Logs and select the Help Scout-related log source or use the View Log link in the integration settings, if available.
4. Note the error message and time, and share only the relevant redacted entries with support.
5. Disable Debug Log after the investigation.

Never include App Secrets, access tokens, customer payment information, or other sensitive data in support requests.

If the steps above do not resolve the issue, contact support through your WooCommerce account and include:

• The Help Scout Integration for WooCommerce version and current WordPress, WooCommerce, and PHP versions.
• Whether you are using HPOS or traditional order storage.
• The API Handler selected in the plugin settings.
• The affected feature: OAuth connection, order form, My Account conversations, shortcode, or Help Scout sidebar.
• The precise error message, HTTP status (if applicable), and a brief description of how to reproduce it.
• Relevant redacted WooCommerce logs and whether the issue occurs on a staging site.

Do not include Help Scout App Secrets, access tokens, or unredacted customer information.