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}:{password} \-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 "username:password"
	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  ]}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.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 "username:password"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
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",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"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  ]})request.basic_auth "username", "password"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"}