API | FastComments Docs

Die FastComments API

FastComments stellt eine API zur Verfügung, um mit vielen Ressourcen zu interagieren. Erstellen Sie Integrationen mit unserer Plattform oder bauen Sie sogar Ihre eigenen Clients!

In dieser Dokumentation finden Sie alle vom API unterstützten Ressourcen, dokumentiert mit ihren Anfrage- und Antworttypen.

Für Enterprise-Kunden wird sämtlicher API-Zugriff im Audit-Log protokolliert.

Generierte SDKs

FastComments erzeugt jetzt eine API-Spezifikation aus unserem Code (dies ist noch nicht vollständig, enthält aber viele APIs).

Wir haben jetzt auch SDKs für beliebte Sprachen:

Authentifizierung

Die API wird authentifiziert, indem Sie Ihren api key entweder als X-API-KEY Header oder als API_KEY Query-Parameter übergeben. Sie benötigen außerdem Ihre tenantId für API-Aufrufe. Diese kann auf derselben Seite wie Ihr api key abgerufen werden.

Sicherheitshinweis

Diese Routen sind dafür gedacht, von einem Server aufgerufen zu werden. RUFEN SIE SIE NICHT aus einem Browser auf. Wenn Sie dies tun, wird Ihr API-Schlüssel offengelegt - dadurch erhält jede Person, die den Quellcode einer Seite einsehen kann, vollen Zugriff auf Ihr Konto!

Header: X-API-KEY
Header: X-TENANT-ID

Authentifizierungsoption Zwei - Query-Parameter

Query-Parameter: API_KEY
Query-Parameter: tenantId

API-Ressourcen

Ressourcennutzung

Es sollte beachtet werden, dass das Abrufen von Daten aus der API als Nutzung auf Ihrem Konto gezählt wird.

Jede Ressource listet diese Nutzung in ihrem eigenen Abschnitt auf.

Einige Ressourcen sind teurer zu bedienen als andere. Jeder Endpunkt hat festgelegte Kosten in Credits pro API-Aufruf. Für einige Endpunkte variiert die Anzahl der Credits basierend auf den Optionen und Antwortgrößen.

Die API-Nutzung kann auf der Abrechnungsanalyse-Seite überprüft werden und wird alle paar Minuten aktualisiert.

Hinweis!

Wir empfehlen, zuerst die Seiten-Dokumentation zu lesen, um Verwirrung bei der Bestimmung zu vermeiden, welche Werte für urlId in der Comment-API übergeben werden sollen.

Daten aggregieren

Resource: Aggregate as GET /api/v1/aggregate Credit Cost: 1

Diese API aggregiert Dokumente durch Gruppierung (wenn groupBy angegeben ist) und wendet mehrere Operationen an. Verschiedene Operationen (z.B. sum, countDistinct, avg, usw.) werden unterstützt.

Die Kosten sind variabel. Alle 500 gescannten Objekte kosten 1 API-Credit.

Die maximal erlaubte Speichernutzung pro API-Aufruf beträgt standardmäßig 64MB, und standardmäßig dürfen Sie nur eine Aggregation gleichzeitig ausführen. Wenn Sie mehrere Aggregationen gleichzeitig einreichen, werden sie in die Warteschlange gestellt und in der Reihenfolge der Einreichung ausgeführt. Ausstehende Aggregationen warten maximal 60 Sekunden, danach wird die Anfrage zeitüberschritten. Einzelne Aggregationen können bis zu 5 Minuten laufen.

Wenn Sie verwaltete Tenants haben, können Sie alle untergeordneten Tenant-Ressourcen in einem Aufruf aggregieren, indem Sie den parentTenantId-Query-Parameter übergeben.

Beispiele

Beispiel: Eindeutige Werte zählen

Eindeutige Werte zählen cURL Beispiel

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "urlId", "alias": "urlId" },
        { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Eindeutige Werte zählen Antwort

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": {
                "distinctCounts": {
                    "someone@somewhere.com": 1,
                    "someone2@somewhere.com": 1
                }
            }
        },
        {
            "urlId": {
                "distinctCounts": {
                    "some-page": 2
                }
            }
        }
    ],
    "stats": { "scanned": 2 }
}

Beispiel: Distinct Count

Distinct Count Werte cURL Beispiel

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "countDistinct", "field": "urlId", "alias": "urlId" },
        { "op": "countDistinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Antwort:

Distinct Count Werte Antwort

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": { "distinctCount": 2 },
            "urlId": { "distinctCount": 1 }
        }
    ],
    "stats": { "scanned": 2 }
}

Beispiel: Werte mehrerer Felder summieren

Werte summieren cURL Beispiel

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "sum", "field": "votes", "alias": "votes" },
        { "op": "sum", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Antwort:

Werte summieren Antwort

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 2 },
            "votesUp": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 2 }
}

Beispiel: Durchschnittswerte mehrerer Felder

Durchschnittswerte cURL Beispiel

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "avg", "field": "votes", "alias": "votes" },
        { "op": "avg", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Antwort:

Durchschnittswerte Antwort

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 1 },
            "votesUp": { "numericValue": 1 }
        }
    ],
    "stats": { "scanned": 2 }
}

Beispiel: Min/Max-Werte mehrerer Felder

Min/Max-Werte cURL Beispiel

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "min", "field": "votes", "alias": "votes" },
        { "op": "min", "field": "votesUp", "alias": "votesUp" },
        { "op": "max", "field": "votes", "alias": "votes" },
        { "op": "max", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Antwort:

Min/Max-Werte Antwort

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 0 },
            "votesUp": { "numericValue": 0 },
            "votes": { "numericValue": 2 },
            "votesUp": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 2 }
}

Beispiel: Eindeutige Werte mehrerer Felder zählen

Eindeutige Werte zählen cURL Beispiel

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "urlId", "alias": "urlId" },
        { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Antwort:

Eindeutige Werte zählen Antwort

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": {
                "distinctCounts": {
                    "someone@somewhere.com": 1,
                    "someone2@somewhere.com": 1
                }
            },
            "urlId": {
                "distinctCounts": {
                    "some-page": 2
                }
            }
        }
    ],
    "stats": { "scanned": 2 }
}

Beispiel: Abfrageerstellung

Abfrageerstellung cURL Beispiel

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "groupBy": ["commenterName"],
    "query": [
        { "key": "approved", "value": true, "operator": "eq" },
        { "key": "commenterName", "value": "some-username-2", "operator": "eq" }
    ],
    "operations": [
        { "op": "sum", "field": "votes", "alias": "votes" }
    ]
}'

Antwort:

Abfrageerstellung Antwort

Copy

{
    "status": "success",
    "data": [
        {
            "groups": { "commenterName": "some-username-2" },
            "votes": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 1 }
}

Beispiel: Kommentare zur Überprüfung zählen

Ausstehende Überprüfungskommentare zählen cURL Beispiel

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "query": [
        { "key": "reviewed", "value": true, "operator": "not_eq" }
    ],
    "operations": [
        { "op": "count", "field": "id", "alias": "count" }
    ]
}'

Antwort:

Ausstehende Überprüfungskommentare zählen Antwort

Copy

{
    "status": "success",
    "data": [
        { "count": { "numericValue": 2 } }
    ],
    "stats": { "scanned": 2 }
}

Beispiel: Aufschlüsselung von genehmigten, überprüften und Spam-Kommentaren

Aufschlüsselung von Kommentaren cURL Beispiel

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "approved", "alias": "approved" },
        { "op": "distinct", "field": "reviewed", "alias": "reviewed" },
        { "op": "distinct", "field": "isSpam", "alias": "isSpam" }
    ]
}'

Antwort:

Aufschlüsselung von Kommentaren Antwort

Copy

{
    "status": "success",
    "data": [
        {
            "approved": { "distinctCounts": { "true": 2 } },
            "reviewed": { "distinctCounts": { "false": 2 } },
            "isSpam": { "distinctCounts": { "false": 2 } }
        }
    ],
    "stats": { "scanned": 2 }
}

Strukturen

Aggregate Anfrage-Struktur

Copy

export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';
/** An operation that will be applied on a field */
export interface AggregationOperation {
    /** The field to operate on */
    field: string;
    /** The type of operation */
    op: AggregationOpType;
    /** Optional alias for the output; if not provided, a default alias is computed */
    alias?: string;
    expandArray?: boolean;
}
export interface QueryPredicate {
    key: string
    value: string | number | boolean
    operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'
}
export interface AggregationRequest {
    query?: QueryPredicate[];
    resourceName: string;
    groupBy?: string[];
    operations: AggregationOperation[];
    sort?: {
        field: string;
        dir: 'asc' | 'desc';
    };
}
type DistinctAccumulator = Record<string, number>;
type GroupValues = Record<string, string>;
export type AggregationValue = {
    distinctCounts?: DistinctAccumulator
    distinctCount?: number
    numericValue?: number
    stringValue?: string
    groups?: GroupValues
};

Aggregate Antwort-Struktur

Copy

export type AggregationItem = Record<string, AggregationValue> & { groups?: GroupValues };
export interface AggregationResponse {
    status: APIStatus,
    data: AggregationItem[];
    stats?: {
        scanned: number;
        timeMS: number;
    };
}

Folgende Ressourcen können aggregiert werden:

AffiliateEvent
AnonymousVote
BannedUser
BatchJob
BlockedUser
Comment
CommentDeleted
CommentIdToSyncOutbound
CommentScheduled
CommentSyncLog
CustomConfig
CustomEmailTemplateRenderError
EmailToSend
EventLogEntry
ImportedCommentScheduled
ModerationGroup
Moderator
Page
PageReact
PendingVote
QuestionResult
SSOUser
SentEmail
SpamEvent
Tenant
TenantAuditLog
TenantBadge
TenantDailyUsage
TenantInvoiceHistory
TenantPackage
User
UserBadge
UserBadgeProgress
UserNotification
UserSubscription
UserUsage
Vote

Audit-Log-Struktur

Ein AuditLog ist ein Objekt, das ein auditiertes Ereignis für Tenants darstellt, die Zugriff auf diese Funktion haben.

Die Struktur für das AuditLog-Objekt ist wie folgt:

AuditLog Struktur

Copy

interface AuditLog {
    id: string;
    userId?: string;
    username?: string;
    resourceName: string;
    crudType: 'c' | 'r' | 'u' | 'd' | 'login';
    from: string;
    url?: string;
    ip?: string;
    when: string;
    description?: string;
    serverStartDate: string;
    objectDetails?: object;
}

Das Audit-Log ist unveränderlich. Es kann auch nicht manuell beschrieben werden. Nur FastComments.com entscheidet, wann ins Audit-Log geschrieben wird. Sie können es jedoch über diese API lesen.

Ereignisse im Audit-Log verfallen nach zwei Jahren.

GET /api/v1/audit-logs

Resource: AuditLog as GET /api/v1/audit-logs Credit Cost: 10

Diese API verwendet Paginierung, bereitgestellt durch die Parameter skip, before und after. AuditLogs werden in Seiten von 1000 zurückgegeben, sortiert nach when und id.

Das Abrufen von jeweils 1000 Logs hat Credit-Kosten von 10.

Standardmäßig erhalten Sie eine Liste mit den neuesten Elementen zuerst. So können Sie beginnend mit skip=0 abfragen und paginieren, bis Sie den letzten verarbeiteten Datensatz finden.

Alternativ können Sie älteste-zuerst sortieren und paginieren, bis keine Datensätze mehr vorhanden sind.

Die Sortierung kann durch Setzen von order auf entweder ASC oder DESC erfolgen. Der Standard ist ASC.

Abfragen nach Datum sind über before und after als Zeitstempel mit Millisekunden möglich. before und after sind NICHT inklusive.

AuditLog cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/audit-logs?tenantId=demo&API_KEY=DEMO_API_SECRET&skip=0&order=ASC&before=123&after=456'

AuditLog Anfrage-Struktur

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    order?: 'ASC' | 'DESC'
    skip?: number
    before?: number
    after?: number
}

AuditLog Antwort-Struktur

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The logs! **/
    auditLogs: AuditLog[]
}

Kommentarstruktur

Ein Comment-Objekt repräsentiert einen Kommentar, der von einem Benutzer hinterlassen wurde.

Die Beziehung zwischen übergeordneten und untergeordneten Kommentaren wird über parentId definiert.

Die Struktur für das Comment-Objekt ist wie folgt:

Comment Struktur

Copy

interface Comment {
    /** READONLY: Set to true if the spam engine determined the comment was spam. **/
    aiDeterminedSpam?: boolean
    /** Whether the comment is approved to show. Set to true when saving the comment, else it will be hidden. **/
    approved?: boolean
    /** The user's avatar. **/
    avatarSrc?: string
    /** Child comments. Not populated in all scenarios. Used when asTree is set to true via the API. **/
    children: Comment[]
    /** The commenter's raw comment. **/
    comment: string
    /** READONLY: The commenter's comment parsed into HTML. **/
    commentHTML?: string
    /** The commenter's email. Required if anonymous commenting is off. **/
    commenterEmail?: string
    /** The commenter's link (for example, their blog). **/
    commenterLink?: string
    /** The commenter's name. Always required. If not available, set to something like "Anonymous". **/
    commenterName: string
    /** The date the comment was left, in UTC epoch. **/
    date: number
    /** The "display label" for the comment - for example "Admin", "Moderator", or something like "VIP User". **/
    displayLabel?: string
    /** The domain the comment was posted on. **/
    domain?: string
    /** READONLY: The number of times the comment was flagged. **/
    flagCount?: number
    /** The #hashtags written in the comment that were successfully parsed. You can also manually add hashtags, for querying, but they won't display in the comment text automatically. **/
    hashTags?: CommentHashTag[]
    /** READONLY: Does the comment contain images? **/
    hasImages?: boolean
    /** READONLY: Does the comment contain links? **/
    hasLinks?: boolean
    /** READONLY: The unique comment id. **/
    id: string
    /** Only on create! This is hashed for storage. **/
    ip?: string
    /** READONLY: Did the current user block the user that wrote this comment? **/
    isBlocked?: boolean
    /** READONLY: Is the comment by an admin? Automatically set based on userId. **/
    isByAdmin?: boolean
    /** READONLY: Is the comment by a moderator? Automatically set based on userId. **/
    isByModerator?: boolean
    /** Set to true if the comment was soft deleted (placeholder had to be left due to some other configuration). **/
    isDeleted?: boolean
    /** Set to true if the user's account was deleted and the comment had to be retained. **/
    isDeletedUser?: boolean
    /** READONLY: Is the flagged by the currently logged-in user (contextUserId)? **/
    isFlagged?: boolean
    /** Is the comment pinned? **/
    isPinned?: boolean
    /** Is the comment locked for new replies (moderators still can reply)? **/
    isLocked?: boolean
    /** Is the comment spam? **/
    isSpam?: boolean
    /** READONLY: Is the comment voted down for the current user (contextUserId)? **/
    isVotedDown?: boolean
    /** READONLY: Is the comment voted up for the current user (contextUserId)? **/
    isVotedUp?: boolean
    /** The locale the comment is in. If not provided, will be derived from the language accept HTTP header. **/
    locale?: 'de_de' | 'en_us' | 'es_es' | 'fr_fr' | 'it_it' | 'ja_jp' | 'ko_kr' | 'pl_pl' | 'pt_br' | 'ru_ru' | 'tr_tr' | 'zh_cn' | 'zh_tw'
    /** READONLY: The @mentions written in the comment that were successfully parsed. **/
    mentions?: CommentUserMention[]
    /** Optional metadata associated with the comment. **/
    meta?: Record<string, string | number | boolean>
    /** The optional list of moderation group ids associated with this comment. **/
    moderationGroupIds?: string[]|null
    /** READONLY: The id of the vote object that corresponds to the vote from the current user (contextUserId) on this comment. **/
    myVoteId?: string
    /** Whether notifications were sent for this comment for commenters. To prevent notifications being sent on imports, set this to true. **/
    notificationSentForParent?: boolean
    /** Whether notifications were sent for this comment for tenant users. To prevent notifications being sent on imports, set this to true. **/
    notificationSentForParentTenant?: boolean
    /** The title of the page this comment was on. **/
    pageTitle?: string
    /** If we're replying to a comment, this is the ID that we are replying to. **/
    parentId?: string|null
    /** Whether the comment is marked reviewed. **/
    reviewed: boolean
    /** The tenant id where the comment belongs. **/
    tenantId: string
    /** The user that wrote the comment. Created automatically when saving a comment with a name/email. **/
    userId?: string|null
    /** The URL to the location that this comment is visible, like a blog post. **/
    url: string
    /** A "cleaned" version of the urlId you passed us. When saving, you specify this field, but when you fetch the comment back this will be "cleaned" and your original value moved to "urlIdRaw". **/
    urlId: string
    /** READONLY: The original urlId you passed us. **/
    urlIdRaw?: string
    /** Is the user and this comment verified? **/
    verified: boolean
    /** Number of votes up. **/
    votesUp?: number
    /** Number of votes down. **/
    votesDown?: number
    /** The "karma" of the comment (= votes up - votes down). **/
    votes?: number
}

Einige dieser Felder sind mit READONLY markiert - diese werden von der API zurückgegeben, können aber nicht gesetzt werden.

Kommentartext-Struktur

Kommentare werden in einem FastComments-Dialekt von Markdown geschrieben, was einfach Markdown plus traditionelle bbcode-Style-Tags für Bilder ist, wie [img]pfad[/img].

Text wird in zwei Feldern gespeichert. Der vom Benutzer eingegebene Text wird unverändert im comment-Feld gespeichert. Dieser wird gerendert und im commentHTML-Feld gespeichert.

Die erlaubten HTML-Tags sind b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, und br.

Es wird empfohlen, das HTML zu rendern, da es sich um eine sehr kleine Teilmenge von HTML handelt und der Bau eines Renderers ziemlich einfach ist. Es gibt mehrere Bibliotheken für React Native und Flutter, die dabei helfen können.

Sie können auch den nicht normalisierten Wert des comment-Feldes rendern. Ein Beispiel-Parser ist hier..

Der Beispiel-Parser könnte auch angepasst werden, um mit HTML zu arbeiten und die HTML-Tags in erwartete Elemente für Ihre Plattform zu transformieren.

Tagging

Wenn Benutzer in einem Kommentar markiert werden, werden die Informationen in einer Liste namens mentions gespeichert. Jedes Objekt in dieser Liste hat die folgende Struktur.

Das Comment Mentions Objekt

Copy

Run

interface CommentUserMention {
    /** The user id. For SSO users, this will have your tenant id prefixed. **/
    id: string
    /** The final @mention tag text, including the @ symbol. **/
    tag: string
    /** The original @mention tag text, including the @ symbol. **/
    rawTag: string
    /** What type of user was tagged. user = FastComments.com account. sso = SSOUser. **/
    type: 'user'|'sso'
    /** If the user opts out of notifications, this will still be set to true. **/
    sent: boolean
}

HashTags

Wenn Hashtags verwendet und erfolgreich geparst werden, werden die Informationen in einer Liste namens hashTags gespeichert. Jedes Objekt in dieser Liste hat die folgende Struktur. Hashtags können auch manuell zum hashTags-Array des Kommentars für Abfragen hinzugefügt werden, wenn retain gesetzt ist.

Das Comment HashTag Objekt

Copy

Run

interface CommentHashTag {
    /** The hashtag id. **/
    id: string
    /** The final #hashtag tag text, including the # symbol. **/
    tag: string
    /** If the hashtag is associated with a custom URL, this will be defined. **/
    url?: string
    /** If we should retain the hashtag, even if it does not exist in the comment text, when the comment is updated. Useful for tagging comments without changing comment text. **/
    retain?: boolean
}

GET /api/v1/comments

Resource: Comment as GET /api/v1/comments Credit Cost: 1

Diese API wird verwendet, um Kommentare zur Anzeige für einen Benutzer abzurufen. Sie filtert beispielsweise automatisch nicht genehmigte oder Spam-Kommentare heraus.

Paginierung

Die Paginierung kann auf zwei Arten erfolgen, abhängig von den Leistungsanforderungen und dem Anwendungsfall:

