Docs

Help desk / Teach the agent / Knowledge

Articles

Write and manage articles, Risotto's built-in knowledge base, and turn resolved Slack threads into articles with the ✍️ emoji

Articles are Risotto's built-in knowledge base. When the agent answers a question, it searches your articles together with your indexes. As the Articles tab puts it, articles take precedence over indexed data. Risotto re-indexes an article each time you save it.

You manage articles in Knowledge > Articles.

The Articles tab

Click Knowledge in the sidebar. The page opens on the Articles tab and lists your articles in a table with their Title and the date they were Created. Click a column header to sort by it, and type in Search articles to find an article by its title or its content. Click a title to open the article.

The ⋮ menu on each row has these actions:

  • Open in Slack: opens the Slack thread the article was made from. It shows only for an article created from a ticket.
  • Export…: copies the article into Guru. See Exporting an article to Guru.
  • Delete: deletes the article. See Deleting an article.

Creating an article

You see Create article if you are an Org Admin, an Org Manager or a Department Supervisor. See Article permissions.

  1. Click Create article

    In Knowledge > Articles, click Create article above the table. The Create article dialog opens.

  2. Enter a title

    Type the article's Title.

  3. Choose a department

    Pick a Department to restrict the article to that department, or keep Organization-wide. See Organizing articles.

    Organization-wide is offered only to Org Admins and Org Managers. If you are a Department Supervisor, your first department is selected for you.

  4. Click Add content

    Click Add content. Risotto creates the article and opens it, ready to edit.

  5. Write the content and save

    Write the article in the Content editor, then click Save. See Editing an article.

Editing an article

  1. Open the article

    In Knowledge > Articles, click the article's title. The article opens with its details in a side panel.

  2. Click Edit

    Click Edit in the page header, or press e. The Title, Department and Content fields open.

  3. Change the article

    Edit the fields. Content is Markdown.

    The toolbar above the content adds bold, italic, a quote, a numbered or bulleted list, a heading (H1 to H3), a link, and code. Click Preview to see the rendered article, and Write to go back to the Markdown.

  4. Click Save

    Click Save, or press ⌘S (Ctrl+S on Windows). The header shows Saved. To discard your changes, click Cancel or press Esc.

Articles hold text only. The editor has no button to upload or paste an image. If you add a Markdown image link, the image shows in Preview, but Risotto reads only the text of the article. It does not read what is in the picture, so describe each step in words.

The side panel shows the article's Title, its Department (or Organization-wide), and when it was Created and Last updated. For an article created from a ticket, it also shows the Original question, a link to the Ticket, and an Open in Slack button that opens the source thread.

Each change is recorded in Settings > Audit Log as Knowledge Article Updated.

Deleting an article

  1. Open the row menu

    In Knowledge > Articles, open the ⋮ menu on the article's row and click Delete.

  2. Confirm

    In the Delete article? dialog, confirm. Risotto shows Article deleted.

Deleting cannot be undone. If Risotto has already used the article to answer in Slack and you index that Slack channel, the answer can stay in the channel index. In that case, editing the article is better than deleting it.

Each deletion is recorded in Settings > Audit Log as Knowledge Article Deleted.

Automating article creation in Slack

When a Slack thread solves a problem that your documentation doesn't cover, you can turn it into an article. Add the ✍️ (:writing_hand:) reaction to the thread's top message, the one that started the thread. A ✍️ on a reply does nothing. Risotto then:

  1. Creates a ticket for the thread if it has none.
  2. Writes an article from the thread: a title and a Markdown body. The article is organization-wide, and it keeps the ticket and the original question.
  3. Resolves the ticket if it is not resolved yet, and adds an internal note to the ticket that names you and links the new article.
  4. Adds a 💡 reaction to the thread once the article is indexed, and posts Knowledge Base Article Created to your notifications channel if you have one.

Once the article is indexed, Risotto stops using the Slack thread itself as a source, so the article takes its place.

  • Adding ✍️ again to a thread that already has an article rewrites that article from the thread. This replaces any edits you made in the dashboard.
  • Removing the last ✍️ reaction from the top message deletes the article.
  • Risotto ignores the reaction from anyone whose Slack email doesn't match a Risotto dashboard user.

To use a different emoji, see Commands.

Organizing articles

Each article has a Department field ("Optionally restrict this article to a specific department."). The field controls which tickets the agent can use the article on:

  • Organization-wide: the agent can use the article on any ticket. Articles that the ✍️ emoji creates are organization-wide.
  • A department: the agent uses the article only on tickets in that department. A ticket with no department gets only organization-wide articles.

The department comes from the ticket, not from the requestor. Any requestor whose ticket goes to that department can get an answer from the article.

Exporting an article to Guru

You can copy an article into Guru as a new card. The article in Risotto stays unchanged. Only an Org Admin or Org Manager sees the export action, because the export sends a vault credential's value to Guru.

Before you start, you need:

  • A Guru User Token stored in the Credential Vault as an org-wide credential of type Secret text. Risotto does not accept a Collection Token. A department credential cannot be used for an export. If the credential has allowed hosts, they must include api.getguru.com.
  • The email of the Guru user the token belongs to.
  1. Open the export dialog

    In Knowledge > Articles, open the ⋮ menu on the article row and click Export…. The Export article dialog opens.

  2. Choose the destination and account

    Destination is Guru. Enter the User email of the Guru user who owns the token. Guru creates the card as this user.

  3. Pick the token

    For User API token, pick the vault credential that holds the Guru User Token, or create one inline. The list shows org-wide credentials only.

  4. Pick a collection

    After you enter the email and pick the token, Risotto loads the collections the Guru user can see. Pick the Collection the card is created in. If you change the email, the token, or the destination, pick the collection again.

  5. Set access and export

    Access is Team or Private. A Team card is visible to everyone who can read the collection. A Private card is visible to the token's user only. Click Export.

    Risotto shows Article exported to Guru with an Open link to the new card.

The export converts the article's markdown to HTML. Tables, fenced code blocks, and lists keep their formatting. Strikethrough text is exported as literal ~~ characters.

Each export is recorded in Settings > Audit Log as Knowledge Article Exported, with the article, the destination, the collection, the access level, and the new card's ID and URL. Exporting the same article again creates another card; Risotto does not update a card it exported before.

Article permissions

Every org member can read every article. Who can write an article depends on the article's Department field and on your roles. See Permissions System for all roles.

ActionOrg Admin or Org ManagerDepartment SupervisorDepartment Agent or Org Member
Read articles✅✅✅
Create, edit, or delete an org-wide article✅❌❌
Create, edit, or delete a department article✅Only in departments that they supervise❌
Move an article to org-wide✅❌❌
Move an article to another department✅Only between departments that they supervise❌
Export an article to Guru✅❌❌

A Supervisor of a sub-department can also write the articles of the parent department. A Supervisor sees Organization-wide in the Department field only if they are also an Org Admin or Org Manager.

Something wrong or missing? Report an issue · View as Markdown