Skip to main content

Quick Start

This guide will show you how to get started through code samples. It will cover:

  • How to use the Respectify client class in your language to interact with Respectify

  • Initialise Respectify with a topic: this gives Respectify an understanding of what people are commenting on, and is usually a blog post, article, etc

  • Evaluate a comment, and get Respectify's feedback on how well it contributes to the conversation and in what ways the reply can be improved in order to encourage healthy interaction.

Installation and Authentication​

Install the library and get an API key. See Installation for full details.

npm install @respectify/client

Check User Credentials​

Verifies your credentials work correctly. See Installation for more details.

import { RespectifyClient } from "@respectify/client";

const client = new RespectifyClient({
  email: "your-email@example.com",
  apiKey: "your-api-key",
});

const result = await client.checkUserCredentials();
console.log(`Active: ${result.active}`);
console.log(`Plan: ${result.plan_name}`);
console.log(`Endpoints: ${result.allowed_endpoints}`);

Initialising a Topic​

Respectify assesses a comment in the context of what it is replying to or is likely about. There is an implicit assumption that all comments are about something, and that is usually an article, blog post, or similar. It doesn't have to be online: you can just give Respectify some text.

But, you always need to initialise a topic so that when evaluating a comment, Respectify knows the 'something' that the conversation is about. See Topic Initialization for full details.

import { RespectifyClient } from "@respectify/client";

const client = new RespectifyClient({
  email: process.env.RESPECTIFY_EMAIL!,
  apiKey: process.env.RESPECTIFY_API_KEY!,
});

const result = await client.initTopicFromUrl("https://en.wikipedia.org/wiki/Delphi");
const articleId = result.article_id;

// Or from text:
const result2 = await client.initTopicFromText("Your article content here...");
const articleId2 = result2.article_id;

Comment Scoring​

Evaluate a comment's quality and contribution to the conversation. See Comment Scoring for full details.

const result = await client.evaluateComment(
  "This is a sample comment.",
  articleId
);

console.log(`Overall Score: ${result.overall_score}/5`);
console.log(`Toxicity: ${result.toxicity_score}`);
console.log(`Low Effort: ${result.appears_low_effort}`);

for (const fallacy of result.logical_fallacies) {
  console.log(`Fallacy: ${fallacy.fallacy_name}`);
}

for (const phrase of result.objectionable_phrases) {
  console.log(`Objectionable: ${phrase.quoted_objectionable_phrase}`);
}

Check Relevance​

Evaluate whether a comment is on-topic and check for banned topics. See Relevance Checking for full details.

const result = await client.checkRelevance(
  "This is a relevant comment",
  articleId,
  ["politics", "religion"]
);

console.log(`On Topic: ${result.on_topic.on_topic}`);
console.log(`Banned Topics Found: ${result.banned_topics.banned_topics}`);

Check Dogwhistles​

Detect coded language that appears innocuous but carries hidden meanings. See Dogwhistle Detection for full details.

const result = await client.checkDogwhistle(
  "This is a comment to analyze.",
  articleId,
  ["politics", "social issues"]
);

console.log(`Dogwhistles Detected: ${result.detection.dogwhistles_detected}`);
console.log(`Confidence: ${result.detection.confidence}`);

Check Spam​

Detect spam, promotional content, and bot-generated text. See Spam Detection for full details.

const result = await client.checkSpam(
  "Buy cheap watches at example.com!",
  articleId
);

console.log(`Is Spam: ${result.is_spam}`);
console.log(`Confidence: ${result.confidence}`);

Megacall​

Run multiple analyses in a single API call for efficiency. See Megacall for full details.

const result = await client.megacall({
  comment: "Comment to analyze.",
  articleId: articleId,
  includeSpam: true,
  includeRelevance: true,
  includeCommentScore: true,
  includeDogwhistle: true,
});

if (result.spam_check) {
  console.log(`Spam: ${result.spam_check.is_spam}`);
}
if (result.comment_score) {
  console.log(`Score: ${result.comment_score.overall_score}/5`);
}

Perspective-Compatible Scoring​

If you are migrating from Google's Perspective API, these are the public compatibility endpoints to call.

Analyse a Comment​

const result = await client.perspective.analyzeComment({
  comment: {
    text: "You clearly did not read the article.",
  },
  requestedAttributes: {
    TOXICITY: {},
    INSULT: {},
  },
  spanAnnotations: true,
});
console.log(result.attributeScores.TOXICITY.summaryScore.value);
console.log(result.attributeScores.INSULT.summaryScore.value);

Send a Score Correction​

await client.perspective.suggestCommentScore({
  comment: {
    text: "You clearly did not read the article.",
  },
  attributeScores: {
    TOXICITY: {
      summaryScore: {
        value: 0.2,
        type: "PROBABILITY",
      },
    },
  },
  clientToken: "review-example-1",
});

That's it!​

You're good to go! Use Respectify's analysis to see if the comment meets the level of genuine interaction that you want to see in your online site.

We recommend using Respectify's responses to give commenters an opportunity to improve what they write. And we hope that as your users see Respectify feedback they will learn from it how and why some ways of talking are better than others.

Respectify's ethos is not to censor, but to encourage and teach how to write and interact better. In fact, we hope that encouraging healthy conversation allows interaction with a more diverse range of opinions, through assisting people to interact and understand them. So, we encourage showing Respectify's analysis to your users and providing them a chance to iterate on what they write before it's posted.