Am schnellsten: Vorberechnete Paginierung:
1. So funktioniert FastComments, wenn Sie unsere vorgefertigten Widgets und Clients verwenden.
2. Ein Klick auf "weiter" erhöht einfach die Seitenzahl.
3. Sie können sich das so vorstellen, als würde es durch einen Key-Value-Speicher abgerufen.
4. Definieren Sie auf diese Weise einfach einen page-Parameter beginnend bei 0 und eine Sortierrichtung als direction.
5. Seitengrößen können über Anpassungsregeln konfiguriert werden.
Am flexibelsten: Flexible Paginierung:
1. Auf diese Weise können Sie benutzerdefinierte limit- und skip-Parameter definieren. Übergeben Sie nicht page.
2. Sortierrichtung direction wird ebenfalls unterstützt.
3. limit ist die Gesamtzahl, die nach Anwendung von skip zurückgegeben wird.
  - Beispiel: Setzen Sie skip = 200, limit = 100 bei Seitengröße = 100 und page = 2.
4. Untergeordnete Kommentare zählen weiterhin bei der Paginierung. Sie können dies mit der Option asTree umgehen.
  - Sie können untergeordnete Kommentare über limitChildren und skipChildren paginieren.
  - Sie können die Tiefe der zurückgegebenen Threads über maxTreeDepth begrenzen.

Threads

Bei Verwendung der Vorberechneten Paginierung werden Kommentare nach Seite gruppiert und Kommentare in Threads beeinflussen die Gesamtseite.
1. Auf diese Weise können Threads auf dem Client basierend auf parentId bestimmt werden.
2. Beispiel: Bei einer Seite mit einem Kommentar der obersten Ebene und 29 Antworten und der Einstellung page=0 in der API - erhalten Sie nur den Kommentar der obersten Ebene und die 29 untergeordneten.
3. Beispielbild hier, das mehrere Seiten illustriert.
Bei Verwendung der Flexiblen Paginierung können Sie einen parentId-Parameter definieren.
1. Setzen Sie diesen auf null, um nur Kommentare der obersten Ebene zu erhalten.
2. Um dann Threads anzuzeigen, rufen Sie die API erneut auf und übergeben parentId.
3. Eine gängige Lösung ist, einen API-Aufruf für die Kommentare der obersten Ebene zu machen und dann parallele API-Aufrufe für die untergeordneten Kommentare jedes Kommentars zu machen.
NEU seit Feb 2023! Als Baum abrufen mit &asTree=true.
1. Sie können sich das als Flexible Paginierung als Baum vorstellen.
2. Nur die Kommentare der obersten Ebene zählen bei der Paginierung.
3. Setzen Sie parentId=null, um den Baum am Wurzelknoten zu beginnen (Sie müssen parentId setzen).
4. Setzen Sie skip und limit für die Paginierung.
5. Setzen Sie asTree auf true.
6. Die Credit-Kosten erhöhen sich um das 2-fache, da unser Backend in diesem Szenario viel mehr Arbeit leisten muss.
7. Setzen Sie maxTreeDepth, limitChildren und skipChildren nach Bedarf.

Bäume erklärt

Bei Verwendung von asTree kann es schwierig sein, die Paginierung nachzuvollziehen. Hier ist eine hilfreiche Grafik:

Baum-Paginierung Diagramm

Kommentare im Kontext eines Benutzers abrufen

Die /comments-API kann in zwei Kontexten für verschiedene Anwendungsfälle verwendet werden:

Für die Rückgabe von Kommentaren, sortiert und mit Informationen versehen, um Ihren eigenen Client zu erstellen.
- Definieren Sie in diesem Fall einen contextUserId-Abfrageparameter.
Zum Abrufen von Kommentaren von Ihrem Backend für benutzerdefinierte Integrationen.
- Die Plattform verwendet standardmäßig dies ohne contextUserId.

Kommentare Vorberechnete Paginierung

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&page=0&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR'

Kommentare Flexible Paginierung

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10'

Kommentare Flexible Paginierung im Benutzerkontext

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id'

Kommentare Flexible Paginierung im Benutzerkontext nur für Kommentare der obersten Ebene

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null'

Kommentare als Baum abrufen

Es ist möglich, die Kommentare als Baum zurückzugeben, wobei die Paginierung nur die Kommentare der obersten Ebene zählt.

Kommentare als Baum im Benutzerkontext

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true'

Möchten Sie nur die Kommentare der obersten Ebene und die unmittelbaren Kinder erhalten? Hier ist eine Möglichkeit:

Kommentare als Baum mit maximaler Tiefe

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&maxTreeDepth=1&limitChildren=10'

In Ihrer Benutzeroberfläche müssen Sie jedoch möglicherweise wissen, ob bei jedem Kommentar eine Schaltfläche "Antworten anzeigen" angezeigt werden soll. Beim Abrufen von Kommentaren über einen Baum gibt es eine hasChildren-Eigenschaft, die bei Bedarf an Kommentare angehängt wird.

Kommentare als Baum abrufen, Suche nach Hash-Tag

Es ist möglich, mit der API nach Hashtag zu suchen, über Ihren gesamten Tenant (nicht auf eine Seite oder urlId beschränkt).

In diesem Beispiel lassen wir urlId weg und suchen nach mehreren Hashtags. Die API gibt nur Kommentare zurück, die alle angeforderten Hashtags haben.

Kommentare als Baum im Benutzerkontext, nach Hash-Tag

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&hashTag=TestTag&hashTag=OtherTestTag'

Alle Anfrageparameter

Kommentare Anfragestruktur

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The urlId (page url, or article id) the comments are associated with. **/
    urlId?: string
    /** Limit the comments returned by this user. **/
    userId?: string
    /** Use this to search by hashtag. To drill down to the intersection of multiple hashtags, do &hashTag=a&hashTag=b. **/
    hashTag?: string
    /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/
    direction?: 'MR' | 'OF' | 'NF'
    /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/
    page?: number
    /** Flexible Pagination: How many comments should we return? **/
    limit?: number
    /** Flexible Pagination: How many child comments should we return for each parent? **/
    limitChildren?: number
    /** Flexible Pagination: How many comments should we skip? **/
    skip?: number
    /** Flexible Pagination: How many child comments should we skip for each parent? **/
    skipChildren?: number
    /** For determining blocked and flagged comments. **/
    contextUserId?: string
    /** For determining blocked and flagged comments. **/
    anonUserId?: string
    /** For fetching child comments. **/
    parentId?: string
    /** For fetching as a tree. **/
    asTree?: boolean
    /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/
    maxTreeDepth?: number
}

Die Antwort

Kommentare Antwortstruktur

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-date' | 'unauthorized-page' | 'invalid-pagination-request' | 'invalid-limit' | 'invalid-limit-children' | 'invalid-skip' | 'invalid-skip-children' | 'invalid-max-tree-depth'
    /** Included on failure. **/
    reason?: string
    /** The comments! **/
    comments: Comment[]
}

Hilfreiche Tipps

URL-ID

Sie möchten wahrscheinlich die Comment-API mit dem urlId-Parameter verwenden. Sie können zuerst die Pages-API aufrufen, um zu sehen, wie die verfügbaren urlId-Werte aussehen.

Anonyme Aktionen

Für anonymes Kommentieren möchten Sie wahrscheinlich anonUserId beim Abrufen von Kommentaren und beim Durchführen von Markierungen und Blockierungen übergeben.

(!) Dies ist für viele App-Stores erforderlich, da Benutzer in der Lage sein müssen, benutzergenerierten Inhalt, den sie sehen können, zu markieren, auch wenn sie nicht angemeldet sind. Wenn Sie dies nicht tun, kann Ihre App aus dem entsprechenden Store entfernt werden.

Kommentare werden nicht zurückgegeben

Überprüfen Sie, ob Ihre Kommentare genehmigt sind und kein Spam sind.

GET /api/v1/comments/:id

Resource: Comment as GET /api/v1/comments/:id Credit Cost: 1

Diese API bietet die Möglichkeit, einen einzelnen Kommentar nach ID abzurufen.

Comments Get-By-Id cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Comment Get-By-Id Anfrage-Struktur

Copy

interface CommentsGetByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Comments Get-By-Id Antwort-Struktur

Copy

interface CommentGetByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'
    /** Included on failure. **/
    reason?: string
    /** The comment! **/
    comment?: Comment
}

POST /api/v1/comments

Resource: Comment as POST /api/v1/comments Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, Kommentare zu erstellen.

Häufige Anwendungsfälle sind benutzerdefinierte UIs, Integrationen oder Importe.

Hinweise:

Diese API kann das Kommentar-Widget bei Bedarf "live" aktualisieren (dies erhöht creditsCost von 1 auf 2).
Diese API erstellt automatisch Benutzerobjekte in unserem System, wenn eine E-Mail angegeben wird.
Der Versuch, zwei Kommentare mit unterschiedlichen E-Mails, aber demselben Benutzernamen zu speichern, führt zu einem Fehler für den zweiten Kommentar.
Wenn Sie parentId angeben und ein untergeordneter Kommentar notificationSentForParent auf false hat, werden wir Benachrichtigungen für den übergeordneten Kommentar senden. Dies geschieht stündlich (wir fassen die Benachrichtigungen zusammen, um die Anzahl der gesendeten E-Mails zu reduzieren).
Wenn Sie Willkommens-E-Mails beim Erstellen von Benutzern oder Kommentarverifizierungs-E-Mails senden möchten, setzen Sie sendEmails in den Query-Parametern auf true.
Über diese API erstellte Kommentare erscheinen auf den Analytics- und Moderationsseiten der Admin-App.
"Schlechte Wörter" werden weiterhin in den Kommentatornamen und im Kommentartext maskiert, wenn die Einstellung aktiviert ist.
Über diese API erstellte Kommentare können bei Bedarf immer noch auf Spam überprüft werden.
Konfigurationen wie die maximale Kommentarlänge, wenn über die Customization Rule Admin-Seite konfiguriert, gelten auch hier.

Die minimal erforderlichen Daten zur Übermittlung, die im Kommentar-Widget angezeigt werden, sind wie folgt:

Minimales Comment POST cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "approved": true,
    "comment": "some-comment",
    "commenterName": "some-commenter-name",
    "date": 1622644382148,
    "urlId": "some-place",
    "url": "https://exmaple.com/some-page",
    "verified": true
}'

Eine realistischere Anfrage könnte so aussehen:

Comment POST cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true&doSpamCheck=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "approved": true,
    "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",
    "comment": "some-comment",
    "commenterName": "some-commenter-name",
    "commenterEmail": "fordperfect@spaceship.com",
    "date": 1622644382148,
    "isSpam": false,
    "locale": "en_us",
    "notificationSentForParent": true,
    "notificationSentForParentTenant": true,
    "reviewed": true,
    "urlId": "some-place",
    "url": "https://exmaple.com/some-page",
    "verified": true,
    "votes": 1,
    "votesUp": 2,
    "votesDown": 1,
    "ip": "123.456.789.000"
}'

Comment POST Anfrage-Struktur

Copy

interface CommentPostQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
    /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/
    isLive?: 'true' | 'false'
    sendEmails?: 'true' | 'false'
    populateNotifications?: 'true' | 'false'
}

Comment POST Antwort-Struktur

Copy

interface CommentPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email';
    /** Included on failure. **/
    reason?: string
    /** The created comment. **/
    comment?: Comment
    /** The associated user, which may or may not have already existed. **/
    user?: User
}

PATCH /api/v1/comments/:id

Resource: Comment as PATCH /api/v1/comments/:id Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, einen einzelnen Kommentar zu aktualisieren.

Hinweise:

Diese API kann das Kommentar-Widget bei Bedarf "live" aktualisieren (dies erhöht die Basis-creditsCost von 1 auf 2).
- Dies kann das Migrieren von Kommentaren zwischen Seiten "live" machen (Ändern der urlId).
- Migrationen kosten zusätzlich 2 Credits, da Seiten vorberechnet werden und dies CPU-intensiv ist.
Anders als bei der Create-API wird diese API NICHT automatisch Benutzerobjekte in unserem System erstellen, wenn eine E-Mail angegeben wird.
Über diese API aktualisierte Kommentare können bei Bedarf immer noch auf Spam überprüft werden.
Konfigurationen wie die maximale Kommentarlänge, wenn über die Customization Rule Admin-Seite konfiguriert, gelten auch hier.
Um Benutzern zu ermöglichen, ihren Kommentartext zu aktualisieren, können Sie einfach comment im Anfrage-Body angeben. Wir generieren das resultierende commentHTML.
- Wenn Sie sowohl comment als auch commentHTML definieren, werden wir das HTML nicht automatisch generieren.
- Wenn der Benutzer Erwähnungen oder Hashtags in seinem neuen Text hinzufügt, wird es weiterhin wie bei der POST-API verarbeitet.
Beim Aktualisieren von commenterEmail bei einem Kommentar ist es am besten, auch userId anzugeben. Andernfalls müssen Sie sicherstellen, dass der Benutzer mit dieser E-Mail zu Ihrem Tenant gehört, oder die Anfrage schlägt fehl.

Minimales Comment PATCH cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "comment": "some-new-comment-text"
}'

Comment PATCH Anfrage-Struktur

Copy

interface CommentPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** The user doing the update. If desired can be used to check that they can edit the comment.  **/
    contextUserId?: string
    /** Should we check if the new comment looks like spam?  **/
    doSpamCheck?: 'true' | 'false'
    /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/
    isLive?: 'true' | 'false'
}

Comment PATCH Antwort-Struktur

Copy

interface CommentPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/comments/:id

Resource: Comment as DELETE /api/v1/comments/:id Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, einen Kommentar zu löschen.

Hinweise:

Diese API kann das Kommentar-Widget bei Bedarf "live" aktualisieren (dies erhöht creditsCost von 1 auf 2).
Diese API löscht alle untergeordneten Kommentare.

Comment DELETE cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

Comment DELETE Anfrage-Struktur

Copy

interface CommentDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** The user doing the update. If desired can be used to check that they can delete the comment.  **/
    contextUserId?: string
    /** Whether the comment should be deleted "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/
    isLive?: 'true' | 'false'
}

Comment DELETE Antwort-Struktur

Copy

interface CommentDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

POST /api/v1/comments/:id/flag

Resource: Comment as POST /api/v1/comments/:id/flag Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, einen Kommentar für einen bestimmten Benutzer zu melden.

Hinweise:

Dieser Aufruf muss immer im Kontext eines Benutzers erfolgen. Der Benutzer kann ein FastComments.com-Benutzer, SSO-Benutzer oder Tenant-Benutzer sein.
Wenn ein Flag-to-Hide-Schwellenwert festgelegt ist, wird der Kommentar automatisch live ausgeblendet, nachdem er die definierte Anzahl von Malen gemeldet wurde.
Nachdem er automatisch nicht genehmigt (ausgeblendet) wurde - kann der Kommentar nur von einem Administrator oder Moderator wieder genehmigt werden. Das Aufheben der Meldung wird den Kommentar nicht wieder genehmigen.

Comment Flag cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Für anonymes Melden müssen wir eine anonUserId angeben. Dies kann eine ID sein, die die anonyme Sitzung repräsentiert, oder eine zufällige UUID. Dies ermöglicht uns, das Melden und Aufheben der Meldung von Kommentaren zu unterstützen, auch wenn ein Benutzer nicht eingeloggt ist. Auf diese Weise kann der Kommentar als gemeldet markiert werden, wenn Kommentare mit derselben anonUserId abgerufen werden.

Anonymes Comment Flag cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Comment Flag Anfrage-Struktur

Copy

interface CommentFlagQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
}

Comment Flag Antwort-Struktur

Copy

interface CommentFlagResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Included on failure. **/
    reason?: string
    /** Was the comment un-approved (hidden) due to being flagged too many times? **/
    wasUnapproved?: boolean;
}

POST /api/v1/comments/:id/un-flag

Resource: Comment as POST /api/v1/comments/:id/un-flag Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, die Markierung eines Kommentars für einen bestimmten Benutzer aufzuheben.

Hinweise:

Dieser Aufruf muss immer im Kontext eines Benutzers erfolgen. Der Benutzer kann ein FastComments.com-Benutzer, SSO-Benutzer oder Tenant-Benutzer sein.
Nachdem ein Kommentar automatisch nicht genehmigt (ausgeblendet) wurde - kann der Kommentar nur von einem Administrator oder Moderator wieder genehmigt werden. Das Aufheben der Markierung wird den Kommentar nicht wieder genehmigen.

Kommentar Markierung-Aufheben cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Für anonymes Markieren müssen wir eine anonUserId angeben. Dies kann eine ID sein, die die anonyme Sitzung repräsentiert, oder eine zufällige UUID.

Anonymes Kommentar-Markieren cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Kommentar Markierung-Aufheben Anfragestruktur

Copy

interface CommentFlagQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
}

Kommentar Markierung-Aufheben Antwortstruktur

Copy

interface CommentUnFlagResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Included on failure. **/
    reason?: string
}

POST /api/v1/comments/:id/block

Resource: Comment as POST /api/v1/comments/:id/block Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, einen Benutzer zu blockieren, der einen bestimmten Kommentar geschrieben hat. Es unterstützt das Blockieren von Kommentaren, die von FastComments.com-Benutzern, SSO-Benutzern und Tenant-Benutzern geschrieben wurden.

Es unterstützt einen commentIdsToCheck-Body-Parameter, um zu prüfen, ob andere potenziell sichtbare Kommentare auf dem Client nach dieser Aktion blockiert/entsperrt werden sollten.

Hinweise:

Dieser Aufruf muss immer im Kontext eines Benutzers erfolgen. Der Benutzer kann ein FastComments.com-Benutzer, SSO-Benutzer oder Tenant-Benutzer sein.
Die userId in der Anfrage ist der Benutzer, der das Blockieren durchführt. Zum Beispiel: Benutzer A möchte Benutzer B blockieren. Übergeben Sie userId=Benutzer A und die Kommentar-ID, die Benutzer B geschrieben hat.
Vollständig anonyme Kommentare (keine Benutzer-ID, keine E-Mail) können nicht blockiert werden und es wird ein Fehler zurückgegeben.

Comment Block cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Für anonymes Blockieren müssen wir eine anonUserId angeben. Dies kann eine ID sein, die die anonyme Sitzung repräsentiert, oder eine zufällige UUID. Dies ermöglicht uns, das Blockieren von Kommentaren zu unterstützen, auch wenn ein Benutzer nicht eingeloggt ist, indem die Kommentare mit derselben anonUserId abgerufen werden.

Anonymes Comment Block cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Comment Block Anfrage-Struktur

Copy

interface CommentBlockQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentIdsToCheck?: string[]
}

Comment Block Antwort-Struktur

Copy

interface CommentBlockResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'
    /** Included on failure. **/
    reason?: string
    /** If commentIdsToCheck is defined, entries in this map with true are also blocked. **/
    commentStatuses?: Record<string, boolean>;
}

POST /api/v1/comments/:id/un-block

Resource: Comment as POST /api/v1/comments/:id/un-block Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, einen Benutzer zu entsperren, der einen bestimmten Kommentar geschrieben hat. Es unterstützt das Entsperren von Kommentaren, die von FastComments.com-Benutzern, SSO-Benutzern und Tenant-Benutzern geschrieben wurden.

Es unterstützt einen commentIdsToCheck-Body-Parameter, um zu prüfen, ob andere potenziell sichtbare Kommentare auf dem Client nach dieser Aktion blockiert/entsperrt werden sollten.

Hinweise:

Dieser Aufruf muss immer im Kontext eines Benutzers erfolgen. Der Benutzer kann ein FastComments.com-Benutzer, SSO-Benutzer oder Tenant-Benutzer sein.
Die userId in der Anfrage ist der Benutzer, der das Entsperren durchführt. Zum Beispiel: Benutzer A möchte Benutzer B entsperren. Übergeben Sie userId=Benutzer A und die Kommentar-ID, die Benutzer B geschrieben hat.
Vollständig anonyme Kommentare (keine Benutzer-ID, keine E-Mail) können nicht blockiert werden und es wird ein Fehler zurückgegeben.

Comment Un-Block cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Anonymes Comment Un-Block cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Comment Un-Block Anfrage-Struktur

Copy

interface CommentUnBlockQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentIdsToCheck?: string[]
}

Comment Un-Block Antwort-Struktur

Copy

interface CommentUnBlockResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'
    /** Included on failure. **/
    reason?: string
    /** If commentIdsToCheck is defined, entries in this map with true are still blocked. If false, you might want to un-hide the comments from the user so they don't have to refresh. **/
    commentStatuses?: Record<string, boolean>;
}

Struktur der E-Mail-Vorlage

Ein EmailTemplate-Objekt repräsentiert die Konfiguration für eine benutzerdefinierte E-Mail-Vorlage für einen Tenant.

Das System wählt die zu verwendende E-Mail-Vorlage über:

