Skip to main content

Evaluate a Comment

Evaluates a comment in the context of the article/blog/etc the conversation is about, and optionally the comment it is replying to.

This is Respectify's main API and the one you will likely call the most. It returns:

  • A list of any common logical fallacies that seems to be present in the comment, with the goal of educating the commenter on traps they may be falling into. This includes the fallacy name, the quoted part of their comment that demonstrates it, an explanation of why we think that quote shows a logical fallacy, and sometimes a suggested rewrite. Rewrites are rare and only if the commenter's intent was very clear.

  • Any objectionable or rude phrases, including (similarly to logical fallacies) what they are, why we assessed them as such, and very rarely a suggested rewrite (only if the commenter's intent was clear);

  • any negative tone phrases. These are not objectionable or rude, but are phrases that don't contribute to the conversation. Note that Respectify encourages friendly (genuine, well-intentioned) disagreement and healthy sharing of different opinions and views. Respectify is not an engine for monoculture of thought, but in fact intends to assist in the opposite while encouraging in healthy interaction along the way. Sometimes, disagreement can be done in an unhealthy way and this section identifies those. Like the previous sections, it quotes the specific example, explains why, and rarely (if intent is clear) suggests how the same thing could be said but in a better way.

  • If the comment appears 'low effort' (usually short comments that don't add to the conversation, eg, 'me too');

  • If the comment appears to be spam (this is an early exit and a spam comment that contains logical fallacies etc may have this flag set, but have empty fields in the other areas);

  • An overall score: an approximation from 1 (low) to 5 (good) of the quality of the comment, ie how well the comment seems to engage and contribute to the conversation.

How to use this response is up to you as the API consumer. We generally recommend using the spam flag and any very low overall score (1 to 2) for a swift assessment not to accept the post, but in other cases show the user the identified issues and allow them the opportunity to edit their comment and try again (resulting in you calling this API a second time.) You may even want to allow very low scored comments the opportunity to have feedback shown and to be rewritten by the commenter.

The idea is to use this not to censor but to educate and encourage better discussion, and providing multiple opportunities to do so is very much the Respectify ethos.

We hope that over time, as a result of feedback as users engage, your users will proactively write better comments without needing to be prompted.

Header Parameters
X-User-Email email — REQUIRED

Account email address, for authentication

X-API-Key string — REQUIRED

API key owned by the user (email), for authentication

Request Body — REQUIRED
article_context_id uuid — REQUIRED

UUID that identifies the article/blog/etc that this comment was written in the context of (ie it's a comment in a conversation about this article.)

This UUID comes from the /inittopic API.

comment string — REQUIRED

The comment text: this is what is evaluated.

reply_to_comment string

Provides additional context: the comment to which the one being evaluated is a reply. This is optional but recommended to include if it exists, because is used to provide additional context when assessing the 'comment' parameter.

Responses
200

Successful response - returns a JSON object.

Schema — OPTIONAL
logical_fallacies object[]

A list of any logical fallacies identified within the comment.

fallacy_name string

Name of the logical fallacy, eg, 'straw man'

quoted_logical_fallacy_example string

Quoted part of the comment that demonstrates the fallacy

explanation_and_suggestions string — OPTIONAL

Explanation of why we think that quote shows a logical fallacy, and suggestions on how to tackle it

suggested_rewrite string — OPTIONAL

Rarely, a suggested rewrite. Provided only if the commenter's intent was very clear.

objectionable_phrases object[]

A list of any objectionable or rude phrases identified within the comment.

quoted_objectionable_phrase string

Quoted part of the comment that may be seen as objectionable

explanation string — OPTIONAL

Explanation of why we assessed this as potentially objectionable

suggested_rewrite string — OPTIONAL

Rarely, a suggested rewrite. Provided only if the commenter's intent was very clear.

negative_tone_phrases object[]

A list of any negative tone phrases identified within the comment.

quoted_negative_tone_phrase string

Quoted part of the comment that may contribute negatively to the conversation

explanation string — OPTIONAL

Explanation of why we assessed this as potentially negative for the conversation

suggested_rewrite string — OPTIONAL

Rarely, a suggested rewrite. Provided only if the commenter's intent was very clear.

appears_low_effort boolean

True if the comment appears to be low effort, eg, 'me too' or 'I agree'.

overall_score integer

An approximation from 1 (low) to 5 (good) of the quality of the comment.

400

Bad Request - Missing or invalid parameters

401

Unauthorized - Missing or incorrect authentication