Article Recommendations

Note: Zendesk has renamed our bot capabilities. Answer Bot is now Zendesk bots. Article Recommendations are now autoreplies. For more information on this change, see this announcement.

A recommendation is a collection of help center articles with content that might be related to a customer's enquiry. Requesting an article recommendation from Answer Bot creates a recommendation.

JSON format

Articles are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
article_id	number	false	false	The id of article
brand_id	number	false	false	The id of the brand
html_body	string	false	false	The body of the article in HTML
html_url	string	false	false	The url of the HTML body
label_names	array	false	false	The labels of this article
locale	string	false	false	The help center locale of the article
score	number	false	false	the score of this article against the user enquiry
snippet	string	false	false	An excerpt of the article
title	string	false	false	The title of the article
url	string	false	false	The url of the article

Get Article Recommendations

• POST /api/v2/answer_bot/answers/articles

Returns help center articles based on an end user's enquiry.

Allowed For

• Authenticated requests

JSON format

Enquiries are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
enquiry	string	false	true	The end user's question
labels	array of strings	false	false	Help center labels used to restrict article recommendations
locale	string	false	false	Help center locales used to restrict article recommendations. Example: "en-gb", "de", or "es". Must match an available help center locale
reference	string	false	true	An unique value for every request. This will be used to calculate the MAUs for the account
user_segment_ids	array of integers	false	false	Array of user segment ids. Article recommendations are restricted to articles that are accessible to these user segments. If user_segment_ids is not provided, only public articles are retrieved

Example body

{
  "enquiry": "Consectetur adipiscing elit",
  "labels": [
    "magna"
  ],
  "locale": "en-us",
  "reference": "sdk-mobile-uid-customer-id",
  "user_segment_ids": [
    2345123
  ]
}

Code Samples

curl

curl "https://{subdomain}.zendesk.com/api/v2/answer_bot/answers/articles" -X POST -H "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
-d '{"enquiry": "Consectetur adipiscing elit","reference":"sdk-mobile-uid-customer-id","locale":"en-us","labels":["magna"]}'

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://support.zendesk.com/api/v2/answer_bot/answers/articles"
	method := "POST"
	payload := strings.NewReader(`{
  "enquiry": "Consectetur adipiscing elit",
  "labels": [
    "magna"
  ],
  "locale": "en-us",
  "reference": "sdk-mobile-uid-customer-id",
  "user_segment_ids": [
    2345123
  ]
}`)
	req, err := http.NewRequest(method, url, payload)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/answer_bot/answers/articles")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"enquiry\": \"Consectetur adipiscing elit\",
  \"labels\": [
    \"magna\"
  ],
  \"locale\": \"en-us\",
  \"reference\": \"sdk-mobile-uid-customer-id\",
  \"user_segment_ids\": [
    2345123
  ]
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "enquiry": "Consectetur adipiscing elit",
  "labels": [
    "magna"
  ],
  "locale": "en-us",
  "reference": "sdk-mobile-uid-customer-id",
  "user_segment_ids": [
    2345123
  ]
});

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/api/v2/answer_bot/answers/articles',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  data : data,
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
import json
from requests.auth import HTTPBasicAuth

url = "https://support.zendesk.com/api/v2/answer_bot/answers/articles"

payload = json.loads("""{
  "enquiry": "Consectetur adipiscing elit",
  "labels": [
    "magna"
  ],
  "locale": "en-us",
  "reference": "sdk-mobile-uid-customer-id",
  "user_segment_ids": [
    2345123
  ]
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"POST",
	url,
	auth=auth,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/answer_bot/answers/articles")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "enquiry": "Consectetur adipiscing elit",
  "labels": [
    "magna"
  ],
  "locale": "en-us",
  "reference": "sdk-mobile-uid-customer-id",
  "user_segment_ids": [
    2345123
  ]
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "articles": [
    {
      "article_id": 10192,
      "brand_id": 10016,
      "html_body": "<p>Consectetur adipiscing elit. Quisque sit amet magna id tellus volutpat aliquet et nec lorem. </p>",
      "html_url": "https://mondocam.zendesk.com/hc/lorem",
      "label_names": [
        "magna",
        "tellus"
      ],
      "locale": "en-us",
      "score": 0.38012391328882644,
      "snippet": "Consectetur adipiscing elit...",
      "title": "Lorem ipsum",
      "url": "https://mondocam.zendesk.com/article"
    },
    {
      "article_id": 10192,
      "brand_id": 10016,
      "html_body": "<p>Cras vehicula ipsum at maximus ullamcorper. Maecenas scelerisque ultricies dignissim.</p>",
      "html_url": "https://mondocam.zendesk.com/hc/proin",
      "label_names": [
        "magna"
      ],
      "locale": "en-us",
      "score": 0.8882646380123913,
      "snippet": "Cras vehicula ipsum...",
      "title": "Proin sit amet",
      "url": "https://mondocam.zendesk.com/article"
    }
  ],
  "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50X2lkIjo0MiwidXNlcl9pZCI6MTAwMDIsInRpY2tldF9pZCI6NSwiYXJ0aWNsZXMiOlsxMDEwMiwxMDE5Ml0sInRva2VuIjpudWxsLCJleHAiOjE1MjA2NjE1MTR9.VzS91dP0cLjXw_3pZd2tcEdru8xoOXQe7ZfqzA9uL3s",
  "id": 4,
  "interaction_access_token": "GciOiJIUzI1NiJ9eyJ0eXAiOiJKV1QiLCJhb.0aWNsZXMiOlsxMDEwMiwxMDE5Ml0sInRva2VuIjpudWxsLCJleHAiOjE1MjA2NjE1MTR9eyJhY2NvdW50X2lkIjo0MiwidXNlcl9pZCI6MTAwMDIsInRpY2tldF9pZCI6NSwiYXJ.VzS91dP0cLjXw_3pZd2tcEdru8xoOXQe7ZfqzA9uL3s"
}