Ihren Typ-Identifikator, wir nennen dies emailTemplateId. Dies sind Konstanten.
Die domain. Wir versuchen zuerst, eine Vorlage für die Domain zu finden, mit der das zugehörige Objekt (wie ein Comment) verbunden ist, und wenn keine Übereinstimmung gefunden wird, versuchen wir, eine Vorlage zu finden, bei der domain null oder * ist.

Die Struktur des EmailTemplate-Objekts ist wie folgt:

E-Mail-Vorlagen Struktur

Copy

interface EmailTemplate {
    id: string
    tenantId: string
    emailTemplateId: string
    displayName: string
    /** READONLY **/
    createdAt: string
    /** READONLY **/
    updatedAt: string
    /** READONLY **/
    updatedByUserId: string
    /** The domain the template should be associated with. **/
    domain?: string | '*' | null
    /** The email template content in EJS syntax. **/
    ejs: string
    /** A map of overridden translation keys to values, for each supported locale. **/
    translationOverridesByLocale: Record<string, Record<string, string>>
    /** An object that represents the render context of the template. **/
    testData: object
}

Hinweise

Sie können die gültigen emailTemplateId-Werte vom /definitions-Endpunkt abrufen.
Der /definitions-Endpunkt enthält auch die Standardübersetzungen und Testdaten.
Vorlagen können nicht gespeichert werden, wenn sie eine ungültige Struktur oder Testdaten haben.

GET /api/v1/email-templates/:id

Resource: EmailTemplate as GET /api/v1/email-templates/:id Credit Cost: 1

Einzelne EmailTemplates können nach ihrer entsprechenden id abgerufen werden (NICHT emailTemplateId).

EmailTemplate nach ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

EmailTemplate nach ID Anfragestruktur

Copy

interface EmailTemplatesByIdRequestQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate nach ID Antwortstruktur

Copy

interface EmailTemplateResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Included on failure. **/
    reason?: string
    emailTemplate?: EmailTemplate | null
}

GET /api/v1/email-templates

Resource: EmailTemplate as GET /api/v1/email-templates Credit Cost: 1

Diese API verwendet Paginierung, bereitgestellt durch den page-Abfrageparameter. EmailTemplates werden in Seiten von 100 zurückgegeben, sortiert nach createdAt und dann id.

EmailTemplate cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

EmailTemplate Anfragestruktur

Copy

interface EmailTemplatesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The page to fetch, starting with 0. **/
    page: number
}

EmailTemplate Antwortstruktur

Copy

interface EmailTemplatesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    emailTemplates: EmailTemplate[]
}

PATCH /api/v1/email-templates/:id

Resource: EmailTemplate as PATCH /api/v1/email-templates/:id Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, eine E-Mail-Vorlage zu aktualisieren, indem nur die ID und die zu aktualisierenden Attribute angegeben werden.

Beachten Sie, dass alle gleichen Validierungen für das Erstellen einer Vorlage auch gelten, zum Beispiel:

Die Vorlage muss renderbar sein. Dies wird bei jeder Aktualisierung überprüft.
Sie können keine doppelten Vorlagen für dieselbe Domain haben (ansonsten würde eine stillschweigend ignoriert werden).

EmailTemplate PATCH cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "Some New Name",
}'

EmailTemplate PATCH Anfragestruktur

Copy

interface EmailTemplatePatchQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate PATCH Antwortstruktur

Copy

interface EmailTemplatePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'not-found' | 'unexpected-param' | 'invalid-email-template-id' | 'unauthorized' | 'domain-invalid' | 'duplicate' | 'does-not-render';
    /** Included on failure. **/
    reason?: string
    /** The updated email template. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates

Resource: EmailTemplate as POST /api/v1/email-templates Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, E-Mail-Vorlagen zu erstellen.

Hinweise:

Sie können nicht mehrere Vorlagen mit derselben emailTemplateId und derselben Domain haben.
Sie können jedoch eine Wildcard-Vorlage (domain = *) und eine domainspezifische Vorlage für dieselbe emailTemplateId haben.
Die Angabe von domain ist nur relevant, wenn Sie verschiedene Domains haben oder spezifische Vorlagen zum Testen verwenden möchten (domain auf localhost usw. gesetzt).
Wenn Sie domain angeben, muss es mit einer DomainConfig übereinstimmen. Bei einem Fehler wird eine Liste gültiger Domains bereitgestellt.
Die Vorlagensyntax ist EJS und wird mit einem Timeout von 500ms gerendert. P99 für das Rendern liegt bei <5ms, wenn Sie also 500ms erreichen, stimmt etwas nicht.
Ihre Vorlage muss mit Ihren angegebenen testData gerendert werden, um zu speichern. Renderfehler werden aggregiert und im Dashboard gemeldet (bald über API verfügbar).

Die Mindestdaten, die zum Hinzufügen einer Vorlage erforderlich sind, sind wie folgt:

Minimales EmailTemplate POST cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."
}'

Möglicherweise möchten Sie Vorlagen pro Website haben, in diesem Fall definieren Sie domain:

EmailTemplate POST cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is some email content!",
    "domain": "somespecificsite.com",
}'

EmailTemplate POST Anfragestruktur

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate POST Antwortstruktur

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'invalid-email-template-id' | 'domain-invalid' | 'duplicate' | 'does-not-render';
    /** Included on failure. **/
    reason?: string
    /** The created template. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates/render

Resource: EmailTemplate as POST /api/v1/email-templates/render Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, E-Mail-Vorlagen in der Vorschau anzuzeigen.

Minimales EmailTemplate Vorschau POST cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates/render?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."
}'

EmailTemplate POST Anfragestruktur

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate POST Antwortstruktur

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';
    /** Included on failure. **/
    reason?: string
    /** The rendered HTML on success. **/
    html?: string
}

DELETE /api/v1/email-templates/:id

Resource: EmailTemplate as DELETE /api/v1/email-templates/:id Credit Cost: 1

Diese Route ermöglicht das Entfernen einer einzelnen EmailTemplate nach ID.

EmailTemplate Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

EmailTemplate Entfernen Anfragestruktur

Copy

interface EmailTemplateRequestQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate Entfernen Antwortstruktur

Copy

interface EmailTemplateDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
}

Hashtag-Struktur

Ein HashTag-Objekt repräsentiert ein Tag, das von einem Benutzer hinterlassen werden kann. HashTags können verwendet werden, um auf einen externen Inhalt zu verlinken oder um zusammengehörige Kommentare zu verbinden.

Die Struktur des HashTag-Objekts ist wie folgt:

HashTag Struktur

Copy

interface HashTag {
    /** Should start with the "#" or desired character. **/
    tag: string
    /** An optional URL that the hashtag can point to. Instead of filtering comments by hashtag, the UI will redirect to this upon click. **/
    url?: string
    /** READONLY **/
    createdAt: string
}

Hinweise:

In einigen API-Endpunkten werden Sie sehen, dass der Hashtag in der URL verwendet wird. Denken Sie daran, Werte URL-zu-kodieren. Zum Beispiel sollte # stattdessen als %23 dargestellt werden.
Einige dieser Felder sind als READONLY markiert - diese werden von der API zurückgegeben, können aber nicht gesetzt werden.

GET /api/v1/hash-tags

Resource: HashTag as GET /api/v1/hash-tags Credit Cost: 1

Diese API verwendet Paginierung, bereitgestellt durch den page-Abfrageparameter. HashTags werden in Seiten von 100 zurückgegeben, sortiert nach tag.

HashTag cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

HashTag Anfragestruktur

Copy

interface HashTagsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The page to fetch, starting with 0. **/
    page: number
}

HashTag Antwortstruktur

Copy

interface HashTagsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The hashtags! **/
    hashTags: HashTag[]
}

PATCH /api/v1/hash-tags/:tag

Resource: HashTag as PATCH /api/v1/hash-tags/:tag Credit Cost: 1

Diese Route bietet die Möglichkeit, einen einzelnen HashTag zu aktualisieren.

HashTag Aktualisieren cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/some-`page`"
}'

HashTag Aktualisieren Anfragestruktur

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Aktualisieren Antwortstruktur

Copy

interface HashTagPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag' |  'already-exists'
    /** Included on failure. **/
    reason?: string
    hashTag?: HashTag; // We return the complete updated hashtag on success.
}

POST /api/v1/hash-tags

Resource: HashTag as POST /api/v1/hash-tags Credit Cost: 1

Diese Route bietet die Möglichkeit, einen einzelnen HashTag hinzuzufügen.

HashTag Erstellen cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "tag": "#example",
    "url": "https://example.com/some-page"
}'

HashTag Erstellen Anfragestruktur

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Erstellen Antwortstruktur

Copy

interface HashTagPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'
    /** Included on failure. **/
    reason?: string
    hashTag?: HashTag; // We return the complete created hashtag on success.
}

POST /api/v1/hash-tags/bulk

Resource: HashTag as POST /api/v1/hash-tags/bulk Credit Cost: 1

Diese Route bietet die Möglichkeit, bis zu 100 HashTag-Objekte auf einmal hinzuzufügen.

HashTag Massen-Erstellen cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/hash-tags/bulk?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": [
        {
            "tag": "#example",
            "url": "https://example.com/some-page"
        }
    ]
}'

HashTag Massen-Erstellen Anfragestruktur

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Massen-Erstellen Antwortstruktur

Copy

interface HashTagBulkPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'
    /** Included on failure. **/
    reason?: string
    results?: HashTagPostResponse[]; // We return a list of HashTagPostResponse objects for each provided tag.
}

DELETE /api/v1/hash-tags/:tag

Resource: HashTag as DELETE /api/v1/hash-tags/:tag Credit Cost: 1

Diese Route ermöglicht das Entfernen eines HashTag-Benutzers anhand des angegebenen Tags.

Beachten Sie, dass Hashtags, sofern die automatische HashTag-Erstellung nicht deaktiviert ist, von einem Benutzer neu erstellt werden können, indem er beim Kommentieren den Hashtag angibt.

HashTag Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET'

HashTag Entfernen Anfragestruktur

Copy

interface HashTagDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Entfernen Antwortstruktur

Copy

interface HashTagDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

Moderator-Struktur

Ein Moderator-Objekt repräsentiert die Konfiguration für einen Moderator.

Es gibt drei Arten von Moderatoren:

Administratorbenutzer, die das isCommentModeratorAdmin-Flag haben.
SSO-Benutzer mit dem isCommentModeratorAdmin-Flag.
Reguläre Kommentatoren oder FastComments.com-Benutzer, die als Moderatoren eingeladen werden.

Die Moderator-Struktur wird verwendet, um den Moderationsstatus von Anwendungsfall 3 darzustellen.

Wenn Sie einen Benutzer über die API als Moderator einladen möchten, verwenden Sie die Moderator-API, indem Sie einen Moderator erstellen und ihn einladen.

Wenn der Benutzer kein FastComments.com-Konto hat, hilft ihm die Einladungs-E-Mail bei der Einrichtung. Wenn er bereits ein Konto hat, erhält er Moderationszugriff auf Ihren Tenant und die userId des Moderator-Objekts wird aktualisiert, um auf seinen Benutzer zu verweisen. Sie werden keinen API-Zugriff auf seinen Benutzer haben, da dieser in diesem Fall ihm selbst gehört und von FastComments.com verwaltet wird.

Wenn Sie eine vollständige Verwaltung des Benutzerkontos benötigen, empfehlen wir entweder die Verwendung von SSO oder das Hinzufügen als Tenant-Benutzer und dann das Hinzufügen eines Moderator-Objekts, um ihre Statistiken zu verfolgen.

Die Moderator-Struktur kann als Statistik-Verfolgungsmechanismus für die Anwendungsfälle 1 und 2 verwendet werden. Nachdem Sie den Benutzer erstellt haben, fügen Sie ein Moderator-Objekt mit definierter userId hinzu und ihre Statistiken werden auf der Kommentar-Moderatoren-Seite verfolgt.

Die Struktur des Moderator-Objekts ist wie folgt:

Moderator Struktur

Copy

interface Moderator {
    name: string
    email: string
    tenantId: string
    userId?: string|null
    acceptedInvite?: boolean
    markReviewedCount?: number
    deletedCount?: number
    markedSpamCount?: number
    approvedCount?: number
    editedCount?: number
    bannedCount?: number
    createdAt: string
    moderationGroupIds?: string[]|null
}

GET /api/v1/moderators/:id

Resource: Moderator as GET /api/v1/moderators/:id Credit Cost: 1

Diese Route gibt einen einzelnen Moderator nach seiner ID zurück.

Moderator nach ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Moderator Anfragestruktur

Copy

interface ModeratorByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator Antwortstruktur

Copy

interface ModeratorByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    moderator?: Moderator
}

GET /api/v1/moderators

Resource: Moderator as GET /api/v1/moderators Credit Cost: 1

Diese API verwendet Paginierung, bereitgestellt durch den skip-Abfrageparameter. Moderatoren werden in Seiten von 100 zurückgegeben, sortiert nach createdAt und id.

Die Kosten basieren auf der Anzahl der zurückgegebenen Moderatoren und kosten 1 Credit pro 10 zurückgegebene Moderatoren.

Moderator cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

Moderator Anfragestruktur

Copy

interface ModeratorsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of moderators to skip for pagination. **/
    skip?: number
}

Moderator Antwortstruktur

Copy

interface ModeratorsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    moderators?: Moderator[]
}

PATCH /api/v1/moderators/:id

Resource: Moderator as PATCH /api/v1/moderators/:id Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, einen Moderator nach id zu aktualisieren.

Das Aktualisieren eines Moderator hat folgende Einschränkungen:

Die folgenden Werte dürfen beim Aktualisieren eines Moderator nicht angegeben werden:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Wenn eine userId angegeben wird, muss dieser Benutzer existieren.
Wenn eine userId angegeben wird, muss sie zum selben tenantId gehören, der in den Abfrageparametern angegeben ist.
Zwei Moderatoren im selben Tenant können nicht mit derselben email hinzugefügt werden.
Sie können die mit einem Moderator verknüpfte tenantId nicht ändern.

Moderator PATCH cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

Moderator PATCH Anfragestruktur

Copy

interface ModeratorPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator PATCH Antwortstruktur

Copy

interface ModeratorPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';
    /** Included on failure. **/
    reason?: string
}

POST /api/v1/moderators

Resource: Moderator as POST /api/v1/moderators Credit Cost: 1

Diese Route bietet die Möglichkeit, einen einzelnen Moderator hinzuzufügen.

Das Erstellen eines Moderator hat folgende Einschränkungen:

Ein name und eine email müssen immer angegeben werden. Eine userId ist optional.
Die folgenden Werte dürfen beim Erstellen eines Moderator nicht angegeben werden:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Wenn eine userId angegeben wird, muss dieser Benutzer existieren.
Wenn eine userId angegeben wird, muss sie zum selben tenantId gehören, der in den Abfrageparametern angegeben ist.
Zwei Moderatoren im selben Tenant können nicht mit derselben email hinzugefügt werden.

Wir können einen Moderator für einen Benutzer erstellen, von dem wir nur die E-Mail kennen:

Moderator Erstellen via E-Mail cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com"
}'

Oder wir können einen Moderator für einen Benutzer erstellen, der zu unserem Tenant gehört, um seine Moderationsstatistiken zu verfolgen:

Moderator Erstellen via Tenant-Benutzer cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com",
    "userId": "some-tenant-user-id"
}'

Moderator Erstellen Anfragestruktur

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator Erstellen Antwortstruktur

Copy

interface ModeratorPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    moderator?: Moderator; // We return the complete created moderator on success.
}

POST /api/v1/moderators/:id/send-invite

Resource: Moderator as POST /api/v1/moderators/:id/send-invite Credit Cost: 10

Diese Route bietet die Möglichkeit, einen einzelnen Moderator einzuladen.

Die folgenden Einschränkungen gelten für das Senden einer Einladungs-E-Mail an einen Moderator:

Der Moderator muss bereits existieren.
Der fromName darf nicht länger als 100 Zeichen sein.

Hinweise:

Wenn ein Benutzer mit der angegebenen E-Mail bereits existiert, wird er eingeladen, die Kommentare Ihres Tenants zu moderieren.
Wenn ein Benutzer mit der angegebenen E-Mail nicht existiert, führt der Einladungslink ihn durch die Erstellung seines Kontos.
Die Einladung läuft nach 30 Tagen ab.

Wir können einen Moderator für einen Benutzer erstellen, von dem wir nur die E-Mail kennen:

Moderator Einladen cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators/xyz/send-invite?tenantId=demo&API_KEY=DEMO_API_SECRET&fromName=Bob' \
  --header 'Content-Type: application/json'

Dies sendet eine E-Mail wie Bob bei TenantName lädt Sie ein, Moderator zu werden...

Moderator Einladen Anfragestruktur

Copy

interface ModeratorSendInviteQueryParams {
    tenantId: string
    API_KEY: string
    /** The email sent to the user will appear to be sent from this name. **/
    fromName: string
}

Moderator Einladen Antwortstruktur

Copy

interface ModeratorSendInviteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found | 'from-name-required' | 'from-name-invalid'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/moderators/:id

Resource: Moderator as DELETE /api/v1/moderators/:id Credit Cost: 5

Diese Route ermöglicht das Entfernen eines Moderator nach ID.

Moderator Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Moderator Entfernen Anfragestruktur

Copy

interface ModeratorDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator Entfernen Antwortstruktur

Copy

interface ModeratorDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

Struktur der Anzahl der Benachrichtigungen

Ein NotificationCount-Objekt repräsentiert die Anzahl ungelesener Benachrichtigungen und Metadaten für einen Benutzer.

Wenn es keine ungelesenen Benachrichtigungen gibt, existiert kein NotificationCount für den Benutzer.

NotificationCount-Objekte werden automatisch erstellt und können nicht über die API erstellt werden. Sie laufen auch nach einem Jahr ab.

Sie können den Zähler für ungelesene Benachrichtigungen eines Benutzers löschen, indem Sie seinen NotificationCount löschen.

Die Struktur des NotificationCount-Objekts ist wie folgt:

NotificationCount Struktur

Copy

interface NotificationCount {
    id: string // user id
    count: number
    createdAt: string // date string
    expireAt: string // date string
}

GET /api/v1/notification-count/:user_id

Resource: NotificationCount as GET /api/v1/notification-count/:user_id Credit Cost: 1

Diese Route gibt einen einzelnen NotificationCount nach Benutzer-ID zurück. Bei SSO hat die Benutzer-ID das Format <tenant id>:<user id>.

Wenn es keine ungelesenen Benachrichtigungen gibt, existiert kein NotificationCount - Sie erhalten also einen 404-Fehler.

Dies unterscheidet sich von notifications/count dadurch, dass es viel schneller ist, aber keine Filterung erlaubt.

NotificationCount nach ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notification-count/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
# -> {"status":"success","data":{"count":1,"createdAt":"2023-03-06T18:45:01.726Z","expireAt":"2024-03-06T01:25:01.726Z","id":"example"}}

NotificationCount Anfragestruktur

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
}

NotificationCount Antwortstruktur

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** Included on failure. **/
    reason?: string
    data?: NotificationCount
}

DELETE /api/v1/notification-count/:user_id

Resource: NotificationCount as DELETE /api/v1/notification-count/:user_id Credit Cost: 1

Diese Route löscht einen einzelnen NotificationCount nach Benutzer-ID. Bei SSO hat die Benutzer-ID das Format <tenant id>:<user id>.

Dadurch wird der Zähler für ungelesene Benachrichtigungen des Benutzers gelöscht (die rote Glocke im Kommentar-Widget wird ausgeblendet und der Zähler verschwindet).

DELETE NotificationCount cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/notification-count/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
# -> {"status":"success"}

NotificationCount Entfernen Anfragestruktur

Copy

interface NotificationCountDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

NotificationCount Entfernen Antwortstruktur

Copy

interface NotificationCountDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

Benachrichtigungsstruktur

Ein Notification-Objekt repräsentiert eine Benachrichtigung für einen Benutzer.

Notification-Objekte werden automatisch erstellt und können nicht über die API erstellt werden. Sie laufen auch nach einem Jahr ab. Benachrichtigungen können nicht gelöscht werden. Sie können jedoch aktualisiert werden, um viewed auf false zu setzen, und Sie können nach viewed abfragen.

Ein Benutzer kann sich auch von Benachrichtigungen für einen bestimmten Kommentar abmelden, indem er optedOut in der Benachrichtigung auf true setzt. Sie können sich wieder anmelden, indem Sie es auf false setzen.

Es gibt verschiedene Benachrichtigungstypen - prüfen Sie relatedObjectType und type.

