Overdesk Docs

Appearance

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 or as an unsent draft reply, under the agent account you choose.

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.
  • For draft replies in the composer, version 1.0.103 or newer of that module (see below).
  • 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 Post drafts 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 drafts and notes 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 ​

Drafts arrive as internal notes by default, and notes work on every version of the module. FreeScout can also hold an unsent draft reply in the composer: choose Draft reply, ready to edit and send under Guardrails → Send mode. Placing a draft reply leaves the conversation's status exactly as it was, so the ticket stays in the queue your agent is working from.

Draft replies need the API and Webhooks module at version 1.0.103 or newer. An older version may not recognise the reply as a draft, and FreeScout sends a reply it does not recognise, so it could reach your customer unread. If your module is older, keep the internal note setting. Overdesk shows the same warning beside the setting.

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

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, and pointing a FreeScout webhook at Overdesk. The steps are in Real-time updates with webhooks.

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 drafts should appear 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.