Connect FreeScout to Website Toolkit

If you run your own FreeScout help desk, you can connect it to the Support inbox in Website Toolkit instead of forwarding email. Each new ticket is matched to the right client site and turned into a task on that site’s feedback dashboard. When you complete the task, a note goes back on the ticket, and the ticket can be closed for you.

Website Toolkit needs three things from your FreeScout: its address, an API key, and (optionally) the webhook secret. Here’s where to find them.

Before you start

  • FreeScout must be reachable from the internet at a public address such as https://help.yourdomain.com. A FreeScout that only runs on your own network or a private IP can’t be connected.
  • The API & Webhooks module. FreeScout’s API isn’t built in. It comes from the official API & Webhooks module, a paid add-on with a lifetime licence for one FreeScout install.
  • Your sites added to your Website Toolkit account, so tickets have somewhere to go.

1. Install the API & Webhooks module

  1. Buy the module from the API & Webhooks module page on freescout.net. You’ll get a licence key.
  2. In FreeScout, open Manage → Modules.
  3. Find API & Webhooks, install it, enter your licence key and activate it.

Once it’s active, an API & Webhooks page appears under Manage (on some versions it’s under Manage → Settings).

2. Get the API key and webhook secret

  1. Open Manage → API & Webhooks.
  2. Copy the API Key. If there isn’t one yet, generate it.
  3. Copy the webhook secret from the same page, if it shows one.

The API key gives full access to your FreeScout, so treat it like a password.

3. Connect it in Website Toolkit

  1. In your client portal, open the Support inbox tab.
  2. In the Help desk card, click Connect FreeScout.
  3. Fill in:
    • FreeScout address: the address you open FreeScout at, e.g. https://help.yourdomain.com
    • API key: from step 2
    • Webhook secret (optional): from step 2
  4. Click Connect FreeScout.

Website Toolkit checks the details by reading your mailbox list before it saves anything. It then registers a webhook in your FreeScout, so new tickets and customer replies arrive straight away, and also checks every 15 minutes in case one was missed. On the first check it brings in open tickets from the last 7 days.

Why add the webhook secret? FreeScout signs every webhook with it. With the secret, Website Toolkit can check each webhook really came from your FreeScout and ignore anything else. Without it, the connection still works, and the card reminds you that the secret is missing.

4. Match mailboxes to sites

If you run a mailbox per client, pick the site for each one under Which site is each mailbox for? and click Save sites. That’s the most reliable way to match tickets.

For a shared mailbox, leave it on Work it out from each ticket. Website Toolkit matches each ticket by a sender you’ve assigned before, the customer’s email domain, the website on their FreeScout customer profile, or a site named in the message. Anything it can’t place waits under Needs attention for you to assign.

5. Choose what happens when a task is done

Completing a task adds a note to its ticket saying the change is complete. Tick Close the ticket when its task is completed to have the ticket closed as well.

If something goes wrong

  • “FreeScout refused the API key”: copy the key again from Manage → API & Webhooks. If it was regenerated, the old one stops working.
  • “No FreeScout API at that address”: the API & Webhooks module isn’t installed or active, or the address is wrong. Use the address you sign in to FreeScout at, without anything after the domain unless FreeScout is installed in a subfolder.
  • “Checking every 15 minutes” on the connection: the webhook couldn’t be registered, so tickets arrive on the next check instead of straight away. Check the webhook list under Manage → API & Webhooks. FreeScout also sends webhooks from its background jobs, so make sure its scheduled task (cron) is running.
  • To disconnect, click Disconnect on the Help desk card. Website Toolkit removes its webhook from your FreeScout, and tasks already created stay on your dashboards. To revoke access completely, regenerate the API key in FreeScout.

← Back to all posts