Die Art und Weise, wie Benachrichtigungen erstellt werden, ist recht flexibel und kann durch viele Szenarien ausgelöst werden (siehe NotificationType).

Stand heute bedeutet die Existenz einer Notification nicht tatsächlich, dass eine E-Mail gesendet wird oder werden sollte. Vielmehr werden die Benachrichtigungen für den Benachrichtigungs-Feed und verwandte Integrationen verwendet.

Die Struktur des Notification-Objekts ist wie folgt:

Benachrichtigung Struktur

Copy

enum NotificationObjectType {
    Comment = 0,
    Profile = 1,
    Tenant = 2
}
enum NotificationType {
    /** If someone replied to you. **/
    RepliedToMe = 0,
    /** If someone replied anywhere in a thread (even children of children) of a thread you commented on. **/
    RepliedTransientChild = 1,
    /** If your comment was up-voted. **/
    VotedMyComment = 2,
    /** If a new comment is left on the root of a page you're subscribed to. **/
    SubscriptionReplyRoot = 3,
    /** If someone commented on your profile. **/
    CommentedOnProfile = 4,
    /** If you have a DM. **/
    DirectMessage = 5,
    /** TrialLimits is for tenant users only. **/
    TrialLimits = 6,
    /** If you were @mentioned. **/
    Mentioned = 7
}
interface Notification {
    id: string
    tenantId: string
    /** With SSO, the user id is in the format `<tenant id>:<user id>`. **/
    userId?: string
    /** When working with SSO, you only have to worry about `userId`. **/
    anonUserId?: string
    /** urlId is almost always defined. It is only optional for tenant-level notifications, which are infrequent. **/
    urlId?: string
    /** URL is cached for quick navigation to the source of the notification. **/
    url?: string
    /** Page Title is cached for quick reading of notification source. **/
    pageTitle?: string
    relatedObjectType: NotificationObjectType
    /** For example, comment id. **/
    relatedObjectId: string
    viewed: boolean
    createdAt: string // date string
    type: NotificationType
    fromCommentId?: string
    fromVoteId?: string
    /** fromUserName and fromUserAvatarSrc are cached here for quick displaying of the notification. They are updated when the user is updated. **/
    fromUserName: string
    fromUserId: string
    fromUserAvatarSrc?: string
    /** Set this to true to stop getting notifications for this object. **/
    optedOut?: boolean
}

GET /api/v1/notifications

Resource: Notification as GET /api/v1/notifications Credit Cost: 1

Diese Route gibt bis zu 30 Notification-Objekte zurück, sortiert nach createdAt, neueste zuerst.

Sie können nach userId filtern. Bei SSO hat die Benutzer-ID das Format <tenant id>:<user id>.

Ungelesene Benachrichtigungen für Benutzer cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false'

Benachrichtigungen Anfragestruktur

Copy

interface NotificationsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Paginate by skipping records. **/
    skip?: number
    /** Filter by user. **/
    userId?: string
    /** Filter by urlId. **/
    urlId?: string
    /** Filter by source comment. **/
    fromCommentId?: string
    /** Filter by read/unread. **/
    viewed?: 'true' | 'false'
    /** Filter by type. **/
    type?: NotificationType
}

Benachrichtigungen Antwortstruktur

Copy

interface NotificationsGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    notifications?: Notification[]
}

GET /api/v1/notifications/count

Resource: Notification as GET /api/v1/notifications/count Credit Cost: 2

Diese Route gibt ein Objekt zurück, das die Anzahl der Benachrichtigungen unter einem count-Parameter enthält.

Sie ist langsamer als /notification-count/ und kostet doppelt so viele Credits, ermöglicht aber die Filterung nach mehr Dimensionen.

Sie können nach denselben Parametern wie beim /notifications-Endpunkt filtern, wie z.B. userId. Bei SSO hat die Benutzer-ID das Format <tenant id>:<user id>.

Anzahl ungelesener Benachrichtigungen für Benutzer cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications/count?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false'

Anzahl ungelesener Benachrichtigungen für Benutzer für bestimmte Seite cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications/count?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false&urlId=some-article-id-or-url'

Benachrichtigungsanzahl Anfragestruktur

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Filter by user. **/
    userId?: string
    /** Filter by urlId. **/
    urlId?: string
    /** Filter by source comment. **/
    fromCommentId?: string
    /** Filter by read/unread. **/
    viewed?: 'true' | 'false'
    /** Filter by type. **/
    type?: NotificationType
}

Benachrichtigungsanzahl Antwortstruktur

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    count?: number
}

PATCH /api/v1/notifications/:id

Resource: Notification as PATCH /api/v1/notifications/:id Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, eine Notification nach id zu aktualisieren.

Das Aktualisieren einer Notification hat folgende Einschränkungen:

Sie können nur die folgenden Felder aktualisieren:
- viewed
- optedOut

Notification PATCH cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/notifications/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "viewed": false,
}'

Notification PATCH Anfragestruktur

Copy

interface NotificationPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Notification PATCH Antwortstruktur

Copy

interface NotificationPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';
    /** Included on failure. **/
    reason?: string
}

Seitenstruktur

Ein Page-Objekt repräsentiert die Seite, zu der viele Kommentare gehören können. Diese Beziehung wird durch urlId definiert.

Eine Page speichert Informationen wie den Seitentitel, die Kommentaranzahl und die urlId.

Die Struktur des Page-Objekts ist wie folgt:

Seiten Struktur

Copy

interface Page {
    id: string
    urlId: string
    url: string
    title?: string
    createdAt: string
    commentCount: number
    rootCommentCount: number
    /** Setting this to null means all SSO users can see the page. An empty list means it is closed to all users. **/
    accessibleByGroupIds?: string[] | null
    /** Is this page closed for new comments? **/
    isClosed?: boolean
}

GET /api/v1/pages

Resource: Page as GET /api/v1/pages Credit Cost: 10

Sie können derzeit nur alle Seiten (oder eine einzelne Seite über /by-url-id) abrufen, die mit Ihrem Konto verknüpft sind. Wenn Sie eine feinere Suche wünschen, kontaktieren Sie uns.

Seiten cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET'

Seiten Anfragestruktur

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Seiten Antwortstruktur

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    pages: Page[]
}

Hilfreicher Tipp

Die Comment-API erfordert eine urlId. Sie können zuerst die Pages-API aufrufen, um zu sehen, wie die verfügbaren urlId-Werte aussehen.

GET /api/v1/pages/by-url-id

Resource: Page as GET /api/v1/pages/by-url-id Credit Cost: 1

Einzelne Seiten können nach ihrer entsprechenden urlId abgerufen werden. Dies kann nützlich sein, um Seitentitel oder Kommentaranzahlen nachzuschlagen.

Seite nach URL-ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages/by-url-id?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=example-id-or-url'

Seite nach URL-ID Anfragestruktur

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
}

Seite nach URL-ID Antwortstruktur

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    page?: Page[] | null
}

Hilfreicher Tipp

Denken Sie daran, Werte wie die urlId URL-zu-kodieren.

PATCH /api/v1/pages/:id

Resource: Page as PATCH /api/v1/pages/:id Credit Cost: 1

Diese Route bietet die Möglichkeit, eine einzelne Page zu aktualisieren. Die entsprechenden Kommentare werden aktualisiert.

Seiten Aktualisieren cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/pages/my-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/some-page"
}'

Seiten Aktualisieren Anfragestruktur

Copy

interface PagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Seiten Aktualisieren Antwortstruktur

Copy

interface PagePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-id' | 'page-does-not-exist' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large'
    /** Included on failure. **/
    reason?: string
    user?: Page; // We return the complete updated page on success.
}

Hinweis

Einige Parameter im Page-Objekt werden automatisch aktualisiert. Dies sind die Zähl- und Titel-Attribute. Zähler können nicht über die API aktualisiert werden, da es sich um berechnete Werte handelt. Der Seiten-title kann über die API gesetzt werden, würde aber überschrieben werden, wenn das Kommentar-Widget auf einer Seite mit derselben urlId und einem anderen Seitentitel verwendet wird.

POST /api/v1/pages

Resource: Page as POST /api/v1/pages Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, Seiten zu erstellen.

Ein häufiger Anwendungsfall ist die Zugriffskontrolle.

Hinweise:

Wenn Sie einen Kommentar in einem Kommentar-Thread hinterlassen oder die API aufgerufen haben, um einen Comment zu erstellen, haben Sie bereits ein Page-Objekt erstellt! Sie können versuchen, es über die /by-url-id Page-Route abzurufen, indem Sie dieselbe urlId übergeben, die an das Kommentar-Widget übergeben wurde.
Die Page-Struktur enthält einige berechnete Werte. Derzeit sind dies commentCount und rootCommentCount. Sie werden automatisch befüllt und können nicht über die API gesetzt werden. Der Versuch, dies zu tun, führt dazu, dass die API einen Fehler zurückgibt.

Seite POST cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Test Page",
    "url": "some0-url",
    "urlId": "page2",
    "accessibleByGroupIds": ["SOME_GROUP_ID"]
}'

Seite POST Anfragestruktur

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Seite POST Antwortstruktur

Copy

interface PagePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large';
    /** Included on failure. **/
    reason?: string
    /** The created page. **/
    page?: Page
}

DELETE /api/v1/pages/:id

Resource: Page as DELETE /api/v1/pages/:id Credit Cost: 1

Diese Route ermöglicht das Entfernen einer einzelnen Seite nach ID.

Beachten Sie, dass die Interaktion mit dem Kommentar-Widget für eine Seite mit derselben urlId die Page einfach nahtlos neu erstellt.

Seiten Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/pages/some-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Seiten Entfernen Anfragestruktur

Copy

interface PageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Seiten Entfernen Antwortstruktur

Copy

interface PageDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'page-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

Struktur ausstehender Webhook-Ereignisse

Ein PendingWebhookEvent-Objekt repräsentiert ein in der Warteschlange befindliches Webhook-Ereignis, das aussteht.

PendingWebhookEvent-Objekte werden automatisch erstellt und können nicht manuell über die API erstellt werden. Sie laufen auch nach einem Jahr ab. Sie können gelöscht werden, wodurch die Aufgabe aus der Warteschlange entfernt wird.

Es gibt verschiedene Ereignistypen - prüfen Sie eventType (OutboundSyncEventType) und type (OutboundSyncType).

Ein häufiger Anwendungsfall für diese API ist die Implementierung von benutzerdefiniertem Monitoring. Sie möchten vielleicht den /count-Endpunkt regelmäßig aufrufen, um die ausstehende Anzahl für gegebene Filter abzufragen.

Die Struktur des PendingWebhookEvent-Objekts ist wie folgt:

PendingWebhookEvent Struktur

Copy

enum OutboundSyncEventType {
    Create: 0,
    Delete: 1,
    Update: 2
}
enum OutboundSyncType {
    /** WordPress-specific sync task. **/
    WP: 0,
    Webhook: 1
}
interface PendingWebhookEvent {
    id: string
    /** The comment id associated with the event. **/
    commentId: string
    /** The comment object for the event at the time of the event. We started adding these in Nov 2023. **/
    comment: Comment
    /** An external id that may be associated with the comment. **/
    externalId: string | null
    createdAt: Date
    tenantId: string
    attemptCount: number
    /** Set before first attempt, and after every failure. **/
    nextAttemptAt: Date
    /** Whether this is a creation, deletion, or update event... **/
    eventType: OutboundSyncEventType
    /** The type of sync to perform (WordPress, call API, etc). **/
    type: OutboundSyncType
    /** The domain that matched the comment. We use this domain to pick the API key. **/
    domain: string
    /** The last error that occurred. This type is untyped and is a "dump" of whatever happened. Usually it contains an object with statusCode, body, and a headers map. **/
    lastError: object | null
}

GET /api/v1/pending-webhook-events

Resource: PendingWebhookEvent as GET /api/v1/pending-webhook-events Credit Cost: 2

Diese Route gibt eine Liste ausstehender Webhook-Ereignisse unter einem pendingWebhookEvents-Parameter zurück.

Diese API verwendet Paginierung, bereitgestellt durch den skip-Parameter. PendingWebhookEvents werden in Seiten von 100 zurückgegeben, sortiert nach createdAt neueste zuerst.

PendingWebhookEvent cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events?tenantId=demo&API_KEY=DEMO_API_SECRET'

PendingWebhookEvent Anfragestruktur

Copy

interface PendingWebhookEventsGetQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Query for events with an attempt count greater than the specified number. **/
    attemptCountGT?: number
}

PendingWebhookEvent Antwortstruktur

Copy

interface PendingWebhookEventsGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    pendingWebhookEvents?: PendingWebhookEvent[]
}

GET /api/v1/pending-webhook-events/count

Resource: PendingWebhookEvent as GET /api/v1/pending-webhook-events/count Credit Cost: 2

Diese Route gibt ein Objekt zurück, das die Anzahl der ausstehenden Webhook-Ereignisse unter einem count-Parameter enthält.

Sie können nach denselben Parametern wie beim /pending-webhook-events-Endpunkt filtern.

PendingWebhookEvent Anzahl cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events/count?tenantId=demo&API_KEY=DEMO_API_SECRET'

PendingWebhookEvent Anzahl Anfragestruktur

Copy

interface PendingWebhookEventsCountQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Query for events with an attempt count greater than the specified number. **/
    attemptCountGT?: number
}

PendingWebhookEvent Anzahl Antwortstruktur

Copy

interface PendingWebhookEventsCountResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    count?: number
}

DELETE /api/v1/pending-webhook-events/:id

Resource: PendingWebhookEvent as DELETE /api/v1/pending-webhook-events/:id Credit Cost: 1

Diese Route ermöglicht das Löschen eines einzelnen PendingWebhookEvent.

Wenn Sie eine Massenlöschung benötigen, rufen Sie die GET-API mit Paginierung auf und rufen Sie dann diese API sequentiell auf.

DELETE PendingWebhookEvent cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

PendingWebhookEvent Löschen Anfragestruktur

Copy

interface PendingWebhookEventDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

PendingWebhookEvent Löschen Antwortstruktur

Copy

interface PendingWebhookEventDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

SSO-Benutzer-Struktur

FastComments provides an easy to use SSO solution. Updating a user's information with the HMAC-based integration is as simple as having the user load the page with an updated payload.

However, it may be desirable to manage a user outside that flow, to improve consistency of your application.

The SSO User API provides a way to CRUD objects that we call SSOUsers. These objects are different from regular Users and kept separate for type safety.

The structure for the SSOUser object is as follows:

SSOUser-Struktur

Copy

interface SSOUser {
    id: string
    username: string
    email?: string
    websiteUrl?: string
    signUpDate: number
    createdFromUrlId?: string
    loginCount?: number
    avatarSrc?: string
    optedInNotifications?: boolean
    optedInSubscriptionNotifications?: boolean
    displayLabel?: string
    displayName?: string
    isAccountOwner?: boolean // Administratorberechtigung - SSO-Benutzer mit diesem Flag werden als SSO-Administratoren abgerechnet (separat von regulären SSO-Benutzern)
    isAdminAdmin?: boolean // Administratorberechtigung - SSO-Benutzer mit diesem Flag werden als SSO-Administratoren abgerechnet (separat von regulären SSO-Benutzern)
    isCommentModeratorAdmin?: boolean // Moderatorberechtigung - SSO-Benutzer mit diesem Flag werden als SSO-Moderatoren abgerechnet (separat von regulären SSO-Benutzern)
    /** Wenn null, wird keine Zugriffskontrolle auf den Benutzer angewendet. Bei einer leeren Liste kann dieser Benutzer keine Seiten sehen oder andere Benutzer per @mention erwähnen. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** Verhindert, dass andere Benutzer die Aktivitäten dieses Benutzers (einschließlich Kommentare) in seinem Profil sehen. Standardmäßig true, um Profile von Haus aus sicher zu machen. **/
    isProfileActivityPrivate?: boolean
    /** Verhindert, dass andere Benutzer Kommentare im Profil des Benutzers hinterlassen oder vorhandene Profilkommentare sehen. Standardmäßig false. **/
    isProfileCommentsPrivate?: boolean
    /** Verhindert, dass andere Benutzer diesem Benutzer Direktnachrichten senden. Standardmäßig false. **/
    isProfileDMDisabled?: boolean
    karma?: number
    /** Optionale Konfiguration für Benutzerabzeichen. **/
    badgeConfig?: {
        /** Array von Abzeichen-IDs, die dem Benutzer zugewiesen werden. Auf 30 Abzeichen begrenzt. Die Reihenfolge wird beibehalten. Dies sind globale Abzeichen, die auf allen Seiten sichtbar sind. **/
        badgeIds: string[]
        /** Array von Abzeichen-IDs, die auf die aktuelle Seite (urlId) beschränkt sind. Diese Abzeichen werden nur auf der Seite angezeigt, auf der sie vergeben wurden. **/
        pageBadgeIds?: string[]
        /** Wenn true, werden alle vorhandenen angezeigten Abzeichen durch die bereitgestellten ersetzt. Globale und seitenbezogene Abzeichen werden unabhängig voneinander überschrieben. Wenn false, werden die bereitgestellten Abzeichen zu den bestehenden hinzugefügt. **/
        override?: boolean
        /** Wenn true, werden die Anzeigeeigenschaften der Abzeichen aus der Mandantenkonfiguration aktualisiert. **/
        update?: boolean
    }
}

Billing for SSO Users

SSO users are billed differently based on their permission flags:

Regular SSO Users: Users without admin or moderator permissions are billed as regular SSO users
SSO Admins: Users with isAccountOwner or isAdminAdmin flags are billed separately as SSO Admins (same rate as regular tenant admins)
SSO Moderators: Users with isCommentModeratorAdmin flag are billed separately as SSO Moderators (same rate as regular moderators)

Important: To prevent double billing, the system automatically deduplicates SSO users against regular tenant users and moderators by email address. If an SSO user has the same email as a regular tenant user or moderator, they will not be billed twice.

Access Control

Users can be broken into groups. This is what the groupIds field is for, and is optional.

@Mentions

By default @mentions will use username to search for other sso users when the @ character is typed. If displayName is used, then results matching username will be ignored when there is a match for displayName, and the @mention search results will use displayName.

Subscriptions

With FastComments, users can subscribe to a page by clicking the bell icon in the comment widget and clicking Subscribe.

With a regular user, we send them notification emails based on their notification settings.

With SSO Users, we split this up for backwards compatibility. Users will only get sent these additional subscription notification emails if you set optedInSubscriptionNotifications to true.

Badges

You can assign badges to SSO users using the badgeConfig property. Badges are visual indicators that appear next to a user's name in comments.

badgeIds - An array of badge IDs to assign to the user. These are global badges visible on all pages. Must be valid badge IDs created in your FastComments account. Limited to 30 badges.
pageBadgeIds - An optional array of badge IDs scoped to the current page (urlId). These badges are only displayed on the page where they were assigned. Different pages can have different page-scoped badges for the same user.
override - If true, all existing displayed badges will be replaced with the provided ones. Global and page-scoped badges are overridden independently — overriding global badges does not affect page-scoped badges, and vice versa. If false or omitted, the provided badges will be added to any existing badges.
update - If true, badge display properties will be updated from the tenant configuration whenever the user logs in.

GET /api/v1/sso-users

Resource: SSOUser as GET /api/v1/sso-users Credit Cost: 10

Diese Route gibt SSO-Benutzer in Seiten von 100 zurück. Die Paginierung wird durch den skip-Parameter bereitgestellt. Benutzer sind nach ihrem signUpDate und id sortiert.

SSOUsers cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUsers Anfragestruktur

Copy

interface SSOUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    skip?: number
}

SSOUsers Antwortstruktur

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    users: SSOUser[]
}

GET /api/v1/sso-users/by-id/:id

Resource: SSOUser as GET /api/v1/sso-users/by-id/:id Credit Cost: 1

Diese Route gibt einen einzelnen SSO-Benutzer nach seiner ID zurück.

SSOUser nach ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users/by-id/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Anfragestruktur

Copy

interface SSOUserRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Antwortstruktur

Copy

interface SSOUserByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user: SSOUser
}

GET /api/v1/sso-users/by-email/:email

Resource: SSOUser as GET /api/v1/sso-users/by-email/:email Credit Cost: 1

Diese Route gibt einen einzelnen SSO-Benutzer nach seiner E-Mail zurück.

SSOUser nach E-Mail cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users/by-email/someone@somewhere.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Anfragestruktur

Copy

interface SSOUserRequestByEmailQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Antwortstruktur

Copy

interface SSOUserByEmailResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-email' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user: SSOUser
}

