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.

TypeScript

npm install @respectify/client

Python

pip install respectify

PHP

composer require respectify/respectify-php

Check User Credentials

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

TypeScript

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}`);

Python

Blocking Client

from respectify import RespectifyClient

client = RespectifyClient(email, api_key)

result = client.check_user_credentials()
print(f"Active: {result.active}")
print(f"Plan: {result.plan_name}")
print(f"Endpoints: {result.allowed_endpoints}")

Async Client

from respectify import RespectifyAsyncClient

client = RespectifyAsyncClient(email, api_key)

result = await client.check_user_credentials()
print(f"Active: {result.active}")
print(f"Plan: {result.plan_name}")
print(f"Endpoints: {result.allowed_endpoints}")

PHP

use Respectify\RespectifyClientAsync;

$client = new RespectifyClientAsync('your-email@example.com', 'your-api-key');

$client->checkUserCredentials()
    ->then(function ($result) {
        echo "Active: " . ($result['active'] ? 'Yes' : 'No') . "\n";
        echo "Plan: " . $result['plan_name'] . "\n";
    });

$client->run();

REST API

curl -X GET https://app.respectify.ai/v0.2/usercheck \
  -H "X-User-Email: your-email@example.com" \
  -H "X-API-Key: your-api-key"

Response:

{
  "active": true,
  "status": "ACTIVE",
  "plan_name": "Professional",
  "allowed_endpoints": ["antispam", "commentscore", "relevance", "dogwhistle", "megacall"],
  "expires": "2025-12-31T23:59:59Z"
}

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.

TypeScript

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;

Python

Blocking Client

import os
from respectify import RespectifyClient

client = RespectifyClient(
    os.environ['RESPECTIFY_EMAIL'],
    os.environ['RESPECTIFY_API_KEY']
)

result = client.init_topic_from_url('https://en.wikipedia.org/wiki/Delphi')
article_id = result.article_id

# Or from text:
result = client.init_topic_from_text("Your article content here...")
article_id = result.article_id

Async Client

import os
from respectify import RespectifyAsyncClient

client = RespectifyAsyncClient(
    os.environ['RESPECTIFY_EMAIL'],
    os.environ['RESPECTIFY_API_KEY']
)

result = await client.init_topic_from_url('https://en.wikipedia.org/wiki/Delphi')
article_id = result.article_id

# Or from text:
result = await client.init_topic_from_text("Your article content here...")
article_id = result.article_id

PHP

use Respectify\RespectifyClientAsync;

$client = new RespectifyClientAsync('your-email@example.com', 'your-api-key');

$client->initTopicFromUrl('https://en.wikipedia.org/wiki/Delphi')
    ->then(function ($articleId) {
        echo "Article ID: $articleId\n";
    });

$client->run();

Comment Scoring

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

TypeScript

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}`);
}

Python

Blocking Client

result = client.evaluate_comment(
    'This is a sample comment.',
    article_id
)

print(f"Overall Score: {result.overall_score}/5")
print(f"Toxicity: {result.toxicity_score}")
print(f"Low Effort: {result.appears_low_effort}")

for fallacy in result.logical_fallacies:
    print(f"Fallacy: {fallacy.fallacy_name}")

for phrase in result.objectionable_phrases:
    print(f"Objectionable: {phrase.quoted_objectionable_phrase}")

Async Client

result = await client.evaluate_comment(
    'This is a sample comment.',
    article_id
)

print(f"Overall Score: {result.overall_score}/5")
print(f"Toxicity: {result.toxicity_score}")
print(f"Low Effort: {result.appears_low_effort}")

for fallacy in result.logical_fallacies:
    print(f"Fallacy: {fallacy.fallacy_name}")

for phrase in result.objectionable_phrases:
    print(f"Objectionable: {phrase.quoted_objectionable_phrase}")

PHP

