Help Scout Integration

Automatically turn a form submission into a new Help Scout conversation, so customer inquiries land directly in your support helpdesk instead of (or alongside) an email notification. Help Scout requires Contactum Pro with the Help Scout module enabled.

---

Requirements #

• Contactum Pro, with the Help Scout module active (Contactum → Modules)
• An active Help Scout account — sign up here if you don’t have one
• A Help Scout App ID and App Secret

---

1. Create a Help Scout App #

Help Scout authenticates via OAuth2, but Contactum uses the Client Credentials grant — the one OAuth2 flow that doesn’t need you to click through an interactive “Authorize” redirect. You just generate an App ID/Secret pair once and paste them in.

1. Log in to Help Scout and go to My Apps.
2. Create a new app (any name, e.g. “Contactum”).
3. Copy the generated App ID and App Secret.

---

2. Connect Help Scout in Contactum #

1. Go to Contactum → Settings → Integrations → Help Scout.
2. Paste in your App ID and App Secret.
3. Click Save Settings.

Contactum exchanges these credentials for an access token to confirm they’re valid before saving. You’ll see “Your Help Scout credentials have been verified and saved” and the status badge turns green. If the credentials are wrong, the error Help Scout returns is shown instead.

To disconnect, click Disconnect Help Scout — this clears the stored credentials and stops all conversation creation until reconnected.

---

3. Enable Help Scout on a Specific Form #

1. Open the form in the builder.
2. Go to Form Settings → Integrations.
3. Toggle Help Scout on, then click Configure.

---

4. Configure Field Mapping #

Field	Required	Description
Mailbox	Yes	Which Help Scout mailbox the conversation is created in. Click the refresh icon to load your account’s mailboxes
Email	Yes	Map to the form field collecting the customer’s email address
First Name	No	Map to a text or name field
Last Name	No	Map to a text or name field
Subject	No	The new conversation’s subject line — defaults to “New form submission” if left blank

Use the { } smart tag button under each field to map it to a form field, the same as any other Contactum integration.

---

5. How It Works #

When a visitor submits the form:

1. Contactum checks the form has Help Scout enabled and that both Mailbox and Email are configured.
2. The mapped smart tags (Email, First Name, Last Name, Subject) are resolved against the submission.
3. A new Help Scout conversation is created in the selected mailbox, with the customer’s email as the requester and an email-type conversation.
4. The conversation’s first message is a plain-text listing of every field the visitor submitted (Label: value, one per line) — so the support agent sees the full submission without needing to look anywhere else.
5. If Subject was left blank, “New form submission” is used.

A failed Help Scout request does not block the form submission — the visitor still sees a normal success confirmation even if conversation creation fails. Failures are recorded in Contactum’s API Log (Contactum → Tools → API Log, if available in your version) and can be retried from there.

---

Troubleshooting #

“Your Help Scout credentials are not valid” #

• Reconfirm the App ID and App Secret were copied exactly from Help Scout → My Apps → your app.
• If the app was deleted or its secret regenerated in Help Scout, update it in Contactum with the new values.

Mailbox dropdown is empty #

• Confirm the global credentials show the green verified badge before clicking refresh.
• Confirm your Help Scout account actually has at least one mailbox set up.

Conversations aren’t appearing in Help Scout #

1. Confirm the form has Help Scout toggled on and was saved.
2. Confirm both Mailbox and Email are mapped in the Configure dialog — the integration silently does nothing if either is missing.
3. Submit a test entry with a real email address, then check the selected mailbox in Help Scout.
4. Check the API Log for a logged failure and its error message.

---

Notes #

• Requires Contactum Pro with the Help Scout module active — not available in the free plugin.
• Auth method: OAuth2 Client Credentials grant. The access token is cached and automatically refreshed — you never need to re-authenticate manually after the initial App ID/Secret setup, unless you regenerate the secret in Help Scout.
• API version: Help Scout Mailbox API v2 (https://api.helpscout.net/v2/).
• Credentials storage: appId and appSecret are stored in wp_options under the key contactum_helpscout.
• A failed conversation never blocks the submission — the visitor’s experience is unaffected by a Help Scout outage or misconfiguration.