Comments

Read what readers ask under your articles, work the moderation queue, and answer as your team. The comments endpoints list every comment on your help center or one article's conversation, approve and reject comments, post replies, and delete comments.

Comments are available on every plan. The private notes your team leaves on articles are a separate resource that these endpoints never return: see Team notes. Reader votes on an article (helpful or not) are recorded with the Articles endpoints.

Endpoints

An API key works with the help center it was created in. An OAuth app names the help center with the X-HCio-Site header (see Choose which help center a request acts on). A Read only key on a write endpoint gets 403 Forbidden with the code insufficient_scope. Reads count toward the limit of 300 requests a minute per API key or OAuth app, and writes also toward 120 a minute (see Rate limits).

The comment object

List comments

Use it as the moderation queue (status=pending) or as the feed of what readers ask. All parameters are optional:

meta gives page, per_page, total_pages (at least 1) and items_count, the number of comments that match your filters. meta.status_counts counts the whole help center's comments by status, whatever your filters, so one call tells you how many are waiting.

Comments on articles in the Trash are left out of every comments endpoint and of the counts, and moderating or deleting one answers 404.

Reader email addresses

Comments come without email addresses. Add include_email=1 when you need to contact the people who wrote them:

curl "https://api.helpcenter.io/v1/comments?status=published&include_email=1" \
  -H "apikey: $HELPCENTER_API_KEY" \
  -H "Accept: application/json"

Each author then carries email: the address a visitor typed, or the account's address for someone who was signed in.

"author": {
  "name": "Jane Doe",
  "type": "visitor",
  "user_id": null,
  "email": "jane.doe@example.com"
}

• The value must be 1 or 0. include_email=true is refused with 422 Unprocessable Entity and "The include email field must be true or false."

• Email addresses need write access: a Read & write API key, or an OAuth token with content.write. A Read only key gets 403 Forbidden.

• Addresses are personal data: request them only when you are going to use them. IP addresses are never returned.

Get an article's comments

The top-level comments come oldest first, each with its replies nested to any depth. meta.threads_count is the number of top-level comments and meta.comments_count the number of comments in the response, replies included. The top-level article.title is an object with every language of the title.

There is no paging: you get the whole conversation. search, article_id, page and limit are accepted and have no effect.

When a comment that has replies is deleted, this view leaves out the comment and its replies. The replies still appear in GET /v1/comments, with parent_id pointing at the deleted comment.

Post a comment or a reply

• The author is the credential's owner. A comment posted with an API key is signed by the team member who created the key; with an OAuth token, by the person who approved the app. There is no field to post under another name.

• It is published at once, whatever your help center's approval setting. Readers see it on the article in its language, wherever your help center shows comments.

• Reply to the top-level comment. Your help center shows one level of replies under each comment. A reply to a reply is saved and returned by the API, but readers may not see it.

• It sends email. A reply emails the author of the comment you replied to ("Your comment got a reply"), unless they unsubscribed, their address isn't a valid email address, or it is their own address, and even when their comment is still pending. A top-level comment emails the article's author ("A new comment has been posted").

• It is not idempotent. Sending the same request twice posts two comments. If a request times out, read the article's comments before you try again.

Approve or reject a comment

Send published to approve a comment or unpublished to reject it. You can change your mind later: both work on any comment that is not deleted, and setting the status it already has answers 200. The text of a comment can't be changed through the API.

Approving a reply that wasn't published yet emails the author of the comment it answers ("Your comment got a reply"), once per reply. Approving a top-level comment sends no email.

Delete a comment

A deleted comment is taken off the help center, and its replies stay. When it has replies, readers see a note that the comment was deleted in its place. Deleting the same comment again answers 200 with "Comment was already deleted.", so a retry is safe.

Restoring a comment, and deleting it for good, happen in the dashboard (see Approve and answer reader comments). To take a comment off the help center in a way you can undo over the API, reject it instead.

Errors

For the error format and the errors every endpoint shares, see Errors.

Related

• Team notes

• Articles

• Webhooks