$client->evaluateComment($articleId, 'This is a sample comment.')
    ->then(function ($result) {
        echo "Overall Score: " . $result->overallScore . "/5\n";
        echo "Toxicity: " . $result->toxicityScore . "\n";
    });

$client->run();

Check Relevance

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

TypeScript

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}`);

Python

Blocking Client

result = client.check_relevance(
    'This is a relevant comment',
    article_id,
    banned_topics=['politics', 'religion']
)

print(f"On Topic: {result.on_topic.on_topic}")
print(f"Banned Topics Found: {result.banned_topics.banned_topics}")

Async Client

result = await client.check_relevance(
    'This is a relevant comment',
    article_id,
    banned_topics=['politics', 'religion']
)

print(f"On Topic: {result.on_topic.on_topic}")
print(f"Banned Topics Found: {result.banned_topics.banned_topics}")

PHP

$client->checkRelevance($articleId, 'This is a relevant comment', ['politics', 'religion'])
    ->then(function ($result) {
        echo "On Topic: " . ($result->onTopic->onTopic ? 'Yes' : 'No') . "\n";
    });

$client->run();

Check Dogwhistles

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

TypeScript

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}`);

Python

Blocking Client

result = client.check_dogwhistle(
    'This is a comment to analyze.',
    article_id,
    sensitive_topics=['politics', 'social issues']
)

print(f"Dogwhistles Detected: {result.detection.dogwhistles_detected}")
print(f"Confidence: {result.detection.confidence}")

Async Client

result = await client.check_dogwhistle(
    'This is a comment to analyze.',
    article_id,
    sensitive_topics=['politics', 'social issues']
)

print(f"Dogwhistles Detected: {result.detection.dogwhistles_detected}")
print(f"Confidence: {result.detection.confidence}")

PHP

$client->checkDogwhistle($articleId, 'This is a comment to analyze.', ['politics'])
    ->then(function ($result) {
        echo "Detected: " . ($result->detection->dogwhistlesDetected ? 'Yes' : 'No') . "\n";
    });

$client->run();

Check Spam

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

TypeScript

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

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

Python

Blocking Client

result = client.check_spam(
    'Buy cheap watches at example.com!',
    article_id
)

print(f"Is Spam: {result.is_spam}")
print(f"Confidence: {result.confidence}")

Async Client

result = await client.check_spam(
    'Buy cheap watches at example.com!',
    article_id
)

print(f"Is Spam: {result.is_spam}")
print(f"Confidence: {result.confidence}")

PHP

$client->checkSpam('Buy cheap watches!', $articleId)
    ->then(function ($result) {
        echo "Is Spam: " . ($result->isSpam ? 'Yes' : 'No') . "\n";
    });

$client->run();

Megacall

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

TypeScript

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`);
}

Python

Blocking Client

result = client.megacall(
    'Comment to analyze.',
    article_id,
    include_spam=True,
    include_relevance=True,
    include_comment_score=True,
    include_dogwhistle=True
)

if result.spam_check:
    print(f"Spam: {result.spam_check.is_spam}")
if result.comment_score:
    print(f"Score: {result.comment_score.overall_score}/5")

Async Client

result = await client.megacall(
    'Comment to analyze.',
    article_id,
    include_spam=True,
    include_relevance=True,
    include_comment_score=True,
    include_dogwhistle=True
)

if result.spam_check:
    print(f"Spam: {result.spam_check.is_spam}")
if result.comment_score:
    print(f"Score: {result.comment_score.overall_score}/5")

PHP

$client->megacall('Comment to analyze.', $articleId, ['spam', 'relevance', 'commentscore', 'dogwhistle'])
    ->then(function ($result) {
        if ($result->spam !== null) {
            echo "Spam: " . ($result->spam->isSpam ? 'Yes' : 'No') . "\n";
        }
        if ($result->commentScore !== null) {
            echo "Score: " . $result->commentScore->overallScore . "/5\n";
        }
    });

$client->run();

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 feedback 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.