How to connect Help Scout Docs and publish to it

Help Scout Docs hosts your knowledge base. Workover works with the same articles: it imports them from the collections you choose, and publishing a document from Workover updates its article in Help Scout, either live or as a Help Scout draft for someone to publish there. This page covers connecting a project to your Help Scout Docs site, editing articles, and publishing them back.

Before you start:

  • You need a Docs API key. In Help Scout, click your avatar, choose Your Profile, then Security and Access, and copy the key under Docs API. If you do not see one, ask your Help Scout account owner or an administrator for the Docs: Create new, edit settings & Collections permission. The key acts as its owner, so that person needs that permission for as long as the project stays connected.
  • Publishing needs an active plan or trial on your workspace.

Connect a project to Help Scout Docs

  1. Create a project: choose Website, enter your knowledge base’s address in Website link, pick Help Scout Docs as the CMS, and click Connect to Help Scout Docs. For an existing project that is not connected to a site, open Project settings and click Connect to Help Scout Docs in the Help Scout Docs card.
  2. Paste your Docs API key and click Continue. If your workspace has already connected Help Scout Docs, this step is skipped.
  3. If your Help Scout account has more than one Docs site, choose one under Site.
  4. Under Collections, choose the collections to sync. Each one shows how many articles it holds, and whether it is private.
  5. Click Import collections.

The import runs in the background: articles appear in the project as they arrive. A large knowledge base takes a few minutes. When an article has an unpublished draft in Help Scout, Workover imports the draft, because that is where your team’s latest words are. An import stops at 3,000 articles per collection.

To change the collections later, open Project settings and click Change collections or settings in the Help Scout Docs card.

Edit an article

Write as you would anywhere in Workover. Help Scout’s blocks appear in the editor as themselves:

  • Callouts keep their color (blue, green, gray, red, or yellow), and their text is editable.
  • HTML blocks show a preview of what they render. Click Edit HTML to change the markup; it is published to Help Scout exactly as you write it. Scripts in an HTML block never run in Workover.
  • Quotes, code blocks, tables, dividers, images, and videos work as they do in any document.

To insert a Help Scout block, type / and pick it from the menu: a Blue, Green, Gray, Red, or Yellow callout, or an HTML block. These entries appear only in a project connected to Help Scout Docs.

Choose what the article publishes

Open the document and click the Help Scout tab in the editor’s side panel. It shows every option Help Scout has for an article:

  • When you publish: Update the live article writes the article in Help Scout, text and settings. Save as a Help Scout draft saves the text as a draft in Help Scout, for someone to publish there.
  • Status: Published or Not published. A draft save never changes the status of an article already in Help Scout.
  • Slug: the end of the article’s address. Leave it empty to follow the title.
  • Collection: where the article lives. It can be chosen only before the article’s first publish, because Help Scout cannot move an article to another collection.
  • Categories, Keywords, and Related articles.

Changes save as you make them and are sent on the next publish. Until then, the tab lists the ones not yet sent. Options you have not changed are not sent, so a publish never clears categories, keywords, or related articles that someone set in Help Scout.

Each article makes its own choice in When you publish. An article that has never chosen updates the live article.

Publish an article

In the Help Scout tab, click Create in Help Scout for a new article, or Update article (Save as Help Scout draft when the article saves drafts) for one already in Help Scout. An article’s first publish always creates it in Help Scout, with the Status you chose. Save as a Help Scout draft applies only after that. For a document that is not in Help Scout yet, choose its Collection first when the project syncs more than one.

Images you added in Workover are uploaded to the article in Help Scout as part of the publish, so the published article never points at Workover. Images that came from Help Scout keep their addresses.

Warning: Updating the live article deletes any unpublished draft of it in Help Scout. Workover checks first, and stops if there is one (see below).

If the article changed in Help Scout

If someone changed the article in Help Scout since your last sync, publishing stops and asks first:

  • Pull Help Scout’s version first replaces the document here with the article in Help Scout, discarding changes you have not published. If the article has an unpublished draft, that is what you get.
  • Publish anyway, overwriting overwrites their changes. When someone has an unpublished draft of the article in Help Scout, the button reads Publish anyway, deleting their draft (or Save anyway, replacing their draft when you are saving a draft).
  • Cancel publishes nothing.

Warning: Help Scout’s editor saves drafts as people type, so a draft can exist even if nobody meant to keep one. Pull first if you are not sure what it holds.

If the article was deleted in Help Scout, the tab says This article is no longer in Help Scout. It may have been deleted there.

To bring an article’s latest version into Workover at any time, click Pull from Help Scout in the Help Scout tab, then Pull latest.

Bring in later changes

Click Sync from Help Scout in the project to bring in new articles and refresh the others. An article that someone has already opened in Workover keeps its body, so your edits are never overwritten; only its title and address are refreshed. Articles nobody has opened are refreshed in full.

Limits and errors

  • Moving an article to another collection happens in Help Scout, not in Workover.
  • Deleting an article happens in Help Scout. Deleting the document in Workover leaves the article in Help Scout.
  • Rate limit. Help Scout allows 2,000 Docs API requests every 10 minutes on a one-site account, 4,000 with three or more sites, shared with your team’s use of Help Scout. A large import paces itself to stay within it, which is why it can take a few minutes.
  • “Help Scout rejected the Docs API key. Reconnect Help Scout Docs and try again.” Check that you copied the Docs API key in full, and that its owner still has permission to edit Docs.
  • “Help Scout is rate limiting this account. Try again in a few minutes.” The account hit the rate limit above. Wait and try again.

Still need help?

Can’t find what you’re looking for? Our team is here to help.

Contact support