Zendesk Answer Bot API

Zendesk Answer Bot API

One of the lesser known and used APIs in Zendesk's arsenal is the Answer Bot API. It allows platforms to replicate the behaviour of their bot in any app or website. Or an Apple HomePod..

One of the lesser known and used APIs in Zendesk's arsenal is the Answer Bot API. It allows platforms to replicate the behaviour of AnswerBot in any app or website. Or an Apple HomePod, but more on that later.

Use cases where this might be useful are for example:

  • Show three suggested articles below a contact form not hosted on Zendesk Guide.
  • Based on the product the customer is looking at, load some support suggestions dynamically
  • Load Zendesk Articles in a third party bot that's not natively connected to Zendesk.

Overview

The API flow runs as follows:

  1. Get a query from your end-user and POST it to the Answer Bot recommendations endpoint.
  2. That endpoint returns an array of 3 articles and an interaction_access_token
  3. You can then use one of two endpoints to either confirm a resolution, or reject the suggestions with a reason.
  4. It's up to your app to then handle the reject with an escalation to a webform, suggest more articles...

Example flow

Exploring an API is only fun if we have a good use case to test it on.
For this example we'll create a small webpage that allows you to get recommendations and reject/accept them.

But first, the demo. This small website allows you to enter a search query. It then pulls in data from our Demo Help Center and returns the three recommended articles.
You can then mark them as good or bad to train the data set.

You can use this sample website to e.g. embed Answer Bot on your own website. All sample code is provided below.

Taking this one step further.

While playing around with the Answer Bot API I remembered that Siri can also do API calls.. so I build a little demo. Just for the fun of it. 😎

You can download the Apple Shortcut below.

Answer Bot API Tutorial

In our demo we handle the connection to AnswerBot via a separate script running on Cloudflare Workers. This makes it possible to hide the API tokens from end-users and add some caching to the returned data, meaning you don't hit your API limits on Zendesk as fast.

The full source code is available in the repository below.

GitHub - verschoren/zendesk_widget: Zendesk has a nice Web Widget to embed your contact channels and FAQ on any page of your website creating a consistent experience that aligns with your brand.
Zendesk has a nice Web Widget to embed your contact channels and FAQ on any page of your website creating a consistent experience that aligns with your brand. - GitHub - verschoren/zendesk_widget:…

Get Article Recommendations

The first step in setting up this flow is accessing the Article Recommendations /api/v2/answer_bot/answers/articles endpoint.
This endpoint requires an enquiry , or the search parameters from the customer. You can restrict the results further by adding a locale or label parameter.

Important here is the reference . It allows you to make these enquiries visible in Zendesk Explore and measure how often customers resolve issues via this new Channel.

POST https://internalnote.zendesk.com/api/v2/answer_bot/answers/articles Authorization: Basic abc123def456ghi789
Content-Type: application/json

{
    "enquiry": "how to clean Lego",
    "locale": "en-us",
    "reference": "internal-note-demo"
}

When successful, the API returns an array of articles and an 🔑 interaction_access_token . You'll need this token to give feedback on the recommended articles. If no articles are found, you get an empty array of articles

{
  "id": 9942024815634,
  "interaction_access_token": "123456789abc",
  "auth_token": "qwertyuiop1234",
  "articles": [
    {
      "title": "Cleaning your LEGO® bricks",
      "article_id": 9913419783442,
      ...
    },
    ...
  ]
}

Getting user input on the presented articles.

💡
Did you know that each time an Agent recommends an article via the Knowledge Panel or a customer interacts with Answer Bot, these actions are used to train the recommendation engine behind Answer Bot? The more your agents or end-users use these tools, the better your result will get!

Now that we can show our customers a set of recommended articles, you can leverage this to train your Answer Bot data by letting your customers mark these articles as ✅ Yes! They solved my problem, or ❌ No didn't help.

In the demo page we added buttons to the articles to allow users to vote up/or down. Note that each article can get its own vote since they're all scored independently of each other.

Accept an article

This is the best-case scenario. It let's Zendesk know this is a good article and should be recommended more for similar enquiries. Since Zendesk only returns three articles, the better its score, the more often an article will be recommended for that query.

Accepting the article as a resolution is as easy as a POST to /api/v2/answer_bot/resolution with the payload below. You use the 🔑 interaction_access_token and the ID of the relevant article.
The API returns a simple STATUS:200

{
  "article_id": 12345, //the article ID
  "interaction_access_token": "123456789abc"
}

Reject an Article

Rejecting an article is similar. It tells Zendesk this is a bet recommendation. By default you can just reject an article, but you can also send a reason ID along to tell the system why it's bad.

Reason ids

Value Reason Description
0 Unknown No reason given, this just lowers the score
1 Not Related Plenty of these removes the article from the recommendations for that query
2 Related, but didn't answer the question This is a good article but needs more info to help the customer. This feedback will trigger Content Cues.
{
  "article_id": 12345, //the article ID
  "interaction_access_token": "123456789abc",
  "reason_id": 2
}

Here also the API returns a simple Status:200

Answer Bot Shortcut

You can install the Shortcut via the link below.

Just remember to:

  • Add a Base64 Encoded [email protected]/token:zendesktoken in the Get Contents of URL step
  • Replace internalnote.zendesk.com with your Zendesk domain in the Get Contents of URL step.

Roundup

As mentioned, Answer Bot is one of the more hidden APIs. Most Zendesk users only encounter it via the Chat Widget, and more rarely it's enabled for webforms or email, but as a way to deflect incoming suggestions and allow for more context-aware self-service for end-users it's powerful.

Implementing the API on your platform might seem farfetched at first, but anywhere where you can replace static content in a list of suggested articled with dynamically generated suggestions you'll win two ways: the suggested list is maintained automatically and you have an extra point we're users can give feedback which will improve your Help Center content and search!