PATCH /api/v1/sso-users/:id

Resource: SSOUser as PATCH /api/v1/sso-users/:id Credit Cost: 1

Diese Route bietet die Möglichkeit, einen einzelnen SSO-Benutzer zu aktualisieren.

SSOUser Aktualisieren cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "notfordperfect"
}'

SSOUser Aktualisieren Anfragestruktur

Copy

interface SSOUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

SSOUser Aktualisieren Antwortstruktur

Copy

interface SSOUserPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the complete updated user on success.
}

POST /api/v1/sso-users

Resource: SSOUser as POST /api/v1/sso-users Credit Cost: 1

Diese Route ermöglicht die Erstellung eines einzelnen SSO-Benutzers.

Der Versuch, zwei Benutzer mit derselben ID zu erstellen, führt zu einem Fehler.

SSOUser Erstellen cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "my-user-id",
    "username": "fordperfect",
    "displayName": "Ford Perfect",
    "email": "fordperfect@galaxy.com",
    "groupIds": ["some-optional-group-id"]
}'

In diesem Beispiel geben wir groupIds für die Zugriffskontrolle an, aber dies ist optional.

SSOUser Erstellen Anfragestruktur

Copy

interface SSOUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Erstellen Antwortstruktur

Copy

interface SSOUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the created user on success.
}

Integrationshinweis

Daten, die über die API übergeben werden, können einfach überschrieben werden, indem ein anderer SSO-Benutzer-HMAC-Payload übergeben wird. Wenn Sie beispielsweise einen Benutzernamen über die API setzen, aber dann einen anderen über den SSO-Flow beim Laden der Seite übergeben, aktualisieren wir automatisch ihren Benutzernamen.

Wir aktualisieren keine Benutzerparameter in diesem Flow, es sei denn, Sie geben sie explizit an oder setzen sie auf null (nicht undefined).

PUT /api/v1/sso-users/:id

Resource: SSOUser as PUT /api/v1/sso-users Credit Cost: 1

Diese Route bietet die Möglichkeit, einen einzelnen SSO-Benutzer zu aktualisieren.

SSOUser Aktualisieren cURL Beispiel

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "fordperfect",
    "displayName": "Ford Perfect",
    "email": "fordperfect@galaxy.com",
    "groupIds": ["some-optional-group-id"]
}'

In diesem Beispiel geben wir groupIds für die Zugriffskontrolle an, aber dies ist optional.

SSOUser Aktualisieren Anfragestruktur

Copy

interface SSOUserPutQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

SSOUser Aktualisieren Antwortstruktur

Copy

interface SSOUserPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the update user on success.
}

DELETE /api/v1/sso-users/:id

Resource: SSOUser as DELETE /api/v1/sso-users/:id Credit Cost: 1

Diese Route ermöglicht das Entfernen eines einzelnen SSO-Benutzers nach seiner ID.

Beachten Sie, dass das erneute Laden des Kommentar-Widgets mit einem Payload für diesen Benutzer den Benutzer einfach nahtlos neu erstellt.

Das Löschen der Kommentare des Benutzers ist über den deleteComments-Abfrageparameter möglich. Beachten Sie, dass wenn dies wahr ist:

Alle Kommentare des Benutzers werden live gelöscht.
Alle untergeordneten (nun verwaisten) Kommentare werden basierend auf der zugehörigen Seitenkonfiguration jedes Kommentars gelöscht oder anonymisiert. Wenn beispielsweise der Thread-Löschmodus "anonymisieren" ist, bleiben Antworten erhalten und die Kommentare des Benutzers werden anonymisiert. Dies gilt nur, wenn commentDeleteMode Remove ist (der Standardwert).
Die creditsCost wird zu 2.

Anonymisierte Kommentare

Sie können die Kommentare des Benutzers behalten, aber einfach anonymisieren, indem Sie commentDeleteMode=1 setzen.

Wenn die Kommentare des Benutzers anonymisiert werden, werden die folgenden Werte auf null gesetzt:

- commenterName
- commenterEmail
- avatarSrc
- userId
- anonUserId
- mentions
- badges

isDeleted und isDeletedUser wird auf true gesetzt.

Beim Rendern verwendet das Kommentar-Widget DELETED_USER_PLACEHOLDER (Standard: "[deleted]") für den Namen des Benutzers und DELETED_CONTENT_PLACEHOLDER für den Kommentar. Diese können über die Widget-Anpassungs-Benutzeroberfläche angepasst werden.

Beispiele

SSOUser Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/sso-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Entfernen Anfragestruktur

Copy

enum SSOUserCommentDeleteMode {
    Remove = 0, // default
    Anonymize = 1
}
interface SSOUsersDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** You can set this to true to also delete the user's comments. This will double the credit cost. **/
    deleteComments?: 'true' | 'false'
    /** You can set this as desired to determine how to handle the user's comments. **/
    commentDeleteMode?: SSOUserCommentDeleteMode
}

SSOUser Entfernen Antwortstruktur

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the removed user on success.
}

Abonnement-Struktur

Ein Subscription-Objekt repräsentiert ein Abonnement für einen Benutzer.

Subscription-Objekte werden erstellt, wenn ein Benutzer auf das Benachrichtigungsglocken-Symbol im Kommentar-Widget klickt und "Diese Seite abonnieren" auswählt.

Abonnements können auch über die API erstellt werden.

Das Vorhandensein eines Subscription-Objekts bewirkt, dass Notification-Objekte generiert und E-Mails gesendet werden, wenn neue Kommentare am Wurzelknoten der zugehörigen Seite hinterlassen werden, für die das Subscription gilt. Das Senden von E-Mails hängt vom Benutzertyp ab. Für reguläre Benutzer hängt dies von optedInNotifications ab. Für SSO-Benutzer hängt dies von optedInSubscriptionNotifications ab. Beachten Sie, dass einige Anwendungen möglicherweise kein Konzept einer webzugänglichen Seite haben, in diesem Fall setzen Sie urlId einfach auf die ID des Elements, das Sie abonnieren (derselbe Wert für urlId, den Sie an das Kommentar-Widget übergeben würden).

Die Struktur des Subscription-Objekts ist wie folgt:

Abonnement Struktur

Copy

interface Subscription {
    id: string
    tenantId: string
    /** With SSO, the user id is in the format `<tenant id>:<user id>`. **/
    userId: string
    anonUserId?: string
    urlId: string
    url?: string
    pageTitle?: string
    createdAt: string // date string
}

GET /api/v1/subscriptions/:id

Resource: Subscription as GET /api/v1/subscriptions Credit Cost: 1

Diese Route gibt bis zu 30 Subscription-Objekte zurück, sortiert nach createdAt, neueste zuerst.

Sie können nach userId filtern. Bei SSO hat die Benutzer-ID das Format <tenant id>:<user id>.

Abonnements für Benutzer cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/subscriptions?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID'

Abonnements Anfragestruktur

Copy

interface SubscriptionsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Paginate by skipping records. **/
    skip?: number
    /** Filter by user. **/
    userId?: string
}

Abonnements Antwortstruktur

Copy

interface SubscriptionsGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    subscriptions?: Subscription[]
}

POST /api/v1/subscriptions

Resource: Subscription as POST /api/v1/subscriptions Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, ein Subscription zu erstellen. Beachten Sie, dass ein Benutzer nur ein Abonnement pro Seite haben kann, da mehr redundant ist, und der Versuch, mehr als ein Abonnement für denselben Benutzer für dieselbe Seite zu erstellen, führt zu einem Fehler.

Das Erstellen eines Abonnements führt dazu, dass Notification-Objekte erstellt werden, wenn ein neuer Kommentar am Wurzelknoten der abonnierten urlId hinterlassen wird (wenn parentId des Kommentars null ist).

Abonnement POST cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/subscriptions?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "tenantId:test-user-id",
    "urlId": "some-page-id-or-url",
    "url": "https://example.com/page",
    "pageTitle": "Some Example Page!"
}'

Abonnement POST Anfragestruktur

Copy

interface SubscriptionPostQueryParams {
    tenantId: string
    API_KEY: string
}

Abonnement POST Antwortstruktur

Copy

interface SubscriptionPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/subscriptions/:id

Resource: Subscription as DELETE /api/v1/subscriptions Credit Cost: 1

Diese Route löscht ein einzelnes Subscription-Objekt nach ID.

Abonnement Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/subscriptions/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Abonnement Entfernen Anfragestruktur

Copy

interface SubscriptionsDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Abonnement Entfernen Antwortstruktur

Copy

interface SubscriptionDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

Struktur der täglichen Mandantennutzung

Ein TenantDailyUsage-Objekt repräsentiert die Nutzung für einen Tenant an einem bestimmten Tag. Wenn es keine Aktivität für einen bestimmten Tenant an einem bestimmten Tag gab, wird dieser Tag kein TenantDailyUsage-Objekt haben.

Das TenantDailyUsage-Objekt ist nicht in Echtzeit und kann einige Minuten hinter der tatsächlichen Nutzung zurückliegen.

Die Struktur des TenantDailyUsage-Objekts ist wie folgt:

TenantDailyUsage Struktur

Copy

export interface TenantDailyUsage {
    yearNumber: number
    monthNumber: number
    dayNumber: number
    commentFetchCount?: number
    commentCreateCount?: number
    conversationCreateCount?: number
    voteCount?: number
    accountCreatedCount?: number
    userMentionSearch?: number
    hashTagSearch?: number
    gifSearchTrending?: number
    gifSearch?: number
    apiCreditsUsed?: number
    createdAt: string
    billed: boolean
    /** Ignored for billing. **/
    ignored: boolean
}

GET /api/v1/tenant-daily-usage

Resource: TenantDailyUsage as GET /api/v1/tenant-daily-usage Credit Cost: 1

Diese Route ermöglicht die Suche nach der Nutzung eines Tenants nach Jahr, Monat und Tag. Es können bis zu 365 Objekte zurückgegeben werden, und die Kosten betragen 1 API-Credit pro 10 Objekte.

Antwortobjekte sind nach ihrem Erstellungsdatum sortiert (die ältesten zuerst).

TenantDailyUsage Suche cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-daily-usage?tenantId=demo&API_KEY=DEMO_API_SECRET&yearNumber=2022&monthNumber=2&dayNumber=10'

TenantDailyUsage Anfragestruktur

Copy

interface TenantDailyUsageQueryParams {
    tenantId: string
    API_KEY: string
    /** Based on UTC. **/
    yearNumber?: number
    /** Zero-based. Based on UTC. **/
    monthNumber?: number
    /** One-based. Based on UTC. **/
    dayNumber?: number
}

TenantDailyUsage Antwortstruktur

Copy

interface TenantDailyUsageResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    tenantDailyUsages: TenantDailyUsage[]
}

Mandantenstruktur

Der Tenant definiert einen FastComments.com-Kunden. Sie können über die API von Tenants mit White-Labeling-Zugang erstellt werden. White-Label-Tenants können keine anderen White-Label-Tenants erstellen (nur eine Verschachtelungsebene ist erlaubt).

Die Struktur des Tenant-Objekts ist wie folgt:

Tenant Struktur

Copy

export enum SiteType {
    Unknown = 0,
    WordPress = 1
}
/** This can also be handled via the DomainConfig API. **/
export interface TenantDomainConfig {
    domain: string
    emailFromName?: string
    emailFromEmail?: string
    createdAt?: string,
    siteType?: FastCommentsSiteType, // you probably want Unknown
    logoSrc?: string, // raw image path
    logoSrc100px?: string, // resized for thumbnails
    footerUnsubscribeURL?: string,
    emailHeaders?: Record<string, string>,
    disableUnsubscribeLinks?: boolean,
    dkim?: {
        domainName: string,
        keySelector: string,
        privateKey: string
    }
}
export interface TenantBillingInfo {
    name: string
    address: string
    city: string
    state: string
    zip: string
    country: string
}
export enum TenantPaymentFrequency {
    Monthly = 0,
    Annually = 1
}
export interface Tenant {
    id: string
    name: string
    email?: string
    signUpDate: number; // number due to "legacy" reasons
    packageId?: string | null
    paymentFrequency?: TenantPaymentFrequency
    billingInfoValid?: boolean
    billingHandledExternally?: boolean
    createdBy?: string
    isSetup?: boolean
    domainConfiguration: FastCommentsAPITenantDomainConfig[]
    billingInfo?: FastCommentsAPITenantBillingInfo
    stripeCustomerId?: string
    stripeSubscriptionId?: string
    stripePlanId?: string
    enableProfanityFilter?: boolean
    enableSpamFilter?: boolean
    lastBillingIssueReminderDate?: string
    removeUnverifiedComments?: boolean
    unverifiedCommentsTTLms?: number
    commentsRequireApproval?: boolean
    autoApproveCommentOnVerification?: boolean
    sendProfaneToSpam?: boolean
    /** @readonly - Is calculated based on packageId. **/
    hasFlexPricing?: boolean
    /** @readonly **/
    flexLastBilledAmount?: number
    /** @readonly - Is calculated based on packageId. **/
    hasAuditing?: boolean
    /** You can store a key value pair with the tenant which you can use to query. Keys cannot contain "." or "$", or be longer than 100 chars. Values may not be longer than 2k chars. **/
    meta?: Record<string, string | null>
}

GET /api/v1/tenants/:id

Resource: Tenant as GET /api/v1/tenants/:id Credit Cost: 1

Diese Route gibt einen einzelnen Tenant nach ID zurück.

Tenant nach ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Tenant Anfragestruktur

Copy

interface TenantByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant Antwortstruktur

Copy

interface TenantByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
    tenant?: Tenant
}

GET /api/v1/tenants

Resource: Tenant as GET /api/v1/tenants Credit Cost: 1

Diese API gibt Tenants zurück, die von Ihrem Tenant verwaltet werden.

Die Paginierung wird durch den skip-Abfrageparameter bereitgestellt. Tenants werden in Seiten von 100 zurückgegeben, sortiert nach signUpDate und id.

Die Kosten basieren auf der Anzahl der zurückgegebenen Tenants und betragen 1 Credit pro 10 zurückgegebene Tenants.

Tenant cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

Sie können meta-Parameter für die Tenant-Objekte definieren und nach passenden Tenants abfragen. Zum Beispiel können wir für den Schlüssel someKey und den Meta-Wert some-value ein JSON-Objekt mit diesem Schlüssel/Wert-Paar erstellen und es dann als Abfrageparameter URI-kodieren, um zu filtern:

Tenant Abfrage nach Meta cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET&meta=%7B%22someKey%22%3A%22some-value%22%7D'

Tenant Anfragestruktur

Copy

interface TenantsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenants to skip for pagination. **/
    skip?: number
    /** Filter by meta params. **/
    meta?: string
}

Tenant Antwortstruktur

Copy

interface TenantsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenants?: Tenant[]
}

POST /api/v1/tenants

Resource: Tenant as POST /api/v1/tenants Credit Cost: 1

Diese Route bietet die Möglichkeit, einen einzelnen Tenant hinzuzufügen.

Das Erstellen eines Tenant hat die folgenden Einschränkungen:

Ein name ist erforderlich.
domainConfiguration ist erforderlich.
Die folgenden Werte dürfen beim Erstellen eines Tenant nicht angegeben werden:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
Das signUpDate darf nicht in der Zukunft liegen.
Der name darf nicht länger als 200 Zeichen sein.
Die email darf nicht länger als 300 Zeichen sein.
Die email muss über alle FastComments.com-Tenants hinweg eindeutig sein.
Sie können keine Tenants erstellen, wenn der übergeordnete Tenant kein gültiges TenantPackage definiert hat.
- Wenn Ihr Tenant über FastComments.com erstellt wurde, sollte dies kein Problem sein.
Sie können nicht mehr Tenants erstellen als unter maxWhiteLabeledTenants in Ihrem Paket definiert.
Sie müssen den tenantId-Abfrageparameter angeben, der die ID Ihres übergeordneten Tenants mit aktiviertem White Labeling ist.

Wir können einen Tenant mit nur wenigen Parametern erstellen:

Tenant Erstellen cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com",
    "domainConfiguration": [ { "domain": "somedomain.com" } ]
}'

Tenant Erstellen Anfragestruktur

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant Erstellen Antwortstruktur

Copy

interface TenantPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'
    /** Included on failure. **/
    reason?: string
    tenant?: Tenant; // We return the complete created tenant on success.
}

PATCH /api/v1/tenants/:id

Resource: Tenant as PATCH /api/v1/tenants/:id Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, einen Tenant nach id zu aktualisieren.

Das Aktualisieren eines Tenant hat die folgenden Einschränkungen:

Die folgenden Werte können nicht aktualisiert werden:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
- managedByTenantId
Das signUpDate darf nicht in der Zukunft liegen.
Der name darf nicht länger als 200 Zeichen sein.
Die email darf nicht länger als 300 Zeichen sein.
Die email muss über alle FastComments.com-Tenants hinweg eindeutig sein.
Wenn billingInfoValid auf true gesetzt wird, muss billingInfo in derselben Anfrage angegeben werden.
Sie können die packageId, die mit Ihrem eigenen Tenant verknüpft ist, nicht aktualisieren.
Sie können die paymentFrequency, die mit Ihrem eigenen Tenant verknüpft ist, nicht aktualisieren.

Tenant PATCH cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

Tenant PATCH Anfragestruktur

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant PATCH Antwortstruktur

Copy

interface TenantPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info';
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/tenants/:id

Resource: Tenant as DELETE /api/v1/tenants/:id Credit Cost: 1,000

Diese Route ermöglicht das Entfernen eines Tenant und aller zugehörigen Daten (Benutzer, Kommentare usw.) nach ID.

Die folgenden Einschränkungen gelten für das Entfernen von Tenants:

Der Tenant muss Ihr eigener oder ein White-Label-Tenant sein, den Sie verwalten.
Der sure-Abfrageparameter muss auf true gesetzt sein.

Tenant Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Tenant Entfernen Anfragestruktur

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant Entfernen Antwortstruktur

Copy

interface TenantDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'unsure'
    /** Included on failure. **/
    reason?: string
}

Struktur des Mandantenpakets

Das TenantPackage definiert Paketinformationen, die einem Tenant zur Verfügung stehen. Ein Tenant kann viele Pakete zur Verfügung haben, aber nur eines zu einem bestimmten Zeitpunkt nutzen.

Ein Tenant kann für keine Produkte verwendet werden, bis seine packageId auf ein gültiges TenantPackage verweist.

Es gibt zwei Arten von TenantPackage-Objekten:

Pakete mit Festpreisen - wobei hasFlexPricing false ist.
Flexible Preisgestaltung - wobei hasFlexPricing true ist.

In beiden Fällen werden Limits für das Konto definiert, das das Paket verwendet, jedoch wird bei Flex dem Tenant ein Grundpreis plus die Nutzung berechnet, definiert durch die flex*-Parameter.

Ein Tenant kann mehrere Tenant-Pakete haben und die Möglichkeit haben, das Paket selbst von der Abrechnungsinfo-Seite zu ändern.

Wenn Sie die Abrechnung für Tenants selbst übernehmen, müssen Sie dennoch ein Paket für jeden Tenant definieren, um deren Limits festzulegen. Setzen Sie einfach billingHandledExternally auf true beim Tenant und sie werden nicht in der Lage sein, ihre Abrechnungsinformationen oder das aktive Paket selbst zu ändern.

Sie dürfen keine Pakete mit höheren Limits als der übergeordnete Tenant erstellen.

Die Struktur des TenantPackage-Objekts ist wie folgt:

TenantPackage Struktur

Copy

export interface TenantPackage {
    id: string
    name: string
    tenantId: string
    createdAt: string
    monthlyCostUSD: number
    yearlyCostUSD: number
    monthlyStripePlanId?: string
    yearlyStripePlanId?: string
    maxMonthlyPageLoads: number
    maxMonthlyAPICredits: number
    maxMonthlyComments: number
    maxConcurrentUsers: number
    maxTenantUsers: number
    maxSSOUsers: number
    maxModerators: number
    maxDomains: number
    maxWhiteLabeledTenants: number
    hasWhiteLabeling: boolean
    hasDebranding: boolean
    forWhoText: string
    featureTaglines: string[]
    hasAuditing: boolean
    hasFlexPricing: boolean
    flexPageLoadCostCents?: null
    flexPageLoadUnit?: null
    flexCommentCostCents?: null
    flexCommentUnit?: null
    flexSSOUserCostCents?: null // Cost per regular SSO user (without admin/moderator permissions)
    flexSSOUserUnit?: null
    flexAPICreditCostCents?: null
    flexAPICreditUnit?: null
    flexModeratorCostCents?: null
    flexModeratorUnit?: null
    flexAdminCostCents?: null
    flexAdminUnit?: null
    flexDomainCostCents?: null
    flexDomainUnit?: null
    flexSSOAdminCostCents?: null // Cost per SSO user with admin permissions (isAccountOwner or isAdminAdmin flags)
    flexSSOAdminUnit?: null
    flexSSOModeratorCostCents?: null // Cost per SSO user with moderator permissions (isCommentModeratorAdmin flag)
    flexSSOModeratorUnit?: null
    flexMinimumCostCents?: null
}

