Skip to content

FreeScout ​

FreeScout runs on your own server, so Overdesk connects to it with your instance's address and an API key. It reads your conversations, learns from your past answers, and places each draft on the conversation as an internal note, under the agent account you choose. For the overview of Overdesk with FreeScout, see the FreeScout page on overdesk.io.

What your FreeScout needs ​

  • An address that starts with https. Overdesk will not send your API key over an unencrypted connection.
  • FreeScout's API and Webhooks module. If API & Webhooks is missing from Manage, then Settings, the module is not installed yet: add it under Manage, then Modules.
  • Optional: FreeScout's Tags module, if you want Overdesk to label conversations.

Connect FreeScout ​

You need to be an owner or admin in Overdesk.

  1. In FreeScout, open Manage, then Settings, then API & Webhooks, and copy the API Key shown at the top.
  2. In Overdesk, open Integrations and choose FreeScout.
  3. Enter the FreeScout address: the address you use to open FreeScout in a browser, such as https://support.yourcompany.com.
  4. Paste the API key.
  5. In Overdesk posts as, enter the email address of an existing FreeScout user. A FreeScout API key does not belong to any one person, so this is the account your notes, and any reply Overdesk sends, appear under.
  6. Choose Connect.

Once connected, the FreeScout page on Integrations shows your instance's address and the mailboxes Overdesk can read.

What joins your knowledge base ​

Your past conversations, through Sync past conversations, every night at 03:00. FreeScout has no help center and no API for saved replies, so those two sources are not available here. Your docs site and the other knowledge sources work the same as on any help desk.

Where drafts appear ​

Every draft arrives as an internal note, and so does every follow-up nudge Overdesk does not send, with sending on or off. Draft reply, ready to edit and send under Guardrails → Send mode is a Help Scout option; on FreeScout your team keeps receiving notes whichever you choose. Overdesk cannot read which version of the API and Webhooks module you run, and a module older than 1.0.103 publishes a draft reply to the customer instead of holding it, so Overdesk places none. A note never reaches your customer on any version. See Where drafts go.

If you edit or discard a draft from its page in Overdesk, Overdesk adds a note to the conversation saying what changed.

Sending replies ​

Once your workspace turns sending on, Overdesk sends the replies your guardrails approve on email conversations. It sends them as the account you entered under Overdesk posts as. A phone, chat or custom conversation waits for your team. After a reply the conversation is set to Pending. Under After Overdesk sends a reply you can choose Active, Closed or Leave as is instead, and Leave as is keeps the status the conversation had. A reply that hands the conversation to a teammate leaves it Active, whatever you chose.

Inboxes, tags and escalation ​

  • In Allowed inboxes, enter all or list mailbox numbers. A mailbox's number is in the address bar when you open it in FreeScout. With a second help desk connected, write them like FreeScout:3.
  • Without the Tags module, Overdesk still reads your conversations, writes drafts and reports on what your team is asked about, but it cannot label conversations inside FreeScout.
  • Escalation rules can assign a conversation to a FreeScout user. FreeScout has no teams, so targets are people. See Escalation.

Real-time updates ​

Right after you connect, the FreeScout page shows One more step for drafts as customers write in. That step is saving FreeScout's Secret Key in Overdesk, so it can check that each event really came from your instance, then connecting FreeScout again so Overdesk can add its webhook to your instance. The steps are in Real-time updates with webhooks. Only a note a person types in the FreeScout web app, or sends by email, asks @Overdesk. A note another app adds through the API does not.

If the connection is refused ​

FreeScout's answers mean something specific on a self-hosted instance, and the form says which:

  • When the API key is rejected: FreeScout regenerates its API key when the server is rebuilt, and an administrator can regenerate it by hand. Copy the current key from API & Webhooks and connect again. A rebuild changes the Secret Key on that page too, so update it in Settings → Developers.
  • When the address answers, but not with the FreeScout API: either the API and Webhooks module is not installed, or the address points somewhere other than the FreeScout home page.
  • When the request is refused rather than the key: FreeScout only answers on the hostnames it trusts. If it sits behind a proxy or answers on a second hostname, add that hostname to the trusted hosts setting in the server's environment file. A security plugin or firewall rule looks the same from Overdesk's side.
  • When no user has that email address: use the address of the agent account Overdesk should post as. If it is definitely right, the module may be too old to look users up by address, and updating it under Manage, then Modules fixes it.

Disconnecting FreeScout deletes its credentials and everything it put into your knowledge base.