Introduction
The Answer Bot API provides Help Center article suggestions for an enquiry. Answer Bot uses machine learning to return articles that might potentially help solve the issue. To learn more, see Answer Bot on www.zendesk.com.
To use the Answer Bot API, your organization must be on the Guide Professional or Enterprise plan and have an Answer Bot monthly subscription. API usage is billed by request volume, with one resolution consumed for every 100 API requests. The API is also available on the trial.
Topics covered:
- Using Answer Bot article suggestions
- Authentication
- Interaction Access Tokens
- Get Article Suggestions
- Record Article Viewed
- Record Article Rejection
- Resolve Enquiry
- Resolve Enquiry in Help Center
Using Answer Bot article suggestions
Requesting an article suggestion from Answer Bot creates a suggestion. A suggestion is a collection of articles with content that might be related to the enquiry. The response also contains metadata that allows further access to Answer Bot API actions, such as resolving the request or providing feedback on the suggestion. See Get Articles Suggestions.
You can then use the suggested articles to provide a UI to your end users that allows them to self-solve their issue. If the user finds an answer to their question, you can use the API to mark the enquiry as resolved. The feedback helps Answer Bot improve its suggestions. See Resolve Enquiry. You can also let the end user self-resolve an enquiry in Help Center. See Resolve Enquiry in Help Center.
You can provide other feedback with the following API endpoints:
Authentication
Authentication works as described in the Security and Authentication in the Zendesk v2 API documentation.
Only the Get Article Suggestions requires authentication. Other endpoints require an interaction access token. The next section explains this type of token.
Interaction Access Tokens
The response from the API includes an interaction_access_token
that is required for further actions in the API. The token uses the JWT standard and contains encoded and signed internal information.
{
"interaction_access_token": "GciOiJIUzI1NiJ9eyJ0eXAiOiJKV1QiLCJhb.0aWNsZXMiO...",
...
}
The decoded JWT token contains the following information:
{
"id": 65731,
"account_id": 1682103,
"brand_id": 626052,
"article_ids": [],
"exp": 1525410034
}
You can read more about the JWT standard and decoding the token on the JWT IO website if you're debugging the integration.
Don't confuse the interaction_access_token
with the auth_token
in the same response. The auth_token
is used in article URLs for resolving enquiries in Help Center. See Resolve Enquiry in Help Center.
Get Article Suggestions
POST /api/v2/answer_bot/answers/articles
Returns Help Center articles based on the user's enquiry.
Allowed for
- Authenticated requests
Request Properties
Name | Type | Required | Comments |
---|---|---|---|
enquiry | string | yes | The user's question |
reference | string | yes | An identifier that you can reference in your system, such as a request id or ticket id |
locale | string | no | Restricts the article suggestions to the specified Help Center locale. Examples: 'en-gb', 'de', or 'es'. Check your Help Center for enabled locales |
labels | array | no | Restricts the article suggestions to public articles with the specified labels |
Using curl
curl https://mondocam.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"]
}'
Example Response
{
"id": 4,
"interaction_access_token": "GciOiJIUzI1NiJ9eyJ0eXAiOiJKV1QiLCJhb.0aWNsZXMiOlsxMDEwMiwxMDE5Ml0sInRva2VuIjpudWxsLCJleHAiOjE1MjA2NjE1MTR9eyJhY2NvdW50X2lkIjo0MiwidXNlcl9pZCI6MTAwMDIsInRpY2tldF9pZCI6NSwiYXJ.VzS91dP0cLjXw_3pZd2tcEdru8xoOXQe7ZfqzA9uL3s",
"auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50X2lkIjo0MiwidXNlcl9pZCI6MTAwMDIsInRpY2tldF9pZCI6NSwiYXJ0aWNsZXMiOlsxMDEwMiwxMDE5Ml0sInRva2VuIjpudWxsLCJleHAiOjE1MjA2NjE1MTR9.VzS91dP0cLjXw_3pZd2tcEdru8xoOXQe7ZfqzA9uL3s",
"articles": [
{
"article_id": 10192,
"title": "Lorem ipsum",
"snippet": "Consectetur adipiscing elit...",
"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",
"url": "https://mondocam.zendesk.com/article",
"label_names": ["magna", "tellus"],
"brand_id": 10016,
"locale": "en-us",
"score": 0.38012391328882646
},
{
"article_id": 10192,
"title": "Proin sit amet",
"snippet": "Cras vehicula ipsum...",
"html_body": "<p>Cras vehicula ipsum at maximus ullamcorper. Maecenas scelerisque ultricies dignissim.</p>",
"html_url": "https://mondocam.zendesk.com/hc/proin",
"url": "https://mondocam.zendesk.com/article",
"label_names": ["magna"],
"brand_id": 10016,
"locale": "en-us",
"score": 0.88826463801239132
}
]
}
Record Article Viewed
POST /api/v2/answer_bot/viewed
Records that the user viewed an article from the list of suggested articles.
Allowed For
- Requests with a valid
interaction_access_token
Request Properties
Name | Type | Required | Comments |
---|---|---|---|
article_id | integer | yes | The id of the Help Center article viewed by the user. Note: This id must be one of the articles suggested from the initial request. |
interaction_access_token | string | yes | See Interaction Access Tokens |
Using curl
curl https://mondocam.zendesk.com/api/v2/answer_bot/viewed -X POST -H "Content-Type: application/json" -d
'{
"article_id": 12345,
"interaction_access_token": "GciOiJIUzI1NiJ9eyJ0eXAiOiJKV1QiLCJhb.0aWNsZXMiOlsxMDEwMiwxMDE5Ml0sInRva2VuIjpudWxsLCJleHAiOjE1MjA2NjE1MTR9eyJhY2NvdW50X2lkIjo0MiwidXNlcl9pZCI6MTAwMDIsInRpY2tldF9pZCI6NSwiYXJ.VzS91dP0cLjXw_3pZd2tcEdru8xoOXQe7ZfqzA9uL3s"
}'
Example Response
200 SUCCESS
Record Article Rejection
POST /api/v2/answer_bot/rejection
Records the article that the user found irrelevant.
Allowed For
- Requests with a valid
interaction_access_token
Request Properties
Name | Type | Required | Comments |
---|---|---|---|
article_id | integer | yes | The id of the Help Center article that the user indicated was not relevant |
reason_id | integer | yes | See Reason Ids |
interaction_access_token | string | yes | See Interaction Access Tokens |
Reason Ids
Value | Reason |
---|---|
0 | unknown (default) |
1 | not related |
2 | related but didn't answer the question |
Using curl
curl https://mondocam.zendesk.com/api/v2/answer_bot/rejection -X POST -H "Content-Type: application/json" -d
'{
"reason_id": 2,
"article_id": 12345,
"interaction_access_token": "GciOiJIUzI1NiJ9eyJ0eXAiOiJKV1QiLCJhb.0aWNsZXMiOlsxMDEwMiwxMDE5Ml0sInRva2VuIjpudWxsLCJleHAiOjE1MjA2NjE1MTR9eyJhY2NvdW50X2lkIjo0MiwidXNlcl9pZCI6MTAwMDIsInRpY2tldF9pZCI6NSwiYXJ.VzS91dP0cLjXw_3pZd2tcEdru8xoOXQe7ZfqzA9uL3s"
}'
Example Response
200 SUCCESS
Resolve Enquiry
POST /api/v2/answer_bot/resolution
Solves the request if the user indicates the question was answered.
You can also let an end user self-resolve an enquiry in Help Center. See Resolve Enquiry in Help Center.
Allowed For
- Requests with a valid
interaction_access_token
Request Properties
Name | Type | Required | Comments |
---|---|---|---|
article_id | integer | yes | The id of the Help Center article that the user indicated answered their question |
interaction_access_token | string | yes | See Interaction Access Tokens |
Using curl
curl https://mondocam.zendesk.com/api/v2/answer_bot/resolution -X POST -H "Content-Type: application/json" -d
'{
"article_id": 12345,
"interaction_access_token": "GciOiJIUzI1NiJ9eyJ0eXAiOiJKV1QiLCJhb.0aWNsZXMiOlsxMDEwMiwxMDE5Ml0sInRva2VuIjpudWxsLCJleHAiOjE1MjA2NjE1MTR9eyJhY2NvdW50X2lkIjo0MiwidXNlcl9pZCI6MTAwMDIsInRpY2tldF9pZCI6NSwiYXJ.VzS91dP0cLjXw_3pZd2tcEdru8xoOXQe7ZfqzA9uL3s"
}'
Example Response
200 SUCCESS
Resolve Enquiry in Help Center
You can let an end user self-resolve an enquiry when they view a suggested article in Help Center.
First, retrieve the auth_token
property returned by the initial request for the article suggestions. See Get Article Suggestions. Don't confuse the auth_token
with the interaction_access_token
in the same response.
Second, append the auth_token
property as a URL parameter to the url (html_url
) of each suggested article you present to the end user. Example:
href="https://mondocam.zendesk.com/hc/en-us/articles/43264532?auth_token="eyJ0eXAiOiJKV1QiLCJhbGciOi..."
If the end user follows the URL, they can self-resolve the enquiry in Help Center if the article answers their question.