GET /api/v1/tenant-packages/:id

Resource: TenantPackage as GET /api/v1/tenant-packages/:id Credit Cost: 1

Diese Route gibt ein einzelnes Tenant-Paket nach ID zurück.

TenantPackage nach ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantPackage Anfragestruktur

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage Antwortstruktur

Copy

interface TenantPackageByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    tenantPackage: TenantPackage
}

GET /api/v1/tenant-packages

Resource: TenantPackage as GET /api/v1/tenant-packages Credit Cost: 1

Diese API verwendet Paginierung, bereitgestellt durch den skip-Abfrageparameter. TenantPackages werden in Seiten von 100 zurückgegeben, sortiert nach createdAt und id.

Die Kosten basieren auf der Anzahl der zurückgegebenen Tenant-Pakete und betragen 1 Credit pro 10 zurückgegebene Tenant-Pakete.

TenantPackage cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

TenantPackage Anfragestruktur

Copy

interface TenantPackagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenant packages to skip for pagination. **/
    skip?: number
}

TenantPackage Antwortstruktur

Copy

interface TenantPackagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenantPackages?: TenantPackage[]
}

POST /api/v1/tenant-packages

Resource: TenantPackage as POST /api/v1/tenant-packages Credit Cost: 1

Diese Route bietet die Möglichkeit, ein einzelnes TenantPackage hinzuzufügen.

Das Erstellen eines TenantPackage hat die folgenden Einschränkungen:

Die folgenden Parameter sind erforderlich:
- name
- tenantId
- monthlyCostUSD - Kann null sein.
- yearlyCostUSD - Kann null sein.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - Wenn true, sind alle flex*-Parameter erforderlich.
Der name darf nicht länger als 50 Zeichen sein.
Jedes forWhoText-Element darf nicht länger als 200 Zeichen sein.
Jedes featureTaglines-Element darf nicht länger als 100 Zeichen sein.
Das TenantPackage muss "kleiner" als der übergeordnete Tenant sein. Beispielsweise müssen alle max*-Parameter niedrigere Werte als der übergeordnete Tenant haben.
Ein White-Label-Tenant darf maximal fünf Pakete haben.
Nur Tenants mit White-Labeling-Zugang können ein TenantPackage erstellen.
Sie können keine Pakete zu Ihrem eigenen Tenant hinzufügen. :)

Wir können ein TenantPackage wie folgt erstellen:

TenantPackage Erstellen per E-Mail cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Default Package",
  "tenantId": "some-child-tenant-id",
  "monthlyCostUSD": null,
  "yearlyCostUSD": null,
  "maxMonthlyPageLoads": 50000,
  "maxMonthlyAPICredits": 50000,
  "maxMonthlyComments": 50000,
  "maxConcurrentUsers": 50000,
  "maxTenantUsers": 10,
  "maxSSOUsers": 50000,
  "maxModerators": 100,
  "maxDomains": 3,
  "hasWhiteLabeling": false,
  "hasDebranding": true,
  "forWhoText": "For Everyone",
  "featureTaglines": [
    "Some Tag",
    "Some Other Tag"
  ],
  "hasFlexPricing": true,
  "flexPageLoadCostCents": 100,
  "flexPageLoadUnit": 100000,
  "flexCommentCostCents": 100,
  "flexCommentUnit": 100000,
  "flexSSOUserCostCents": 100,
  "flexSSOUserUnit": 1000,
  "flexAPICreditCostCents": 100,
  "flexAPICreditUnit": 50000,
  "flexModeratorCostCents": 500,
  "flexModeratorUnit": 1,
  "flexAdminCostCents": 1000,
  "flexAdminUnit": 1,
  "flexDomainCostCents": 1000,
  "flexDomainUnit": 1,
  "flexMinimumCostCents": 99
}'

TenantPackage Erstellen Anfragestruktur

Copy

interface TenantPackagePostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage Erstellen Antwortstruktur

Copy

interface TenantPackagePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'
    /** Included on failure. **/
    reason?: string
    tenantPackage?: TenantPackage; // We return the complete created tenant package on success.
}

PATCH /api/v1/tenant-packages/:id

Resource: TenantPackage as PATCH /api/v1/tenant-packages/:id Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, ein TenantPackage nach id zu aktualisieren.

Das Aktualisieren eines TenantPackage hat die folgenden Einschränkungen:

Wenn Sie hasFlexPricing auf true setzen, sind alle flex*-Parameter in derselben Anfrage erforderlich.
Der name darf nicht länger als 50 Zeichen sein.
Jedes forWhoText-Element darf nicht länger als 200 Zeichen sein.
Jedes featureTaglines-Element darf nicht länger als 100 Zeichen sein.
Das TenantPackage muss "kleiner" als der übergeordnete Tenant sein. Beispielsweise müssen alle max*-Parameter niedrigere Werte als der übergeordnete Tenant haben.
Sie können die mit einem TenantPackage verknüpfte tenantId nicht ändern.

TenantPackage PATCH cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

TenantPackage PATCH Anfragestruktur

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage PATCH Antwortstruktur

Copy

interface TenantPackagePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param';
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/tenant-packages/:id

Resource: TenantPackage as DELETE /api/v1/tenant-packages/:id Credit Cost: 5

Diese Route ermöglicht das Entfernen eines TenantPackage nach ID.

Sie können ein TenantPackage nicht entfernen, das in Verwendung ist (wenn die packageId eines Tenants auf das Paket verweist). Aktualisieren Sie zuerst den Tenant.

TenantPackage Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantPackage Entfernen Anfragestruktur

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage Entfernen Antwortstruktur

Copy

interface TenantPackageDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'package-in-use'
    /** Included on failure. **/
    reason?: string
}

Mandantenbenutzer-Struktur

Der TenantUser definiert einen User, der von einem bestimmten Tenant verwaltet wird. Sein Konto steht vollständig unter der Kontrolle des Tenants, mit dem er verknüpft ist, und sein Konto kann über die Benutzeroberfläche oder API aktualisiert oder gelöscht werden.

Tenant-Benutzer können Administratoren mit allen Berechtigungen und Zugriff auf den Tenant sein, oder sie können auf bestimmte Berechtigungen beschränkt sein, um Kommentare zu moderieren, auf API-Schlüssel zuzugreifen usw.

Die Struktur des TenantUser-Objekts ist wie folgt:

TenantUser Struktur

Copy

/** This is for notifications. **/
export enum UserDigestEmailFrequency {
    Disabled = -1,
    Daily = 0,
    Weekly = 1,
    Monthly = 2
}
export interface TenantUser {
    id: string
    tenantId: string
    username: string
    /** A link to the commenter's blog, for example. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    verified: boolean
    loginCount: number
    optedInNotifications: boolean
    optedInTenantNotifications: boolean
    hideAccountCode: boolean
    avatarSrc?: string
    /** Does the user receive help requests from commenters? **/
    isHelpRequestAdmin: boolean
    isAccountOwner: boolean
    isAdminAdmin: boolean
    isBillingAdmin: boolean
    isAnalyticsAdmin: boolean
    isCustomizationAdmin: boolean
    isManageDataAdmin: boolean
    isCommentModeratorAdmin: boolean
    isAPIAdmin: boolean
    moderatorIds: string[]
    locale: FastCommentsLocale
    digestEmailFrequency: UserDigestEmailFrequency
    lastLoginDate: string
    displayLabel?: string
    karma?: number
}

GET /api/v1/tenant-users/:id

Resource: TenantUser as GET /api/v1/tenant-users/:id Credit Cost: 1

Diese Route gibt einen einzelnen TenantUser nach ID zurück.

TenantUser nach ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantUser Anfragestruktur

Copy

interface TenantUserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Antwortstruktur

Copy

interface TenantUserByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
    tenantUser?: TenantUser
}

GET /api/v1/tenant-users

Resource: TenantUser as GET /api/v1/tenant-users Credit Cost: 1

Diese API verwendet Paginierung, bereitgestellt durch den skip-Abfrageparameter. TenantUsers werden in Seiten von 100 zurückgegeben, sortiert nach signUpDate, username und id.

Die Kosten basieren auf der Anzahl der zurückgegebenen Tenant-Benutzer und betragen 1 Credit pro 10 zurückgegebene Tenant-Benutzer.

TenantUser cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-users?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

TenantUser Anfragestruktur

Copy

interface TenantUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenant users to skip for pagination. **/
    skip?: number
}

TenantUser Antwortstruktur

Copy

interface TenantUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenantUsers?: TenantUser[]
}

POST /api/v1/tenant-users

Resource: TenantUser as POST /api/v1/tenant-users Credit Cost: 1

Diese Route bietet die Möglichkeit, einen einzelnen TenantUser hinzuzufügen.

Das Erstellen eines TenantUser hat die folgenden Einschränkungen:

Ein username ist erforderlich.
Eine email ist erforderlich.
Das signUpDate darf nicht in der Zukunft liegen.
Die locale muss in der Liste der Unterstützten Locales enthalten sein.
Der username muss über alle FastComments.com hinweg eindeutig sein. Wenn dies ein Problem ist, empfehlen wir stattdessen SSO zu verwenden.
Die email muss über alle FastComments.com hinweg eindeutig sein. Wenn dies ein Problem ist, empfehlen wir stattdessen SSO zu verwenden.
Sie können nicht mehr Tenant-Benutzer erstellen als unter maxTenantUsers in Ihrem Paket definiert.

Wir können einen TenantUser wie folgt erstellen

TenantUser Erstellen cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Some Name",
    "email": "someone@someone.com"
}'

TenantUser Erstellen Anfragestruktur

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Erstellen Antwortstruktur

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'username-required' | 'email-required' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'tenant-user-limit-reached'
    /** Included on failure. **/
    reason?: string
    tenantUser?: TenantUser; // We return the complete created tenant user on success.
}

Resource: TenantUser as POST /api/v1/tenant-users/:id/send-login-link Credit Cost: 10

Diese Route bietet die Möglichkeit, einen Login-Link an einen einzelnen TenantUser zu senden.

Nützlich beim Batch-Erstellen von Benutzern, ohne ihnen erklären zu müssen, wie sie sich bei FastComments.com anmelden. Dies sendet ihnen einfach einen "Magic Link" zum Anmelden, der nach 30 Tagen abläuft.

Die folgenden Einschränkungen gelten für das Senden eines Login-Links an einen TenantUser:

Der TenantUser muss bereits existieren.
Sie müssen Zugriff haben, um den Tenant zu verwalten, zu dem der TenantUser gehört.

Wir können wie folgt einen Login-Link an einen TenantUser senden:

TenantUser Login-Link cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz/send-login-link?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

Dies sendet eine E-Mail wie Bob bei TenantName lädt Sie ein, Moderator zu werden...

TenantUser Login-Link Anfragestruktur

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Login-Link Antwortstruktur

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

PATCH /api/v1/tenant-users/:id

Resource: TenantUser as PATCH /api/v1/tenant-users/:id Credit Cost: 1

Diese Route bietet die Möglichkeit, einen einzelnen TenantUser zu aktualisieren.

Das Aktualisieren eines TenantUser hat die folgenden Einschränkungen:

Das signUpDate darf nicht in der Zukunft liegen.
Die locale muss in der Liste der Unterstützten Locales enthalten sein.
Der username muss über alle FastComments.com hinweg eindeutig sein. Wenn dies ein Problem ist, empfehlen wir stattdessen SSO zu verwenden.
Die email muss über alle FastComments.com hinweg eindeutig sein. Wenn dies ein Problem ist, empfehlen wir stattdessen SSO zu verwenden.
Sie können die tenantId eines Benutzers nicht aktualisieren.

Wir können einen TenantUser wie folgt erstellen

TenantUser Aktualisieren cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Some Name",
    "email": "someone@someone.com"
}'

TenantUser Aktualisieren Anfragestruktur

Copy

interface TenantUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

TenantUser Aktualisieren Antwortstruktur

Copy

interface TenantUserPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'unauthorized' | 'no-package' | 'invalid-package' | 'tenant-user-limit-reached' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/tenant-users/:id

Resource: TenantUser as DELETE /api/v1/tenant-users/:id Credit Cost: 5

Diese Route ermöglicht das Entfernen eines TenantUser nach ID.

Das Löschen der Kommentare des Benutzers ist über den deleteComments-Abfrageparameter möglich. Beachten Sie, dass wenn dieser true ist:

Alle Kommentare des Benutzers werden live gelöscht.
Alle Kind-Kommentare (jetzt verwaist) werden basierend auf der zugehörigen Seitenkonfiguration jedes Kommentars gelöscht oder anonymisiert. Wenn beispielsweise der Thread-Löschmodus "anonymisieren" ist, bleiben Antworten erhalten, und die Kommentare des Benutzers werden anonymisiert. Dies gilt nur, wenn commentDeleteMode Remove ist (der Standardwert).
Die creditsCost wird 2.

Anonymisierte Kommentare

Sie können die Kommentare des Benutzers behalten, aber einfach anonymisieren, indem Sie commentDeleteMode=1 setzen.

Wenn die Kommentare des Benutzers anonymisiert werden, werden die folgenden Werte auf null gesetzt:

- commenterName
- commenterEmail
- avatarSrc
- userId
- anonUserId
- mentions
- badges

isDeleted und isDeletedUser werden auf true gesetzt.

Beispiele

TenantUser Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantUser Entfernen Anfragestruktur

Copy

enum TenantUserCommentDeleteMode {
    Remove = 0, // default
    Anonymize = 1
}
interface TenantUserDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** You can set this to true to also delete the user's comments. This will double the credit cost. **/
    deleteComments?: 'true' | 'false'
    /** You can set this as desired to determine how to handle the user's comments. **/
    commentDeleteMode?: TenantUserCommentDeleteMode
}

TenantUser Entfernen Antwortstruktur

Copy

interface TenantUserDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
}

Benutzerstruktur

User ist ein Objekt, das den kleinsten gemeinsamen Nenner aller Benutzer darstellt.

Beachten Sie, dass wir bei FastComments verschiedene Anwendungsfälle für Benutzer haben:

Secure SSO
Simple SSO
Tenant-Benutzer (zum Beispiel: Administratoren)
Kommentierende

Diese API ist für Kommentierende und Benutzer, die über Simple SSO erstellt wurden. Grundsätzlich kann über diese API auf jeden Benutzer zugegriffen werden, der über Ihre Seite erstellt wurde. Tenant-Benutzer können auch auf diese Weise abgerufen werden, aber Sie erhalten mehr Informationen durch Interaktion mit der /tenant-users/-API.

Für Secure SSO verwenden Sie bitte die /sso-users/-API.

Sie können diese Arten von Benutzern nicht aktualisieren. Sie haben ihr Konto über Ihre Seite erstellt, daher bieten wir einen grundlegenden schreibgeschützten Zugang, aber Sie können keine Änderungen vornehmen. Wenn Sie diesen Flow haben möchten, müssen Sie Secure SSO einrichten.

Die Struktur des User-Objekts ist wie folgt:

User Struktur

Copy

export interface User {
    /** This is also the id used as userId on comment objects. **/
    id: string
    username: string
    /** A link to the commenter's blog, for example. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    avatarSrc?: string
    locale: FastCommentsLocale
    displayLabel?: string
    karma?: number
}

GET /api/v1/users/:id

Resource: User as GET /api/v1/users/:id Credit Cost: 1

Diese Route gibt einen einzelnen User nach ID zurück.

User nach ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

User Anfragestruktur

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

User Antwortstruktur

Copy

interface UserByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
    user?: User
}

Stimmenstruktur

Ein Vote-Objekt repräsentiert eine Abstimmung, die von einem Benutzer hinterlassen wurde.

Die Beziehung zwischen Kommentaren und Abstimmung wird über commentId definiert.

Die Struktur des Vote-Objekts ist wie folgt:

Vote Struktur

Copy

interface Vote {
    id: string
    urlId: string
    commentId: string
    userId: string
    direction: 1 | -1
    createdAt: string
}

GET /api/v1/votes

Resource: Vote as GET /api/v1/votes Credit Cost: 10

Abstimmungen müssen nach urlId abgerufen werden.

Arten von Abstimmungen

Es gibt drei Arten von Abstimmungen:

Authentifizierte Abstimmungen, die auf den entsprechenden Kommentar angewendet werden. Diese können Sie über diese API erstellen.
Authentifizierte Abstimmungen, die auf Verifizierung warten, und daher noch nicht auf den Kommentar angewendet wurden. Diese werden erstellt, wenn ein Benutzer den FastComments.com-Login-zum-Abstimmen-Mechanismus verwendet.
Anonyme Abstimmungen, die auf den entsprechenden Kommentar angewendet werden. Diese werden zusammen mit anonymen Kommentaren erstellt.

Diese werden in separaten Listen in der API zurückgegeben, um Verwirrung zu vermeiden.

Votes cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test'

Votes Anfragestruktur

Copy

interface VotesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
}

Votes Antwortstruktur

Copy

interface VotesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    /** Authorized, verified votes, applied to their corresponding comments. **/
    appliedAuthorizedVotes: Vote[]
    /** Anonymous votes, applied to their corresponding comments. **/
    appliedAnonymousVotes: Vote[]
    /** Votes pending verification, not yet applied to their corresponding comments. **/
    pendingVotes: Vote[]
}

Hinweise zu anonymen Abstimmungen

Beachten Sie, dass anonyme Abstimmungen, die über diese API erstellt werden, in der appliedAuthorizedVotes-Liste erscheinen. Sie gelten als autorisiert, da sie über die API mit einem API-Schlüssel erstellt wurden.

Die appliedAnonymousVotes-Struktur ist für Abstimmungen, die ohne E-Mail, API-Schlüssel usw. erstellt wurden.

GET /api/v1/votes/for-user

Resource: Vote as GET /api/v1/votes/for-user Credit Cost: 1

Ermöglicht das Abrufen von Abstimmungen, die von einem Benutzer für eine bestimmte urlId hinterlassen wurden. Nimmt eine userId entgegen, die jeder FastComments.com- oder SSO-Benutzer sein kann.

Dies ist nützlich, wenn Sie zeigen möchten, ob ein Benutzer für einen Kommentar abgestimmt hat. Wenn Sie Kommentare abrufen, rufen Sie diese API einfach gleichzeitig für den Benutzer mit der gleichen urlId auf.

Wenn Sie anonyme Abstimmungen verwenden, möchten Sie stattdessen anonUserId übergeben.

Votes für Benutzer cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&userId=some-user-id'

Votes für anonymen Benutzer cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&anonUserId=some-user-id'

Beachten Sie, dass anonyme Abstimmungen in der appliedAuthorizedVotes-Liste erscheinen. Sie gelten als autorisiert, da sie über die API mit einem API-Schlüssel erstellt wurden.

Votes für Benutzer Anfragestruktur

Copy

interface VotesForUserRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
    userId?: string
    anonUserId?: string
}

Votes für Benutzer Antwortstruktur

Copy

interface VotesForUserResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'invalid-user-id'
    /** Included on failure. **/
    reason?: string
    /** Authorized, verified votes, applied to their corresponding comments. **/
    appliedAuthorizedVotes: Vote[]
    /** Votes pending verification, not yet applied to their corresponding comments. **/
    pendingVotes: Vote[]
}

POST /api/v1/votes

Resource: Vote as POST /api/v1/votes Credit Cost: 1

Diese Route bietet die Möglichkeit, ein einzelnes autorisiertes Vote hinzuzufügen. Abstimmungen können up (+1) oder down (-1) sein.

Vote Erstellen cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=user-id&commentId=comment-id&direction=up' \
  --header 'Content-Type: application/json'

Anonymes Vote Erstellen cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-randomly-generated-identifier&commentId=comment-id&direction=up' \
  --header 'Content-Type: application/json'

Vote Erstellen Anfragestruktur

Copy

interface VotePostQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentId: string
    direction: 'up' | 'down'
}

Vote Erstellen Antwortstruktur

Copy

interface VotePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-user-id' | 'invalid-user-id' | 'invalid-comment-id' | 'invalid-direction' | 'duplicate' | 'voting-disabled'
    /** Included on failure. **/
    reason?: string
    voteId?: string
}

Erstellen anonymer Abstimmungen

Anonyme Abstimmungen können erstellt werden, indem in den Abfrageparametern anonUserId anstelle von userId gesetzt wird.

Diese ID muss keinem Benutzerobjekt irgendwo entsprechen (daher anonym). Es ist einfach ein Bezeichner für die Sitzung, damit Sie Abstimmungen in derselben Sitzung erneut abrufen können, um zu prüfen, ob für einen Kommentar abgestimmt wurde.

Wenn Sie so etwas wie "anonyme Sitzungen" nicht haben, wie FastComments es hat, können Sie dies einfach auf eine zufällige ID setzen, wie eine UUID (obwohl wir kleinere Bezeichner schätzen, um Platz zu sparen).

Weitere Hinweise

Diese API befolgt Einstellungen auf Tenant-Ebene. Wenn Sie beispielsweise das Abstimmen für eine bestimmte Seite deaktivieren und versuchen, über die API eine Abstimmung zu erstellen, schlägt dies mit dem Fehlercode voting-disabled fehl.
Diese API ist standardmäßig live.
Diese API aktualisiert die votes des entsprechenden Comment.

DELETE /api/v1/votes/:id

Resource: Vote as DELETE /api/v1/votes/:id Credit Cost: 1

Diese Route bietet die Möglichkeit, ein einzelnes Vote zu löschen.

Vote Löschen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/votes/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

Vote Löschen Anfragestruktur

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Vote Löschen Antwortstruktur

Copy

interface VoteDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id'
    /** Included on failure. **/
    reason?: string
}

Hinweise:

Diese API befolgt Einstellungen auf Tenant-Ebene. Wenn Sie beispielsweise das Abstimmen für eine bestimmte Seite deaktivieren und versuchen, über die API eine Abstimmung zu erstellen, schlägt dies mit dem Fehlercode voting-disabled fehl.
Diese API ist standardmäßig live.
Diese API aktualisiert die votes des entsprechenden Comment.

Struktur der Domain-Konfiguration

Ein DomainConfig-Objekt stellt die Konfiguration für eine Domain eines Mandanten dar.

Die Struktur des DomainConfig-Objekts ist wie folgt:

Struktur der Domain-Konfiguration

Copy

interface DomainConfig {
    /** Eine Domain, keine URL, z. B. "fastcomments.com" oder "www.example.com". Ein Subdomain-Anteil kann eingeschlossen werden, wenn die Einschränkung auf eine Subdomain gewünscht ist. Maximal 1000 Zeichen. **/
    domain: string
    /** Der Absendername, der beim Versenden von E-Mails verwendet wird. **/
    emailFromName?: string
    /** Die Absender-E-Mail, die beim Versenden von E-Mails verwendet wird. Stellen Sie sicher, dass SPF eingerichtet ist, um mail.fastcomments.com das Versenden von E-Mails im Namen der in diesem Attribut verwendeten Domain zu erlauben. **/
    emailFromEmail?: string
    /** SCHREIBGESCHÜTZT. Wann das Objekt erstellt wurde. **/
    createdAt: string
    /** Das zur Domain gehörige Logo. Wird in E-Mails verwendet. Verwenden Sie HTTPS. **/
    logoSrc?: string
    /** Ein kleineres zur Domain gehörendes Logo. Verwenden Sie HTTPS. **/
    logoSrc100px?: string
    /** NUR SSO. Die URL, die in der Fußzeile jeder gesendeten E-Mail verwendet wird. Unterstützt eine "[userId]"-Variable. **/
    footerUnsubscribeURL?: string
    /** NUR SSO. Die Header, die in jeder gesendeten E-Mail verwendet werden. Nützlich beispielsweise zum Setzen von unsubscribe-bezogenen Headern zur Verbesserung der Zustellbarkeit. Der List-Unsubscribe-Eintrag in diesem Record, falls vorhanden, unterstützt eine "[userId]"-Variable. **/
    emailHeaders?: Record<string, string>
    /** Alle Abmeldelinks deaktivieren. Nicht empfohlen, kann die Zustellraten beeinträchtigen. **/
    disableUnsubscribeLinks?: boolean
    /** DKIM-Konfiguration. **/
    dkim?: DomainConfigDKIM
}

Struktur der DKIM-Konfiguration

Copy

interface DomainConfigDKIM {
    /** Der Domain-Name in Ihrem DKIM-Eintrag. **/
    domainName: string
    /** Der DKIM-Key-Selector, der verwendet werden soll. **/
    keySelector: string
    /** Der öffentliche Schlüssel im PEM-Format. Wird in GET-Antworten zurückgegeben. **/
    publicKey: string
    /** @deprecated Wird nicht mehr in API-Antworten zurückgegeben. Beim Schreiben aus Gründen der Abwärtskompatibilität akzeptiert. **/
    privateKey?: string
}

Für die Authentifizierung

Die Domain-Konfiguration wird verwendet, um zu bestimmen, welche Websites das FastComments-Widget für Ihr Konto hosten können. Dies ist eine grundlegende Form der Authentifizierung, was bedeutet, dass das Hinzufügen oder Entfernen von Domain-Konfigurationen die Verfügbarkeit Ihrer FastComments-Installation in der Produktion beeinträchtigen kann.

Entfernen oder aktualisieren Sie nicht die domain-Eigenschaft einer Domain Config für eine Domain, die derzeit verwendet wird, es sei denn, das Deaktivieren dieser Domain ist beabsichtigt.

Dies hat das gleiche Verhalten wie das Entfernen einer Domain über /auth/my-account/configure-domains.

Beachten Sie auch, dass das Entfernen einer Domain aus der My Domains-Benutzeroberfläche alle entsprechenden Konfigurationen für diese Domain entfernt, die möglicherweise über diese Benutzeroberfläche hinzugefügt wurden.

Für E-Mail-Anpassungen

Der Abmeldelink in der E-Mail-Fußzeile und die One-Click-Abmeldefunktion, die viele E-Mail-Clients anbieten, können über diese API konfiguriert werden, indem jeweils footerUnsubscribeURL und emailHeaders definiert werden.

Für DKIM

Nachdem Sie Ihre DKIM-DNS-Einträge definiert haben, aktualisieren Sie einfach das DomainConfig mit Ihrer DKIM-Konfiguration unter Verwendung der definierten Struktur.

GET /api/v1/domain-configs

Resource: Comment as GET /api/v1/domain-configs Credit Cost: 1

Diese API bietet die Möglichkeit, alle DomainConfig-Objekte für einen Tenant abzurufen.

DomainConfig GET cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'

DomainConfig GET Anfragestruktur

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig GET Antwortstruktur

Copy

interface GetDomainConfigsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The configurations! **/
    configurations: DomainConfig[] | null
}

GET /api/v1/domain-configs/:domain

Resource: DomainConfig as GET /api/v1/domain-configs/:domain Credit Cost: 1

Einzelne DomainConfigs können nach ihrer entsprechenden domain abgerufen werden.

Domain-Konfiguration nach Domain cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

Domain-Konfiguration nach Domain Anfragestruktur

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Domain-Konfiguration nach Domain Antwortstruktur

Copy

interface DomainConfigResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-domain' | 'update-would-create-duplicate' | 'domain-does-not-exist'
    /** Included on failure. **/
    reason?: string
    configuration?: DomainConfig | null
}

POST /api/v1/domain-configs

Resource: DomainConfig as POST /api/v1/domain-configs Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, Domain-Konfigurationen zu erstellen.

Das Hinzufügen einer Konfiguration für eine Domain autorisiert diese Domain für das FastComments-Konto.

Häufige Anwendungsfälle dieser API sind die Ersteinrichtung, wenn viele Domains hinzugefügt werden sollen, oder benutzerdefinierte Konfigurationen für den E-Mail-Versand.

DomainConfig POST cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "example.com",
    "emailFromName": "some from name",
    "emailFromEmail": "some@test.com",
    "logoSrc": "https://example.com/my-logo-big.png",
    "logoSrc100px": "https://example.com/my-logo-100px.png",
    "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
    "emailHeaders": {
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
        "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
    }
}'

DomainConfig POST Anfragestruktur

Copy

interface DomainConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig POST Antwortstruktur

Copy

interface DomainConfigPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'configuration-exists-for-domain' | 'domain-too-long' | 'domain-invalid';
    /** Included on failure. **/
    reason?: string
    /** The created configuration. **/
    configuration?: DomainConfig
}

PATCH /api/v1/domain-configs/:domain

Resource: DomainConfig as PATCH /api/v1/domain-configs/:domain Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, eine Domain-Konfiguration zu aktualisieren, indem nur die Domain und das zu aktualisierende Attribut angegeben werden.

DomainConfig PATCH cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailFromName": "Some New From Name",
}'

DomainConfig PATCH Anfragestruktur

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PATCH Antwortstruktur

Copy

interface DomainConfigPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';
    /** Included on failure. **/
    reason?: string
    /** The updated configuration. **/
    configuration?: DomainConfig
}

PUT /api/v1/domain-configs/:domain

Resource: DomainConfig as PUT /api/v1/domain-configs/:domain Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, eine Domain-Konfiguration zu ersetzen.

DomainConfig PUT cURL Beispiel

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "new-domain-example.com",
    "emailFromName": "some from name",
    "emailFromEmail": "some@test.com",
    "logoSrc": "https://example.com/my-logo-big.png",
    "logoSrc100px": "https://example.com/my-logo-100px.png",
    "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
    "emailHeaders": {
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
        "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
    }
}'

DomainConfig PUT Anfragestruktur

Copy

interface DomainConfigPutQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PUT Antwortstruktur

Copy

interface DomainConfigPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';
    /** Included on failure. **/
    reason?: string
    /** The updated configuration. **/
    configuration?: DomainConfig
}

DELETE /api/v1/domain-configs/:domain

Resource: DomainConfig as DELETE /api/v1/domain-configs/:domain Credit Cost: 1

Diese Route ermöglicht das Entfernen einer einzelnen DomainConfig nach ID.

Hinweis: Das Entfernen einer DomainConfig wird die Autorisierung dieser Domain für FastComments aufheben.
Hinweis: Das erneute Hinzufügen einer Domain über die Benutzeroberfläche erstellt das Objekt neu (nur mit domain befüllt).

DomainConfig Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

DomainConfig Entfernen Anfragestruktur

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig Entfernen Antwortstruktur

Copy

interface DomainConfigDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-domain' | 'domain-config-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

Struktur der Fragekonfiguration

FastComments bietet eine Möglichkeit, Fragen zu konstruieren und ihre Ergebnisse zu aggregieren. Ein Beispiel für eine Frage (im Folgenden QuestionConfig genannt) könnte eine Sternebewertung, ein Schieberegler oder eine NPS-Frage sein (bestimmt durch type).

Fragedaten können einzeln, zusammen, über Zeit, insgesamt, nach Seite usw. aggregiert werden.

Das Framework hat alle Fähigkeiten, die benötigt werden, um clientseitige Widgets (mit Ihrem Server vor dieser API), Admin-Dashboards und Reporting-Tools zu erstellen.

Zuerst müssen wir eine QuestionConfig definieren. Die Struktur ist wie folgt:

QuestionConfig Struktur

Copy

type QuestionConfigType = 'nps' | 'slider' | 'star' | 'thumbs';
interface QuestionConfig {
    id: string
    tenantId: string
    name: string
    question: string
    helpText?: string
    createdAt: string
    createdBy: string
    /** READONLY - incremented for each new response. **/
    usedCount: number
    /** A date string for when the configuration was last used (result left). **/
    lastUsed?: string
    type: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder: number
}

GET /api/v1/question-configs

Resource: QuestionConfig as GET /api/v1/question-configs Credit Cost: 1

Diese Route gibt bis zu 100 QuestionConfig-Objekte auf einmal zurück, paginiert. Die Kosten betragen 1 pro 100 Objekte. Sie sind nach Fragetext aufsteigend sortiert (question-Feld).

QuestionConfig Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionConfig Anfragestruktur

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
    /** For pagination. Starts at 0. **/
    skip?: number
}

QuestionConfig Antwortstruktur

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    questionConfigs: QuestionConfig[]
}

GET /api/v1/question-configs/:id

Resource: QuestionConfig as GET /api/v1/question-configs/:id Credit Cost: 1

Diese Route gibt eine einzelne QuestionConfig nach ihrer ID zurück.

QuestionConfig nach ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-configs/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionConfig Anfragestruktur

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig Antwortstruktur

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    questionConfig?: QuestionConfig
}

POST /api/v1/question-configs

Resource: QuestionConfig as POST /api/v1/question-configs Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, eine QuestionConfig zu erstellen.

QuestionConfig POST cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some name that shows on reports.",
    "question": "how much do you like this api?",
    "type": 'slider',
    "reportingOrder": 0,
    "min": 0,
    "max": 10
}'

QuestionConfig POST Anfragestruktur

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig POST Antwortstruktur

Copy

interface QuestionConfigPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';
    /** Included on failure. **/
    reason?: string
    /** The created object. **/
    questionConfig?: QuestionConfig
}

PATCH /api/v1/question-configs/:id

Resource: QuestionConfig as PATCH /api/v1/question-configs/:id Credit Cost: 1

Diese Route bietet die Möglichkeit, eine einzelne QuestionConfig zu aktualisieren.

Die folgende Struktur repräsentiert alle Werte, die geändert werden können:

QuestionConfig Struktur

Copy

interface QuestionConfigPatchBody {
    name?: string
    question?: string
    helpText?: string
    /** Beware! Changing type may throw off reporting if min/max is different. **/
    type?: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder?: number
}

QuestionConfig Aktualisieren cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/question-configs/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "question": "some new question text"
}'

QuestionConfig Aktualisieren Anfragestruktur

Copy

interface QuestionConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig Aktualisieren Antwortstruktur

Copy

interface QuestionConfigPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/question-configs/:id

Resource: QuestionConfig as DELETE /api/v1/question-configs/:id Credit Cost: 100

Diese Route ermöglicht das Entfernen einer QuestionConfig nach ID.

Dies löscht alle entsprechenden Frageergebnisse (aber nicht die Kommentare). Dies ist Teil der hohen Credit-Kosten.

QuestionConfig Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/question-configs/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionConfig Entfernen Anfragestruktur

Copy

interface QuestionConfigDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig Entfernen Antwortstruktur

Copy

interface QuestionConfigResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

Struktur des Frageergebnisses

Um Ergebnisse für Fragen zu speichern, erstellen Sie ein QuestionResult. Sie können dann Frageergebnisse aggregieren und sie auch zu Berichtszwecken mit Kommentaren verknüpfen.

QuestionResult Struktur

Copy

interface QuestionResultMeta {
    name: string
    values: string[]
}
interface QuestionResult {
    id: string
    tenantId: string
    urlId: string
    anonUserId?: string
    userId?: string
    createdAt?: string
    value: number
    commentId?: string
    questionId: string
    meta?: QuestionResultMeta[]
}

GET /api/v1/question-results

Resource: QuestionResults as GET /api/v1/question-results Credit Cost: 1

Diese Route gibt bis zu 1000 QuestionResults-Objekte auf einmal zurück, paginiert. Die Kosten betragen 1 pro 100 Objekte. Sie sind nach createdAt aufsteigend sortiert. Sie können nach verschiedenen Parametern filtern.

QuestionResults Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionResults Anfragestruktur

Copy

interface QuestionResultsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** For pagination. Starts at 0. **/
    skip?: number
    /** For pagination. **/
    limit?: number
    /** Get the results from a specific page. **/
    urlId?: string
    /** Get the results from a specific user. **/
    userId?: string
    startDate?: string | number
    questionId?: string | string[]
}

QuestionResults Antwortstruktur

Copy

interface QuestionResultsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    questionResults: QuestionResults[]
}

GET /api/v1/question-results/:id

Resource: QuestionResult as GET /api/v1/question-results/:id Credit Cost: 1

Diese Route gibt ein einzelnes QuestionResult nach seiner ID zurück.

QuestionResult nach ID cURL Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionResult Anfragestruktur

Copy

interface QuestionResultRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult Antwortstruktur

Copy

interface QuestionResultByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    questionResult?: QuestionResult
}

POST /api/v1/question-results

Resource: QuestionResult as POST /api/v1/question-results Credit Cost: 1

Dieser API-Endpunkt bietet die Möglichkeit, ein QuestionResult zu erstellen.

QuestionResult POST cURL Beispiel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "urlId": "some-page-id",
    "anonUserId": 'anon-0',
    "userId": 'user-0',
    "value": 10,
    "questionId": "some-question-id",
    "meta": [
        {
            name: "example",
            values: ["value-1", "value-2"]
        }
    ]
}'

QuestionResult POST Anfragestruktur

Copy

interface QuestionResultPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult POST Antwortstruktur

Copy

interface QuestionResultPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';
    /** Included on failure. **/
    reason?: string
    /** The created object. **/
    questionResult?: QuestionResult
}

PATCH /api/v1/question-results/:id

Resource: QuestionResult as PATCH /api/v1/question-results/:id Credit Cost: 1

Diese Route bietet die Möglichkeit, ein einzelnes QuestionResult zu aktualisieren.

Die folgende Struktur repräsentiert alle Werte, die geändert werden können:

QuestionResult Struktur

Copy

interface QuestionResultPatchBody {
    urlId?: string
    anonUserId?: string
    userId?: string
    value?: string
    commentId?: string
    questionId?: string
    meta?: QuestionResultMeta[]
}

QuestionResult Aktualisieren cURL Beispiel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/question-results/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "value": 5
}'

QuestionResult Aktualisieren Anfragestruktur

Copy

interface QuestionResultPatchQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult Aktualisieren Antwortstruktur

Copy

interface QuestionResultPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/question-results/:id

Resource: QuestionResult as DELETE /api/v1/question-results/:id Credit Cost: 1

Diese Route ermöglicht das Entfernen eines QuestionResult nach ID.

QuestionResult Entfernen cURL Beispiel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/question-results/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionResult Entfernen Anfragestruktur

Copy

interface QuestionResultDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult Entfernen Antwortstruktur

Copy

interface QuestionResultResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

GET /api/v1/question-results-aggregate

Resource: QuestionResultsAggregate as GET /api/v1/question-results-aggregate Credit Cost: 2

Hier findet die Aggregation von Ergebnissen statt.

Die Aggregations-Antwortstruktur ist wie folgt:

QuestionResultsAggregationResult Struktur

Copy

interface QuestionResultDataPoint {
    /** A map of value to count of occurrences of that value for the current data point (date bucket or page). **/
    v: Map<ValueAsString, number>
    total: number
}
interface QuestionResultsAggregationResult {
    /** Note - is null when timeBucket not specified. **/
    dataByDateBucket?: Map<DateString, QuestionResultDataPoint>
    dataByUrlId?: Map<URLIdString, QuestionResultDataPoint>
    countsByValue?: Map<ValueAsString, number>
    /** The total number of results aggregated. **/
    total: number
    /** The resulting weighted average. It is a float, usually two decimals or fewer. **/
    average: number
    /** A date string representing when this data was calculated, since it might come from cache. **/
    createdAt: string
}

Hier sind die für die Aggregation verfügbaren Abfrageparameter:

QuestionResultsAggregation Anfragestruktur

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** You can aggregate results for one or more questions. **/
    questionId: string | string[]
    startDate?: string | number
    timeBucket?: 'day' | 'month' | 'year'
    /** Aggregate for a specific page. **/
    urlId?: string
    /** Aggregate for a specific user. **/
    userId?: string
    /** Force recalculate now and update the cache. **/
    forceRecalculate?: boolean
}

Hier ist ein Beispiel für eine Anfrage:

QuestionResultsAggregation Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results-aggregation?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id'

Beispielantwort:

QuestionResultsAggregation Antwort Beispiel

Copy

    {
        "average": 8.33,
        "countsByValue": {
            "5": 1,
            "10": 2
        },
        "createdAt": "2023-08-30T00:00:00.000Z",
        "dataByUrlId": {
            "some-page": {
                "total": 3,
                "v": {
                    "5": 1,
                    "10": 2
                }
            }
        },
        "total": 3
    }

QuestionResultsAggregation Antwortstruktur

Copy

interface QuestionResultsAggregationResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    data: QuestionResultsAggregationResult
}

Leistungshinweise

Bei einem Cache-Miss dauern Aggregationen in der Regel fünf Sekunden pro Million Ergebnisse.
Ansonsten sind Anfragen in konstanter Zeit.

Caching- und Kostenhinweise

Wenn forceRecalculate angegeben wird, betragen die Kosten immer 10 anstelle der normalen 2.
Wenn der Cache abläuft und Daten neu berechnet werden, betragen die Kosten immer noch konstant 2, wenn forceRecalculate nicht angegeben ist. Der Cache läuft basierend auf der aggregierten Datensatzgröße ab (kann zwischen 30 Sekunden und 5 Minuten variieren).
Dies soll die Nutzung des Caches fördern.

GET /api/v1/question-results-aggregate/combine/comments

Resource: QuestionResultsCombinedWithComments as GET /api/v1/question-results-aggregate/combine/comments Credit Cost: 2

Hier findet die Kombination von Ergebnissen mit Kommentaren statt. Nützlich zum Beispiel für die Erstellung eines "letzte positive und negative Kommentare"-Diagramms für ein Produkt.

Sie können über einen Wertebereich (inklusive), eine oder mehrere Fragen und nach einem Startdatum (inklusive) suchen.

Die Antwortstruktur ist wie folgt:

QuestionResultsCombinedWithCommentsResponse Struktur

Copy

interface SimpleComment {
    id: string
    commenterName: string
    userId?: string
    date: string
    commentHTML: string
}
interface SimpleQuestionResult {
    id: string
    value: number
}
interface CommentAndResult {
    comment: SimpleComment
    result: SimpleQuestionResult
}
interface QuestionResultsCombinedWithCommentsResponse {
    /** A date string representing when this data was calculated, since it might come from cache. **/
    createdAt: string
    results: CommentAndResult[]
}

Hier sind die für die Aggregation verfügbaren Abfrageparameter:

QuestionResultsCombineComments Anfragestruktur

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** You can aggregate results for one or more questions. **/
    questionId: string | string[]
    startDate?: string | number
    urlId?: string
    minValue: number
    maxValue: number
    limit?: number
    forceRecalculate?: boolean
}

Hier ist ein Beispiel für eine Anfrage:

QuestionResultsCombineComments Beispiel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results-aggregation/combine/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id&minValue=5&maxValue=10'

Beispielantwort:

QuestionResultsCombineComments Antwort Beispiel

Copy

{
    "createdAt": "2023-08-30T00:00:00.000Z",
    "results": [
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-2",
                "commenterName": "Test",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 10
            }
        },
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-0",
                "commenterName": "Some Name",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 5
            }
        }
    ]
}

QuestionResultsCombineComments Antwortstruktur

Copy

interface QuestionResultsCombineCommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    data: QuestionResultsCombinedWithCommentsResponse
}

Caching- und Kostenhinweise

Wenn forceRecalculate angegeben wird, betragen die Kosten immer 10 anstelle der normalen 2.
Wenn der Cache abläuft und Daten neu berechnet werden, betragen die Kosten immer noch konstant 2, wenn forceRecalculate nicht angegeben ist.
Dies soll die Nutzung des Caches fördern.

Struktur des Benutzerabzeichens

UserBadge ist ein Objekt, das ein Abzeichen repräsentiert, das einem Benutzer im FastComments-System zugewiesen ist.

Abzeichen können Benutzern automatisch aufgrund ihrer Aktivität (z. B. Anzahl der Kommentare, Antwortzeit, Veteranenstatus) oder manuell von Website-Administratoren zugewiesen werden.

Die Struktur des UserBadge-Objekts ist wie folgt:

UserBadge-Struktur

Copy

export interface UserBadge {
    /** Eindeutige Kennung für diese Zuordnung des Benutzerabzeichens */
    id: string
    /** ID des Benutzers, dem dieses Abzeichen zugewiesen ist */
    userId: string
    /** ID der Abzeichendefinition aus dem Abzeichenkatalog des Mandanten */
    badgeId: string
    /** ID des Mandanten, der dieses Abzeichen erstellt/zugewiesen hat */
    fromTenantId: string
    /** Wann dieses Abzeichen erstellt wurde (Millisekunden seit Epoch) */
    createdAt?: number
    /** Wann dieses Abzeichen vom Benutzer erhalten wurde (Millisekunden seit Epoch) */
    receivedAt?: number
    /** 
     * Der Abzeichentyp: 
     * 0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, 3=CommentsPinned, 
     * 4=Veteran, 5=NightOwl, 6=FastReplyTime, 7=ModeratorCommentsDeleted,
     * 8=ModeratorCommentsApproved, 9=ModeratorCommentsUnapproved, 10=ModeratorCommentsReviewed,
     * 11=ModeratorCommentsMarkedSpam, 12=ModeratorCommentsMarkedNotSpam, 13=RepliedToSpecificPage,
     * 14=Manual
     */
    type: number
    /** Für schwellenbasierte Abzeichen der Schwellenwert */
    threshold?: number
    /** Der Name/Bezeichner des Abzeichens */
    name?: string
    /** Detaillierte Beschreibung des Abzeichens */
    description?: string
    /** Der auf dem Abzeichen angezeigte Text */
    displayLabel?: string
    /** URL zu einem auf dem Abzeichen angezeigten Bild */
    displaySrc?: string
    /** Hintergrundfarbe des Abzeichens (Hex-Code) */
    backgroundColor?: string
    /** Randfarbe des Abzeichens (Hex-Code) */
    borderColor?: string
    /** Textfarbe des Abzeichens (Hex-Code) */
    textColor?: string
    /** Zusätzliche CSS-Klasse zur Gestaltung */
    cssClass?: string
    /** Für Veteranen-Abzeichen die Zeitgrenze in Millisekunden */
    veteranUserThresholdMillis?: number
    /** Ob dieses Abzeichen in den Kommentaren des Benutzers angezeigt wird */
    displayedOnComments: boolean
    /** Die Anzeigereihenfolge des Abzeichens */
    order?: number
    /** Falls gesetzt, wird dieses Abzeichen nur auf der Seite mit der passenden urlId angezeigt. Null für globale Abzeichen. */
    urlId?: string | null
}

GET /api/v1/user-badges

Dieser Endpunkt ermöglicht das Abrufen von Benutzer-Badges basierend auf verschiedenen Kriterien.

Beispielanfrage:

GET Anfrage Beispiel

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET"

Sie können verschiedene Abfrageparameter hinzufügen, um die Ergebnisse zu filtern:

userId - Badges für einen bestimmten Benutzer abrufen
badgeId - Instanzen eines bestimmten Badges abrufen
type - Nach Badge-Typ filtern (0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, usw. Siehe UserBadge-Struktur für vollständige Liste)
displayedOnComments - Filtern, ob das Badge bei Kommentaren angezeigt wird (true/false)
limit - Maximale Anzahl der zurückzugebenden Badges (Standard 30, max 200)
skip - Anzahl der zu überspringenden Badges (für Paginierung)

Beispielantwort:

Antwort

Copy

{
  "status": "success",
  "userBadges": [
    {
      "id": "badge123",
      "userId": "user456",
      "badgeId": "badgeDef789",
      "fromTenantId": "tenant001",
      "createdAt": 1650532511000,
      "receivedAt": 1650532511000,
      "type": 14,
      "name": "Special Contributor",
      "description": "Awarded to special contributors to our community",
      "displayLabel": "Special",
      "backgroundColor": "#4a5568",
      "textColor": "#ffffff",
      "displayedOnComments": true,
      "order": 1
    },
    {
      "id": "badge124",
      "userId": "user456",
      "badgeId": "badgeDef790",
      "fromTenantId": "tenant001",
      "createdAt": 1650532598000,
      "receivedAt": 1650532598000,
      "type": 0,
      "threshold": 100,
      "name": "Centurion",
      "description": "Made 100 comments",
      "displayLabel": "100",
      "backgroundColor": "#2b6cb0",
      "textColor": "#ffffff",
      "displayedOnComments": true,
      "order": 2
    }
  ]
}

Mögliche Fehlerantworten:

Fehler: Fehlende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fehler: Ungültiges Limit

Copy

{
  "status": "failed",
  "code": "invalid-limit",
  "reason": "The limit (query param: limit) is too large (> 200)."
}

GET /api/v1/user-badges/:id

Dieser Endpunkt ermöglicht das Abrufen eines bestimmten Benutzer-Badges anhand seiner eindeutigen ID.

Beispielanfrage:

GET Anfrage Beispiel

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Beispielantwort:

Antwort

Copy

{
  "status": "success",
  "userBadge": {
    "id": "badge123",
    "userId": "user456",
    "badgeId": "badgeDef789",
    "fromTenantId": "tenant001",
    "createdAt": 1650532511000,
    "receivedAt": 1650532511000,
    "type": 14,
    "name": "Special Contributor",
    "description": "Awarded to special contributors to our community",
    "displayLabel": "Special",
    "backgroundColor": "#4a5568",
    "textColor": "#ffffff",
    "displayedOnComments": true,
    "order": 1
  }
}

Mögliche Fehlerantworten:

Fehler: Fehlende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fehler: Nicht gefunden

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

POST /api/v1/user-badges

Dieser Endpunkt ermöglicht das Erstellen einer neuen Benutzer-Badge-Zuweisung.

Beispielanfrage:

POST Anfrage Beispiel

Copy

Run

curl -X POST "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "userId": "user456",
  "badgeId": "badgeDef789",
  "displayedOnComments": true
}'

Der Anfragekörper muss die folgenden Parameter enthalten:

userId (erforderlich) - Die ID des Benutzers, dem das Badge zugewiesen werden soll
badgeId (erforderlich) - Die ID des zuzuweisenden Badges
displayedOnComments (optional) - Ob das Badge bei den Kommentaren des Benutzers angezeigt werden soll (standardmäßig true)

Wichtige Hinweise:

Das Badge muss existieren und im Badge-Katalog Ihres Tenants aktiviert sein
Sie können Badges nur Benutzern zuweisen, die zu Ihrem Tenant gehören oder auf Ihrer Seite kommentiert haben

Beispielantwort:

Antwort

Copy

{
  "status": "success",
  "userBadge": {
    "id": "badge123",
    "userId": "user456",
    "badgeId": "badgeDef789",
    "fromTenantId": "tenant001",
    "createdAt": 1650532511000,
    "receivedAt": 1650532511000,
    "type": 14,
    "name": "Special Contributor",
    "description": "Awarded to special contributors to our community",
    "displayLabel": "Special",
    "backgroundColor": "#4a5568",
    "textColor": "#ffffff",
    "displayedOnComments": true,
    "order": 1
  }
}

Mögliche Fehlerantworten:

Fehler: Fehlende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fehler: Fehlende Benutzer-ID

Copy

{
  "status": "failed",
  "code": "missing-user-id",
  "reason": "User ID (body param: userId) is required."
}

Fehler: Fehlende Badge-ID

Copy

{
  "status": "failed",
  "code": "missing-badge-id",
  "reason": "Badge ID (body param: badgeId) is required."
}

Fehler: Badge nicht gefunden

Copy

{
  "status": "failed",
  "code": "badge-not-found",
  "reason": "The badge badgeDef789 was not found or is not enabled."
}

Fehler: Nicht autorisierter Benutzer

Copy

{
  "status": "failed",
  "code": "unauthorized-user",
  "reason": "You can only add badges to users who belong to your tenant or have commented on your site."
}

PUT /api/v1/user-badges/:id

Dieser Endpunkt ermöglicht das Aktualisieren einer Benutzer-Badge-Zuweisung.

Derzeit ist die einzige Eigenschaft, die aktualisiert werden kann, displayedOnComments, die steuert, ob das Badge bei den Kommentaren des Benutzers angezeigt wird.

Beispielanfrage:

PUT Anfrage Beispiel

Copy

Run

curl -X PUT "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "displayedOnComments": false
}'

Beispielantwort:

Antwort

Copy

{
  "status": "success"
}

Mögliche Fehlerantworten:

Fehler: Fehlende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fehler: Fehlende ID

Copy

{
  "status": "failed",
  "code": "missing-id",
  "reason": "The User Badge ID (url param: id) is missing."
}

Fehler: Nicht gefunden

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

DELETE /api/v1/user-badges/:id

Dieser Endpunkt ermöglicht das Löschen einer Benutzer-Badge-Zuweisung.

Beispielanfrage:

DELETE Anfrage Beispiel

Copy

Run

curl -X DELETE "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Beispielantwort:

Antwort

Copy

{
  "status": "success"
}

Mögliche Fehlerantworten:

Fehler: Fehlende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fehler: Fehlende ID

Copy

{
  "status": "failed",
  "code": "missing-id",
  "reason": "The User Badge ID (url param: id) is missing."
}

Fehler: Nicht gefunden

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

Struktur des Fortschritts bei Benutzerabzeichen

UserBadgeProgress ist ein Objekt, das den Fortschritt eines Benutzers beim Verdienen verschiedener Badges im FastComments-System darstellt.

Diese Verfolgung hilft zu bestimmen, wann Benutzer automatische Badges basierend auf ihrer Aktivität und Teilnahme in Ihrer Community erhalten sollten.

Die Struktur des UserBadgeProgress-Objekts ist wie folgt:

UserBadgeProgress Struktur

Copy

export interface UserBadgeProgress {
    /** Unique identifier for this progress record */
    id: string
    /** ID of the tenant this progress record belongs to */
    tenantId: string
    /** ID of the user this progress record tracks */
    userId: string
    /** ID of the user's first comment in the system */
    firstCommentId?: string
    /** Date of the user's first comment (milliseconds since epoch) */
    firstCommentDate?: number
    /** Automatically calculated trust factor based on user activity */
    autoTrustFactor?: number
    /** Manually set trust factor by administrators */
    manualTrustFactor?: number
    /** Detailed progress object with various metrics, keys match BadgeType enum */
    progress: {
        /** 0: CommentCount - Count of comments the user has made */
        '0'?: number
        /** 1: CommentUpVotes - Count of upvotes the user has received */
        '1'?: number
        /** 2: CommentReplies - Count of replies the user has made */
        '2'?: number
        /** 3: CommentsPinned - Count of pinned comments the user has */
        '3'?: number
        /** 4: Veteran - User's account age */
        '4'?: number
        /** 5: NightOwl - Times user has posted during nighttime hours */
        '5'?: number
        /** 6: FastReplyTime - Average reply time in milliseconds */
        '6'?: number
        /** 7: ModeratorCommentsDeleted - For moderator badges, comments deleted count */
        '7'?: number
        /** 8: ModeratorCommentsApproved - For moderator badges, comments approved count */
        '8'?: number
        /** 9: ModeratorCommentsUnapproved - For moderator badges, comments unapproved count */
        '9'?: number
        /** 10: ModeratorCommentsReviewed - For moderator badges, comments reviewed count */
        '10'?: number
        /** 11: ModeratorCommentsMarkedSpam - For moderator badges, comments marked as spam count */
        '11'?: number
        /** 12: ModeratorCommentsMarkedNotSpam - For moderator badges, comments marked as not spam count */
        '12'?: number
        /** 13: RepliedToSpecificPage - For each page, count of replies */
        '13'?: Record<string, number>
    }
}

GET /api/v1/user-badge-progress

Dieser Endpunkt ermöglicht das Abrufen von Benutzer-Badge-Fortschrittseinträgen basierend auf verschiedenen Kriterien.

Beispielanfrage:

GET Anfrage Beispiel

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress?tenantId=demo&API_KEY=DEMO_API_SECRET"

Sie können verschiedene Abfrageparameter hinzufügen, um die Ergebnisse zu filtern:

userId - Fortschritt für einen bestimmten Benutzer abrufen
limit - Maximale Anzahl der zurückzugebenden Einträge (Standard 30, max 200)
skip - Anzahl der zu überspringenden Einträge (für Paginierung)

Beispielantwort:

Antwort

Copy

{
  "status": "success",
  "userBadgeProgresses": [
    {
      "id": "progress123",
      "tenantId": "tenant001",
      "userId": "user456",
      "firstCommentId": "comment789",
      "firstCommentDate": 1650532511000,
      "autoTrustFactor": 0.75,
      "progress": {
        "0": 42,
        "1": 120,
        "2": 15,
        "3": 3,
        "5": 5,
        "6": 1800000,
        "8": 0,
        "7": 0
      }
    },
    {
      "id": "progress124",
      "tenantId": "tenant001",
      "userId": "user789",
      "firstCommentId": "comment790",
      "firstCommentDate": 1650532598000,
      "autoTrustFactor": 0.5,
      "progress": {
        "0": 12,
        "1": 15,
        "2": 4
      }
    }
  ]
}

Mögliche Fehlerantworten:

Fehler: Fehlende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fehler: Ungültiges Limit

Copy

{
  "status": "failed",
  "code": "invalid-limit",
  "reason": "The limit (query param: limit) is too large (> 200)."
}

GET /api/v1/user-badge-progress/:id

Dieser Endpunkt ermöglicht das Abrufen eines bestimmten Benutzer-Badge-Fortschrittseintrags anhand seiner eindeutigen ID.

Beispielanfrage:

GET Anfrage Beispiel

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/progress123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Beispielantwort:

Antwort

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

Mögliche Fehlerantworten:

Fehler: Fehlende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fehler: Nicht gefunden

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge progress progress123 was not found."
}

GET /api/v1/user-badge-progress/user/:userId

Dieser Endpunkt ermöglicht das Abrufen des Badge-Fortschrittseintrags eines Benutzers anhand seiner Benutzer-ID.

Beispielanfrage:

GET Anfrage Beispiel

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/user/user456?tenantId=demo&API_KEY=DEMO_API_SECRET"

Beispielantwort:

Antwort

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

Mögliche Fehlerantworten:

Fehler: Fehlende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fehler: Fehlende Benutzer-ID

Copy

{
  "status": "failed",
  "code": "missing-user-id",
  "reason": "The User ID (path param: userId) is missing."
}

Fehler: Nicht gefunden

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "No badge progress found for user user456 in tenant tenant001."
}

Abschließend

Wir hoffen, dass Sie unsere API-Dokumentation als umfassend und leicht verständlich empfunden haben. Wenn Sie Lücken feststellen, lassen Sie es uns unten wissen.

Sprache 🇩🇪 Deutsch

API-Ressourcen

Aggregationen

Audit-Logs

Kommentare

E-Mail-Vorlagen

Hashtags

Moderatoren

Anzahl der Benachrichtigungen

Benachrichtigungen

Seiten

Ausstehende Webhook-Ereignisse

SSO-Benutzer

Abonnements

Tägliche Mandantennutzung

Mandanten

Mandantenpakete

Mandantenbenutzer

Benutzer

Abstimmungen

Domain-Konfigurationen

Fragekonfigurationen

Frageergebnisse

Aggregation von Frageergebnissen

Benutzerabzeichen

Fortschritt bei Benutzerabzeichen

Die FastComments API

Generierte SDKs

Authentifizierung

Sicherheitshinweis

Authentifizierungsoption Eins - Header

Authentifizierungsoption Zwei - Query-Parameter

API-Ressourcen

Ressourcennutzung

Hinweis!

Daten aggregieren

Beispiele

Beispiel: Eindeutige Werte zählen

Beispiel: Distinct Count

Beispiel: Werte mehrerer Felder summieren

Beispiel: Durchschnittswerte mehrerer Felder

Beispiel: Min/Max-Werte mehrerer Felder

Beispiel: Eindeutige Werte mehrerer Felder zählen

Beispiel: Abfrageerstellung

Beispiel: Kommentare zur Überprüfung zählen

Beispiel: Aufschlüsselung von genehmigten, überprüften und Spam-Kommentaren

Strukturen

Audit-Log-Struktur

GET /api/v1/audit-logs

Kommentarstruktur

Kommentartext-Struktur

Tagging

HashTags

GET /api/v1/comments

Paginierung

Threads

Bäume erklärt

Kommentare im Kontext eines Benutzers abrufen

Kommentare als Baum abrufen

Kommentare als Baum abrufen, Suche nach Hash-Tag

Alle Anfrageparameter

Die Antwort

Hilfreiche Tipps

URL-ID

Anonyme Aktionen

Kommentare werden nicht zurückgegeben

GET /api/v1/comments/:id

POST /api/v1/comments

PATCH /api/v1/comments/:id

DELETE /api/v1/comments/:id

POST /api/v1/comments/:id/flag

POST /api/v1/comments/:id/un-flag

POST /api/v1/comments/:id/block

POST /api/v1/comments/:id/un-block

Struktur der E-Mail-Vorlage

Hinweise

GET /api/v1/email-templates/:id

GET /api/v1/email-templates

PATCH /api/v1/email-templates/:id

POST /api/v1/email-templates